cbrowser 16.5.0 → 16.7.1

package/docs/PERSONA-QUESTIONNAIRE.md

@@ -0,0 +1,322 @@
+# Persona Questionnaire System
+
+**Introduced in v16.6.0**
+
+The Persona Questionnaire system provides research-backed trait mapping for creating custom cognitive personas. Instead of defaulting traits to 0.5 (neutral baseline), this system uses behavioral questions to derive differentiated trait profiles.
+
+## The Problem
+
+When creating custom personas, AI-generated profiles often defaulted many traits to 0.5. This creates "average" personas that don't accurately represent real user diversity.
+
+## The Solution
+
+The questionnaire system:
+1. Maps behavioral answers to trait values (0-1 scale)
+2. Uses 5 distinct behavioral levels per trait (0, 0.25, 0.5, 0.75, 1.0)
+3. Applies research-backed correlations between traits
+4. Provides behavioral descriptions based on academic research
+
+## Quick Start
+
+### CLI Usage
+
+```bash
+# Interactive 8-question questionnaire
+npx cbrowser persona-questionnaire start
+
+# Comprehensive 25-trait questionnaire
+npx cbrowser persona-questionnaire start --comprehensive --name "my-persona"
+
+# Look up trait behavior at specific value
+npx cbrowser persona-questionnaire lookup --trait patience --value 0.25
+
+# List all available traits
+npx cbrowser persona-questionnaire list-traits
+```
+
+### Programmatic Usage
+
+```typescript
+import {
+  generatePersonaQuestionnaire,
+  buildTraitsFromAnswers,
+  getTraitBehaviors,
+  getTraitLabel,
+} from 'cbrowser';
+
+// Generate questionnaire
+const questionnaire = generatePersonaQuestionnaire({ comprehensive: false });
+
+// Build traits from answers
+const traits = buildTraitsFromAnswers({
+  patience: 0.25,
+  riskTolerance: 0.75,
+  curiosity: 1.0,
+});
+
+// Look up specific trait behavior
+const behaviors = getTraitBehaviors('patience', 0.25);
+console.log(behaviors.label);       // "Low"
+console.log(behaviors.behaviors);   // ["Gets frustrated quickly", ...]
+```
+
+### MCP Tools
+
+Three MCP tools are available:
+
+| Tool | Description |
+|------|-------------|
+| `persona_questionnaire_get` | Generate questionnaire questions |
+| `persona_questionnaire_build` | Build trait profile from answers |
+| `persona_trait_lookup` | Look up behaviors for trait value |
+
+## The 25 Cognitive Traits
+
+| Trait | Research Basis | What It Models |
+|-------|---------------|----------------|
+| **patience** | UX research | Time before abandoning on friction |
+| **riskTolerance** | Prospect theory | Willingness to try unfamiliar actions |
+| **comprehension** | Cognitive load theory | UI pattern understanding |
+| **persistence** | Motivation research | Retry behavior after failures |
+| **curiosity** | Exploration theory | Feature discovery tendency |
+| **workingMemory** | Cognitive psychology | Multi-step task handling |
+| **readingTendency** | Eye-tracking studies | Text consumption behavior |
+| **resilience** | Positive psychology | Bounce-back from errors |
+| **selfEfficacy** | Bandura (1977) | Belief in problem-solving ability |
+| **satisficing** | Simon (1956) | Accept "good enough" vs optimize |
+| **trustCalibration** | Fogg (2003) | Trust in unfamiliar interfaces |
+| **interruptRecovery** | Mark et al. (2005) | Resume after distractions |
+| **decisionFatigue** | Baumeister | Decision quality over time |
+| **internalAttribution** | Attribution theory | Self-blame for failures |
+| **externalAttribution** | Attribution theory | System-blame for failures |
+| **techSavviness** | Digital literacy | Familiarity with UI patterns |
+| **attentionSpan** | Attention research | Focus duration |
+| **impulsivity** | Behavioral psychology | Quick vs deliberate actions |
+| **errorRecovery** | Human factors | Speed of correcting mistakes |
+| **visualProcessing** | Cognitive science | Image vs text preference |
+| **spatialMemory** | Navigation research | UI layout recall |
+| **patternRecognition** | Expertise research | UI element identification |
+| **riskPerception** | Risk psychology | Danger assessment |
+| **socialProof** | Cialdini (1984) | Influence of others' actions |
+| **authorityTrust** | Trust research | Trust in official sources |
+
+## Trait Reference Matrix
+
+Each trait has 5 behavioral levels with specific descriptions:
+
+### Example: Patience Trait
+
+| Value | Label | Behaviors |
+|-------|-------|-----------|
+| 0 | Very Low | Abandons at first sign of friction, expects instant results |
+| 0.25 | Low | Gets frustrated quickly, skips slow-loading content |
+| 0.5 | Moderate | Waits reasonable time, tolerates some friction |
+| 0.75 | High | Patient with delays, reads loading messages |
+| 1.0 | Very High | Extremely patient, waits through any delay |
+
+### Example: Self-Efficacy Trait
+
+| Value | Label | Behaviors |
+|-------|-------|-----------|
+| 0 | Very Low | "I can't do this", gives up immediately on challenge |
+| 0.25 | Low | Doubts ability, abandons 40% faster than average |
+| 0.5 | Moderate | Normal confidence, persists through minor challenges |
+| 0.75 | High | Confident problem-solver, sees obstacles as puzzles |
+| 1.0 | Very High | "I'll figure this out", never attributes failure to self |
+
+## Trait Correlations
+
+The system automatically applies research-backed correlations:
+
+| Primary Trait | Correlated Trait | Relationship |
+|---------------|------------------|--------------|
+| Low selfEfficacy | High internalAttribution | Self-blame for failures |
+| Low selfEfficacy | Low resilience | Slower bounce-back |
+| Low patience | Low resilience | Less tolerance for errors |
+| High curiosity | Higher exploration | More feature discovery |
+| Low trustCalibration | Longer evaluation time | Scrutinizes CTAs |
+
+## Questionnaire Formats
+
+### Quick Questionnaire (8 traits)
+
+Core traits for basic persona differentiation:
+- patience, riskTolerance, comprehension, persistence
+- curiosity, workingMemory, readingTendency, resilience
+
+### Comprehensive Questionnaire (25 traits)
+
+All cognitive traits for detailed behavioral modeling.
+
+### Custom Selection
+
+Request specific traits:
+
+```typescript
+const questionnaire = generatePersonaQuestionnaire({
+  traits: ['patience', 'selfEfficacy', 'trustCalibration'],
+});
+```
+
+## AskUserQuestion Integration
+
+For Claude sessions, use the `formatForAskUserQuestion` function:
+
+```typescript
+import { formatForAskUserQuestion, generatePersonaQuestionnaire } from 'cbrowser';
+
+const questionnaire = generatePersonaQuestionnaire({ comprehensive: false });
+const askUserFormat = formatForAskUserQuestion(questionnaire.questions);
+
+// Returns format compatible with Claude's AskUserQuestion tool:
+// {
+//   questions: [
+//     {
+//       question: "How does this user handle waiting?",
+//       header: "patience",
+//       options: [
+//         { label: "Very impatient", description: "Abandons at first delay" },
+//         ...
+//       ],
+//       multiSelect: false
+//     },
+//     ...
+//   ]
+// }
+```
+
+## CLI Interactive Mode
+
+The CLI provides an interactive questionnaire experience:
+
+```bash
+$ npx cbrowser persona-questionnaire start --name "anxious-newbie"
+
+=== CBrowser Persona Questionnaire ===
+Creating persona: anxious-newbie (8 core traits)
+
+[1/8] Patience
+How does this user handle waiting for pages or actions?
+  1. Very impatient - abandons at first delay
+  2. Somewhat impatient - frustrated by normal load times
+  3. Average - tolerates reasonable waits
+  4. Patient - waits through delays calmly
+  5. Very patient - unlimited patience
+> 2
+
+[2/8] Risk Tolerance
+How willing is this user to try unfamiliar features?
+...
+
+=== Persona Created ===
+Saved to: ~/.cbrowser/personas/anxious-newbie.json
+```
+
+## Using Custom Personas
+
+After creating a persona via questionnaire:
+
+```typescript
+import { runCognitiveJourney } from 'cbrowser';
+
+const result = await runCognitiveJourney({
+  persona: 'anxious-newbie',  // Uses saved persona
+  startUrl: 'https://example.com',
+  goal: 'complete signup',
+});
+```
+
+Or with inline traits:
+
+```typescript
+const customTraits = buildTraitsFromAnswers({
+  patience: 0.25,
+  selfEfficacy: 0.25,
+  trustCalibration: 0.25,
+});
+
+const result = await runCognitiveJourney({
+  persona: 'custom',
+  customTraits,
+  startUrl: 'https://example.com',
+  goal: 'complete signup',
+});
+```
+
+## Research Citations
+
+The trait system is grounded in academic research:
+
+- **Bandura, A. (1977)** - Self-Efficacy: Toward a Unifying Theory of Behavioral Change
+- **Kahneman, D. & Tversky, A.** - Prospect Theory and Decision Making
+- **Simon, H. (1956)** - Satisficing and Administrative Behavior
+- **Fogg, B.J. (2003)** - Persuasive Technology and Trust
+- **Mark, G. et al. (2005)** - No Task Left Behind: Interrupt Recovery
+- **Baumeister, R.** - Ego Depletion and Decision Fatigue
+- **Nielsen, J.** - Usability Engineering and User Behavior
+- **Cialdini, R. (1984)** - Influence: The Psychology of Persuasion
+
+## API Reference
+
+### generatePersonaQuestionnaire(options)
+
+Generate questionnaire questions.
+
+```typescript
+interface QuestionnaireOptions {
+  comprehensive?: boolean;     // All 25 traits (default: false = 8 traits)
+  traits?: string[];           // Specific traits to include
+  includeResearch?: boolean;   // Include research citations
+}
+
+const questionnaire = generatePersonaQuestionnaire(options);
+// Returns: { questions: Question[], estimatedMinutes: number }
+```
+
+### buildTraitsFromAnswers(answers)
+
+Build complete trait profile from questionnaire answers.
+
+```typescript
+const traits = buildTraitsFromAnswers({
+  patience: 0.25,
+  curiosity: 0.75,
+});
+// Returns: CognitiveTraits with correlations applied
+```
+
+### getTraitBehaviors(trait, value)
+
+Get behavioral description for a trait value.
+
+```typescript
+const behaviors = getTraitBehaviors('patience', 0.25);
+// Returns: { label: string, description: string, behaviors: string[] }
+```
+
+### getTraitLabel(trait, value)
+
+Get short label for trait value.
+
+```typescript
+const label = getTraitLabel('patience', 0.25);
+// Returns: "Low"
+```
+
+### getTraitReference(trait)
+
+Get full research reference for a trait.
+
+```typescript
+const ref = getTraitReference('selfEfficacy');
+// Returns: { researchBasis: string, citations: string[], levels: Level[] }
+```
+
+### formatForAskUserQuestion(questions)
+
+Format questions for Claude's AskUserQuestion tool.
+
+```typescript
+const formatted = formatForAskUserQuestion(questions);
+// Returns: { questions: AskUserQuestion[] }
+```

package/docs/README.md

@@ -0,0 +1,74 @@
+# CBrowser Documentation
+
+Welcome to the CBrowser documentation. This directory contains comprehensive guides for all CBrowser features.
+
+## Quick Links
+
+| Guide | Description |
+|-------|-------------|
+| [Getting Started](./GETTING-STARTED.md) | Installation, first commands, basic usage |
+| [Cognitive Simulation](./COGNITIVE-SIMULATION.md) | User simulation, personas, trait system |
+| [Persona Questionnaire](./PERSONA-QUESTIONNAIRE.md) | Research-backed custom persona creation |
+| [Visual Testing](./VISUAL-TESTING.md) | AI visual regression, cross-browser, responsive |
+| [MCP Integration](./MCP-INTEGRATION.md) | Claude Desktop and remote MCP server setup |
+| [Natural Language Tests](./NATURAL-LANGUAGE-TESTS.md) | Writing tests in plain English |
+| [Constitutional Safety](./CONSTITUTIONAL-SAFETY.md) | Risk classification and safety zones |
+| [CLI Reference](./CLI-REFERENCE.md) | Complete command-line reference |
+| [API Reference](./API-REFERENCE.md) | TypeScript API documentation |
+
+## Feature Guides
+
+### Core Features
+- [Self-Healing Selectors](./SELF-HEALING-SELECTORS.md) - ARIA-first selector strategy
+- [Agent-Ready Audit](./AGENT-READY-AUDIT.md) - AI-agent friendliness analysis
+- [Competitive Benchmark](./COMPETITIVE-BENCHMARK.md) - UX comparison across sites
+- [Empathy Audit](./EMPATHY-AUDIT.md) - Disability simulation testing
+
+### Testing Features
+- [Test Suites](./TEST-SUITES.md) - Natural language test execution
+- [Test Repair](./TEST-REPAIR.md) - AI-powered test fixing
+- [Flaky Detection](./FLAKY-DETECTION.md) - Identify unreliable tests
+- [Coverage Mapping](./COVERAGE-MAPPING.md) - Find untested pages
+
+### Visual Features
+- [Visual Baselines](./VISUAL-BASELINES.md) - Capture and compare screenshots
+- [Cross-Browser Testing](./CROSS-BROWSER-TESTING.md) - Chrome, Firefox, Safari comparison
+- [Responsive Testing](./RESPONSIVE-TESTING.md) - Mobile, tablet, desktop viewports
+- [A/B Comparison](./AB-COMPARISON.md) - Compare two URLs visually
+
+### Advanced Features
+- [Chaos Testing](./CHAOS-TESTING.md) - Inject failures, test resilience
+- [Bug Hunting](./BUG-HUNTING.md) - Autonomous issue discovery
+- [Performance Testing](./PERFORMANCE-TESTING.md) - Regression detection
+- [Session Management](./SESSION-MANAGEMENT.md) - Save and restore browser state
+
+## MCP Tools Reference
+
+CBrowser provides 48 MCP tools organized by category:
+
+| Category | Tools | Description |
+|----------|-------|-------------|
+| **Navigation** | 5 | Navigate, screenshot, extract, cloudflare detection |
+| **Interaction** | 4 | Click, smart click, fill, scroll |
+| **Testing** | 3 | Test suites, repair, flaky detection |
+| **Visual** | 6 | Baselines, regression, cross-browser, responsive, A/B |
+| **Cognitive** | 3 | Journey init, state update, persona comparison |
+| **Persona** | 3 | Questionnaire, build, trait lookup |
+| **Analysis** | 5 | Bug hunt, chaos, agent audit, benchmark, empathy |
+| **Stealth** | 5 | Enable, disable, status, check, diagnose |
+
+See [MCP Integration](./MCP-INTEGRATION.md) for complete tool documentation.
+
+## Version History
+
+See [CHANGELOG.md](../CHANGELOG.md) for detailed release notes.
+
+### Current Version: 16.7.0
+
+Key features:
+- 48 MCP tools for Claude integration
+- Research-backed persona questionnaire system
+- 25 cognitive traits with behavioral mappings
+- Accessibility empathy testing
+- Competitive UX benchmarking
+- Agent-ready site auditing

package/examples/persona-questionnaire.ts

@@ -0,0 +1,219 @@
+/**
+ * Persona Questionnaire Example
+ *
+ * This example demonstrates the research-backed persona questionnaire system
+ * introduced in v16.6.0. The questionnaire maps behavioral answers to cognitive
+ * trait values (0-1 scale) with proper correlation adjustments.
+ *
+ * The questionnaire works across:
+ * - Claude sessions (via AskUserQuestion tool)
+ * - CLI (interactive terminal prompts)
+ * - Remote and Local MCP servers
+ */
+
+import {
+  generatePersonaQuestionnaire,
+  buildTraitsFromAnswers,
+  getTraitBehaviors,
+  getTraitLabel,
+  getTraitReference,
+  formatForAskUserQuestion,
+  TRAIT_REFERENCE_MATRIX,
+} from 'cbrowser';
+
+// Example 1: Generate the questionnaire for Claude's AskUserQuestion tool
+function claudeQuestionnaireExample() {
+  console.log('\n=== Claude AskUserQuestion Format ===\n');
+
+  // Generate a quick 8-trait questionnaire
+  const questionnaire = generatePersonaQuestionnaire({ comprehensive: false });
+
+  console.log(`Generated ${questionnaire.questions.length} questions:`);
+
+  for (const q of questionnaire.questions) {
+    console.log(`\nTrait: ${q.trait}`);
+    console.log(`Question: ${q.question}`);
+    console.log('Options:');
+    for (const opt of q.options) {
+      console.log(`  [${opt.value}] ${opt.label}`);
+    }
+  }
+
+  // Format for AskUserQuestion tool
+  const askUserFormat = formatForAskUserQuestion(questionnaire.questions.slice(0, 4));
+  console.log('\n=== AskUserQuestion Format (first 4 questions) ===');
+  console.log(JSON.stringify(askUserFormat, null, 2));
+}
+
+// Example 2: Build traits from questionnaire answers
+function buildTraitsExample() {
+  console.log('\n=== Building Traits from Answers ===\n');
+
+  // Simulate answers from questionnaire
+  const answers: Record<string, number> = {
+    patience: 0.25,           // Gets frustrated quickly
+    riskTolerance: 0.75,      // Willing to try new things
+    comprehension: 0.5,       // Average
+    persistence: 0.75,        // Keeps trying
+    curiosity: 1.0,           // Very curious, explores everything
+    workingMemory: 0.5,       // Average
+    readingTendency: 0.25,    // Skims, doesn't read carefully
+    resilience: 0.5,          // Average bounce-back
+  };
+
+  // Build full trait profile with correlations applied
+  const traits = buildTraitsFromAnswers(answers);
+
+  console.log('Input answers:', answers);
+  console.log('\nDerived trait profile (with correlations):');
+
+  for (const [trait, value] of Object.entries(traits)) {
+    const label = getTraitLabel(trait, value);
+    console.log(`  ${trait}: ${value.toFixed(2)} (${label})`);
+  }
+}
+
+// Example 3: Lookup trait behaviors
+function traitBehaviorLookup() {
+  console.log('\n=== Trait Behavior Lookup ===\n');
+
+  const trait = 'patience';
+  const value = 0.25;
+
+  const behaviors = getTraitBehaviors(trait, value);
+  const reference = getTraitReference(trait);
+
+  console.log(`Trait: ${trait}`);
+  console.log(`Value: ${value}`);
+  console.log(`Label: ${behaviors.label}`);
+  console.log(`Description: ${behaviors.description}`);
+  console.log(`\nBehaviors:`);
+  for (const behavior of behaviors.behaviors) {
+    console.log(`  - ${behavior}`);
+  }
+  console.log(`\nResearch basis: ${reference?.researchBasis || 'None'}`);
+  console.log(`Citations: ${reference?.citations?.join(', ') || 'None'}`);
+}
+
+// Example 4: List all available traits
+function listAllTraits() {
+  console.log('\n=== All 25 Cognitive Traits ===\n');
+
+  const traits = Object.keys(TRAIT_REFERENCE_MATRIX);
+
+  console.log(`Total traits: ${traits.length}\n`);
+
+  for (const trait of traits) {
+    const ref = getTraitReference(trait);
+    console.log(`${trait}:`);
+    console.log(`  Research: ${ref?.researchBasis || 'General'}`);
+    console.log(`  Range: 0 (${getTraitLabel(trait, 0)}) to 1 (${getTraitLabel(trait, 1)})`);
+    console.log('');
+  }
+}
+
+// Example 5: Comprehensive questionnaire (all 25 traits)
+function comprehensiveQuestionnaireExample() {
+  console.log('\n=== Comprehensive Questionnaire ===\n');
+
+  const questionnaire = generatePersonaQuestionnaire({
+    comprehensive: true,
+    includeResearch: true,
+  });
+
+  console.log(`Comprehensive questionnaire: ${questionnaire.questions.length} questions`);
+  console.log(`Estimated time: ${questionnaire.estimatedMinutes} minutes\n`);
+
+  // Show first 3 questions with research citations
+  for (const q of questionnaire.questions.slice(0, 3)) {
+    console.log(`[${q.trait}] ${q.question}`);
+    if (q.researchBasis) {
+      console.log(`  Research: ${q.researchBasis}`);
+    }
+    console.log('');
+  }
+}
+
+// Example 6: Custom trait selection
+function customTraitSelection() {
+  console.log('\n=== Custom Trait Selection ===\n');
+
+  // Only get questions for specific traits
+  const questionnaire = generatePersonaQuestionnaire({
+    traits: ['patience', 'riskTolerance', 'selfEfficacy', 'trustCalibration'],
+  });
+
+  console.log(`Custom questionnaire: ${questionnaire.questions.length} questions\n`);
+
+  for (const q of questionnaire.questions) {
+    console.log(`${q.trait}: ${q.question}`);
+  }
+}
+
+// Example 7: Trait correlation demonstration
+function correlationExample() {
+  console.log('\n=== Trait Correlations ===\n');
+
+  // Low self-efficacy should correlate with higher internal attribution
+  const lowEfficacyAnswers: Record<string, number> = {
+    selfEfficacy: 0.25, // "I probably can't figure this out"
+  };
+
+  const derived = buildTraitsFromAnswers(lowEfficacyAnswers);
+
+  console.log('Input: selfEfficacy = 0.25 (Low)');
+  console.log('\nCorrelated traits automatically adjusted:');
+  console.log(`  internalAttribution: ${derived.internalAttribution?.toFixed(2)} (blames self for failures)`);
+  console.log(`  resilience: ${derived.resilience?.toFixed(2)} (lower bounce-back ability)`);
+  console.log('\nResearch: Bandura (1977) - Self-efficacy affects attribution patterns');
+}
+
+// Example 8: Integration with cognitive journey
+async function journeyIntegrationExample() {
+  console.log('\n=== Integration with Cognitive Journey ===\n');
+
+  // Build traits from questionnaire answers
+  const answers: Record<string, number> = {
+    patience: 0.25,
+    riskTolerance: 0.5,
+    comprehension: 0.75,
+    selfEfficacy: 0.5,
+    curiosity: 0.75,
+  };
+
+  const traits = buildTraitsFromAnswers(answers);
+
+  console.log('Generated trait profile for cognitive journey:');
+  console.log(JSON.stringify(traits, null, 2));
+
+  console.log('\nUse with runCognitiveJourney:');
+  console.log(`
+const result = await runCognitiveJourney({
+  persona: 'custom',
+  startUrl: 'https://example.com',
+  goal: 'complete signup',
+  customTraits: ${JSON.stringify(traits, null, 2)},
+});
+`);
+}
+
+// Run examples
+async function main() {
+  console.log('╔════════════════════════════════════════════════════════════════╗');
+  console.log('║  CBrowser Persona Questionnaire Examples (v16.6.0)             ║');
+  console.log('║  Research-backed trait mapping for cognitive user simulation  ║');
+  console.log('╚════════════════════════════════════════════════════════════════╝');
+
+  claudeQuestionnaireExample();
+  buildTraitsExample();
+  traitBehaviorLookup();
+  // listAllTraits();              // Uncomment for full trait list
+  comprehensiveQuestionnaireExample();
+  customTraitSelection();
+  correlationExample();
+  await journeyIntegrationExample();
+
+  console.log('\n=== Example Complete ===');
+}
+
+main().catch(console.error);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cbrowser",
-  "version": "16.5.0",
+  "version": "16.7.1",
   "type": "module",
   "description": "Cognitive browser automation that thinks like your users. Simulate real user cognition with abandonment detection, constitutional safety, chaos engineering, and UX friction discovery.",
   "main": "dist/index.js",