@codeyam/codeyam-cli 0.1.0-staging.036391e → 0.1.0-staging.07d8f7b

package/codeyam-cli/templates/codeyam-memory-hook.sh

@@ -3,7 +3,7 @@
 # Ensures rules are reviewed when associated code changes
 #
 # This hook checks that rules with matching `paths` patterns have been reviewed
-# (indicated by an updated timestamp in .claude/codeyam-rule-state.json) when associated code files are modified.
+# (indicated by an updated lastAuditedAt in .claude/codeyam-rule-state.json) when associated code files are modified.
 
 set -e
 
@@ -21,9 +21,9 @@ if [ -z "$STAGED_FILES" ]; then
   exit 0
 fi
 
-# Function to convert ISO 8601 timestamp to epoch seconds
+# Function to convert ISO 8601 date string to epoch seconds
 # Handles both macOS and Linux date commands
-timestamp_to_epoch() {
+iso_to_epoch() {
   local ts="$1"
   # Remove trailing Z if present
   ts="${ts%Z}"
@@ -84,14 +84,14 @@ matches_pattern() {
   echo "$file" | grep -qE "$regex_pattern" 2>/dev/null
 }
 
-# Read timestamp from .claude/codeyam-rule-state.json
+# Read lastAuditedAt from .claude/codeyam-rule-state.json
 RULE_STATE_FILE=".claude/codeyam-rule-state.json"
-get_rule_timestamp() {
+get_rule_last_audited_at() {
   local rule_file="$1"
   # Extract relative path from .claude/rules/
   local rule_name="${rule_file#.claude/rules/}"
   if [ ! -f "$RULE_STATE_FILE" ]; then echo ""; return; fi
-  node -e "try{const d=JSON.parse(require('fs').readFileSync('$RULE_STATE_FILE','utf-8'));console.log((d.rules&&d.rules['$rule_name']&&d.rules['$rule_name'].timestamp)||'')}catch{console.log('')}"
+  node -e "try{const d=JSON.parse(require('fs').readFileSync('$RULE_STATE_FILE','utf-8'));console.log((d.rules&&d.rules['$rule_name']&&d.rules['$rule_name'].lastAuditedAt)||'')}catch{console.log('')}"
 }
 
 # Parse paths from YAML frontmatter
@@ -117,14 +117,14 @@ while IFS= read -r rule_file; do
   fi
   CHECKED_RULES="$CHECKED_RULES $rule_file"
 
-  rule_timestamp=$(get_rule_timestamp "$rule_file")
+  rule_last_audited=$(get_rule_last_audited_at "$rule_file")
 
-  # Skip rules without timestamp
-  if [ -z "$rule_timestamp" ]; then
+  # Skip rules without lastAuditedAt
+  if [ -z "$rule_last_audited" ]; then
     continue
   fi
 
-  rule_epoch=$(timestamp_to_epoch "$rule_timestamp")
+  rule_epoch=$(iso_to_epoch "$rule_last_audited")
 
   if [ "$rule_epoch" = "0" ]; then
     continue
@@ -155,7 +155,7 @@ while IFS= read -r rule_file; do
         # Get file modification time
         file_epoch=$(get_file_mtime "$staged_file")
 
-        # If file is newer than rule timestamp, flag it
+        # If file is newer than rule's lastAuditedAt, flag it
         if [ "$file_epoch" -gt "$rule_epoch" ]; then
           rule_is_outdated=true
           matched_file="$staged_file"
@@ -179,13 +179,13 @@ if [ -n "$OUTDATED_RULES" ]; then
   echo "  Claude Rules (Codeyam Memory): Outdated Documentation Detected"
   echo "================================================================"
   echo ""
-  echo "  The following rules have timestamps older than the code"
-  echo "  files they cover:"
+  echo "  The following rules were last audited before recent code"
+  echo "  changes to the files they cover:"
   echo "$OUTDATED_RULES"
   echo ""
   echo "  To proceed:"
   echo "    1. Review each rule to ensure it's still accurate"
-  echo "    2. Run 'codeyam memory touch' to update timestamps"
+  echo "    2. Run 'codeyam memory touch' to mark them as audited"
   echo "    3. Stage the updated .claude/codeyam-rule-state.json"
   echo "    4. Commit again"
   echo ""

package/codeyam-cli/templates/{codeyam:memory.md → codeyam-memory.md}

@@ -1,5 +1,5 @@
 ---
-name: codeyam:memory
+name: codeyam-memory
 autoApprove: true
 description: |
   Generate and maintain Claude Rules for your codebase based on thorough analysis.
@@ -13,19 +13,14 @@ This skill helps you generate and maintain Claude Rules (`.claude/rules/`) that
 
 ## Core Principle: Document Confusion, Not Information
 
-**Good rules** explain things that are NOT obvious from reading the code:
+**Valuable rules** capture knowledge that reading the code alone wouldn't reveal:
 
 - Historical context (why code evolved this way)
 - Hidden relationships (files that must change together)
 - Gotchas that caused bugs
 - Non-obvious conventions
 
-**Bad rules** document things Claude can easily ascertain:
-
-- What functions do (Claude can read the code)
-- Type definitions (Claude can see them)
-- Directory structure (Claude can explore it)
-- Basic patterns (Claude knows common patterns)
+Skip documenting things Claude can determine by reading code: function signatures, type definitions, directory structure, and common patterns.
 
 ## When to Use This Skill
 
@@ -41,7 +36,9 @@ Check if this is the first time running memory.
 
 ### 1A. Add Documentation Section to CLAUDE.md
 
-If CLAUDE.md doesn't contain a "When Confused / With Mistakes" section, add close to the top:
+If CLAUDE.md already contains a "Documenting Confusion / Mistakes" section, skip this step entirely.
+
+Otherwise, add **only** the section below — do not modify or add any other content to CLAUDE.md. If CLAUDE.md doesn't exist, create it with just a `# Project` heading followed by this section:
 
 ```markdown
 ## Continuous Documentation
@@ -61,6 +58,8 @@ It is very important to document any tribal knowledge, complex architectural dec
 Please see `.codeyam/rules/instructions.md` for guidance.
 ```
 
+**Important:** Do not add project descriptions, architecture summaries, or any other content to CLAUDE.md. Only add the exact section above.
+
 ### 1B. Verify Instructions File
 
 Check that `.codeyam/rules/instructions.md` exists (it should be created during `codeyam init`). If missing, copy it from `codeyam-cli/templates/rules-instructions.md`.
@@ -275,7 +274,7 @@ Before generating each rule, verify it passes these tests:
 
 **2. Code-derivable check**: Read the files the rule will cover. Could the rule's content be determined by reading those files alone?
 
-- If YES → rule probably not needed (Claude can read the code)
+- If YES → the code is its own documentation — prefer keeping rules for non-derivable insights
 - If NO (historical context, edge cases, non-obvious behavior) → rule is valuable
 
 **3. Prevention check**: Would this rule have prevented one of the confusion commits you found?
@@ -301,7 +300,7 @@ This caused a bug where `entity` matched `entityCode` (siblings, not parent-chil
 - Not code-derivable: Code doesn't explain why boundary checking matters
 - Prevention: Would prevent future prefix-matching bugs
 
-**❌ Bad rule** (fails tests):
+**Compare with a weaker alternative** (fails the checks):
 
 ```markdown
 ## Running Tests
@@ -309,9 +308,7 @@ This caused a bug where `entity` matched `entityCode` (siblings, not parent-chil
 Use `pnpm jest` to run tests. Configuration is in `jest.config.ts`.
 ```
 
-- No confusion evidence (no commits showing people struggled with this)
-- Code-derivable: Anyone can see `jest.config.ts` exists
-- Doesn't prevent any confusion
+- No confusion evidence, code-derivable, and wouldn't prevent future mistakes
 
 ### 5B. Rule File Guidelines
 
@@ -319,17 +316,13 @@ Use `pnpm jest` to run tests. Configuration is in `jest.config.ts`.
    - Rule for `src/api/` → `.claude/rules/src/api/architecture.md`
    - Rule for testing patterns → `.claude/rules/testing-patterns.md`
 
-2. **Paths must be specific**
-   - Good: `paths: ['src/api/**/*.ts']`
-   - Bad: `paths: ['**/*.ts']` (too broad, wastes context)
+2. **Paths must be specific** — use `paths: ['src/api/**/*.ts']` rather than `'**/*.ts'` (too broad wastes context)
 
 3. **Content should explain "why" not just "what"**
    - Focus on the reasoning, history, or gotcha
    - Be concise - every word costs context
 
-4. **Timestamp must be current**
-   - Use ISO 8601 format: `2026-01-27T15:30:00Z`
-   - This enables the pre-commit hook enforcement
+4. **Audit dates live in `.claude/codeyam-rule-state.json`** (managed by `codeyam memory touch`). Keep rule frontmatter limited to `paths`.
 
 ### Rule Template
 
@@ -337,7 +330,6 @@ Use `pnpm jest` to run tests. Configuration is in `jest.config.ts`.
 ---
 paths:
   - 'specific/path/**/*.ts'
-timestamp: [CURRENT_ISO_TIMESTAMP]
 ---
 
 ## [Clear, Descriptive Title]
@@ -374,7 +366,7 @@ After generating rules based on your analysis and user answers:
 5. **Remind the user** to commit the new rules:
    ```
    git add .claude/rules/ .codeyam/rules/
-   git commit -m "Add rules for Claude Code (generated via /codeyam:memory)"
+   git commit -m "Add rules for Claude Code (generated via /codeyam-memory)"
    ```
 
 ---
@@ -394,11 +386,11 @@ After generating rules based on your analysis and user answers:
 The pre-commit hook **blocks commits** when:
 
 - Code files matching a rule's `paths` are modified
-- The rule's `timestamp` is older than the code changes
+- The rule's `lastAuditedAt` in `.claude/codeyam-rule-state.json` is older than the code changes
 
 To proceed:
 
 1. Review the flagged rule(s)
 2. Update content if needed
-3. Update the `timestamp` to current time
+3. Run `codeyam memory touch` to mark rules as audited in `.claude/codeyam-rule-state.json`
 4. Stage and commit

package/codeyam-cli/templates/{codeyam:new-rule.md → codeyam-new-rule.md}

@@ -1,5 +1,5 @@
 ---
-name: codeyam:new-rule
+name: codeyam-new-rule
 autoApprove: true
 description: |
   Create a new Claude Rule for documenting codebase patterns.
@@ -9,5 +9,3 @@ description: |
 # Create New Claude Rule
 
 Read `.codeyam/rules/instructions.md` for detailed guidance on structure and formatting.
-
-If the instructions file doesn't exist, copy it from `codeyam-cli/templates/rules-instructions.md`.

package/codeyam-cli/templates/{codeyam:setup.md → codeyam-setup.md}

@@ -1,5 +1,5 @@
 ---
-name: codeyam:setup
+name: codeyam-setup
 autoApprove: true
 description: |
   Use this skill when the user asks to "setup CodeYam" or needs to configure CodeYam for their project.
@@ -52,6 +52,18 @@ codeyam validate-mock .codeyam/universal-mocks/{path-to-your-mock}
 
 ## Setup Workflow
 
+### Step 0: Ensure Simulation Infrastructure
+
+Before configuring the dev server or mocks, ensure the simulation infrastructure is installed.
+
+```bash
+codeyam setup-simulations
+```
+
+This is **idempotent** — if already set up, each step is detected and skipped. On first run it installs analyzer dependencies, Playwright chromium, and creates baseline entities (several minutes). Subsequent runs complete in seconds.
+
+If it fails with "No web applications found", the project doesn't support simulations — inform the user and stop.
+
 ### Step 1: Configure Webapp Start Command
 
 **ACTION 1:** Read configuration files:

package/codeyam-cli/templates/{codeyam:sim.md → codeyam-sim.md}

@@ -1,5 +1,5 @@
 ---
-name: codeyam:sim
+name: codeyam-sim
 autoApprove: true
 description: |
   Use this skill to create interactive simulations of components and functions using CodeYam's analysis.

package/codeyam-cli/templates/{codeyam:test.md → codeyam-test.md}

@@ -1,5 +1,5 @@
 ---
-name: codeyam:test
+name: codeyam-test
 autoApprove: true
 description: |
   Use this skill to write comprehensive unit and integration tests using CodeYam's mock generation.

package/codeyam-cli/templates/{codeyam:verify.md → codeyam-verify.md}

@@ -1,5 +1,5 @@
 ---
-name: codeyam:verify
+name: codeyam-verify
 autoApprove: true
 description: |
   Use this skill after making code changes that impact application functionality.

package/codeyam-cli/templates/editor-step-hook.py

@@ -0,0 +1,143 @@
+#!/usr/bin/env python3
+"""
+PostToolUse + Stop hook for editor mode step tracking.
+
+Reads .codeyam/editor-step.json and prints a reminder about the current step.
+Logs each firing to .codeyam/logs/editor-log.jsonl.
+If no state file exists, outputs nothing (not in editor mode or between features).
+"""
+
+import json
+import os
+import sys
+from datetime import datetime, timezone
+
+
+STEP_LABELS = {
+    1: "Plan",
+    2: "Prototype",
+    3: "Confirm",
+    4: "Deconstruct",
+    5: "Glossary",
+    6: "Analyze",
+    7: "App Scenarios",
+    8: "User Scenarios",
+    9: "Verify",
+    10: "Review",
+}
+
+STEP_RESTRICTIONS = {
+    1: "Do NOT write any code. Plan and describe only. Wait for user confirmation.",
+    2: "Do NOT create scenarios or run codeyam analyze. Build fast — working prototype with real data.",
+    3: "Present a selection menu (AskUserQuestion) for confirmation. Do NOT refactor or create scenarios until approved.",
+    4: "Do NOT create scenarios. Write a failing test FIRST, then extract. TDD only.",
+    5: "Do NOT write application code or scenarios. Update the glossary only.",
+    6: "Run codeyam analyze for each file. Verify all pass. Fix any failures before proceeding.",
+    7: "Do NOT modify application code. Create and register app-level scenarios only.",
+    8: "Do NOT modify application code. Create user-persona scenarios only (or skip if no users).",
+    9: "Verify entity screenshots (/api/editor-entity-status) AND editor scenarios. After ANY code fix, re-run codeyam analyze on affected files. Fix only — do NOT add features.",
+    10: "Verify ALL screenshots exist and NO client-side errors (/api/editor-client-errors), then present selection menu (AskUserQuestion): Save or make changes.",
+}
+
+
+def log_event(project_dir, event, data=None):
+    """Append a JSONL entry to .codeyam/logs/editor-log.jsonl."""
+    try:
+        logs_dir = os.path.join(project_dir, ".codeyam", "logs")
+        os.makedirs(logs_dir, exist_ok=True)
+        log_path = os.path.join(logs_dir, "editor-log.jsonl")
+        entry = {"ts": datetime.now(timezone.utc).isoformat(), "event": event}
+        if data:
+            entry.update(data)
+        with open(log_path, "a") as f:
+            f.write(json.dumps(entry) + "\n")
+    except Exception:
+        pass  # Logging is best-effort
+
+
+def detect_event():
+    """Detect whether this is a PostToolUse or Stop hook from stdin."""
+    try:
+        raw = sys.stdin.read()
+        if not raw.strip():
+            return "unknown", {}
+        data = json.loads(raw)
+        # PostToolUse has tool_name; Stop has stop_hook_active
+        if "tool_name" in data:
+            return "post_tool_use", data
+        elif "stop_hook_active" in data:
+            return "stop", data
+        return "unknown", data
+    except Exception:
+        return "unknown", {}
+
+
+def main():
+    project_dir = os.environ.get("CLAUDE_PROJECT_DIR", os.getcwd())
+    state_path = os.path.join(project_dir, ".codeyam", "editor-step.json")
+
+    if not os.path.exists(state_path):
+        return
+
+    try:
+        with open(state_path, "r") as f:
+            state = json.load(f)
+    except (json.JSONDecodeError, IOError):
+        return
+
+    step = state.get("step")
+    label = state.get("label", "Unknown")
+    feature = state.get("feature", "")
+
+    if not step:
+        return
+
+    event_type, event_data = detect_event()
+
+    # Log the hook firing
+    log_data = {"step": step, "label": label, "feature": feature, "hook": event_type}
+    if event_type == "post_tool_use":
+        log_data["tool"] = event_data.get("tool_name", "")
+    log_event(project_dir, "hook", log_data)
+
+    restriction = STEP_RESTRICTIONS.get(step, "")
+    next_cmd = f"codeyam editor {step + 1}" if step < 10 else "codeyam editor 1"
+
+    lines = [
+        f'Editor Mode \u2014 Step {step} ({label}): "{feature}"',
+    ]
+    if restriction:
+        lines.append(restriction)
+
+    if event_type == "stop":
+        # Build colored progress tracker using ANSI escape codes
+        GREEN = "\033[32m"
+        BOLD_CYAN = "\033[1;36m"
+        DIM = "\033[2m"
+        RESET = "\033[0m"
+        tracker = [f"{DIM}  \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510{RESET}"]
+        for i in range(1, 11):
+            lbl = STEP_LABELS[i].ljust(28)
+            num = f" {i}" if i < 10 else f"{i}"
+            content = f"{num}. {lbl}"
+            if i < step:
+                tracker.append(f"{DIM}  \u2502{RESET}{GREEN}  \u2713  {content}{RESET}{DIM}\u2502{RESET}")
+            elif i == step:
+                tracker.append(f"{DIM}  \u2502{RESET}{BOLD_CYAN}  \u2192  {content}{RESET}{DIM}\u2502{RESET}")
+            else:
+                tracker.append(f"{DIM}  \u2502  \u25cb  {content}\u2502{RESET}")
+        tracker.append(f"{DIM}  \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518{RESET}")
+        lines.append("Present this progress tracker to the user (copy verbatim):")
+        lines.extend(tracker)
+        lines.append(
+            "For the CURRENT step (\u2192), show each checklist item with "
+            "\u2713 (done) or \u2717 (skipped + reason)."
+        )
+
+    lines.append(f"When this step is complete, run: {next_cmd}")
+
+    print("\n".join(lines))
+
+
+if __name__ == "__main__":
+    main()

package/codeyam-cli/templates/hooks/staleness-check.sh

@@ -0,0 +1,43 @@
+#!/bin/bash
+# Staleness check hook - runs after file edits to check if related rules need review
+# Receives JSON input via stdin with tool info
+
+set -e
+
+# Read the input JSON
+INPUT=$(cat)
+
+# Extract the file path that was edited
+FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // .tool_input.path // empty' 2>/dev/null)
+
+if [ -z "$FILE_PATH" ]; then
+  exit 0  # No file path, nothing to check
+fi
+
+# Find rules that match this file path
+RULES_DIR="${CLAUDE_PROJECT_DIR}/.claude/rules"
+
+if [ ! -d "$RULES_DIR" ]; then
+  exit 0  # No rules directory
+fi
+
+# Search for rules whose paths might match the edited file
+MATCHING_RULES=""
+while IFS= read -r -d '' rule_file; do
+  # Extract paths from frontmatter
+  PATHS=$(sed -n '/^---$/,/^---$/p' "$rule_file" | grep -E "^\s*-\s*'" | sed "s/.*'\(.*\)'.*/\1/")
+
+  for pattern in $PATHS; do
+    # Simple check if the file might match the pattern
+    if [[ "$FILE_PATH" == *"${pattern%%\**}"* ]]; then
+      MATCHING_RULES="$MATCHING_RULES\n- $(basename "$rule_file")"
+      break
+    fi
+  done
+done < <(find "$RULES_DIR" -name "*.md" -print0 2>/dev/null)
+
+if [ -n "$MATCHING_RULES" ]; then
+  echo "📋 Modified file may have related rules that need review:$MATCHING_RULES"
+fi
+
+exit 0

package/codeyam-cli/templates/isolation-route/next-app.tsx.template

@@ -0,0 +1,80 @@
+/**
+ * CodeYam Isolation Route — Next.js App Router
+ *
+ * Place this file at: app/__codeyam__/[component]/[scenario]/page.tsx
+ *
+ * This route dynamically imports a component and renders it with mock data
+ * from the specified scenario, enabling isolated component preview.
+ *
+ * Usage: http://localhost:3000/__codeyam__/TaskCard/Default
+ */
+'use client';
+
+import { useEffect, useState } from 'react';
+import { useParams } from 'next/navigation';
+
+interface ScenarioData {
+  mockData: Record<string, unknown>;
+}
+
+export default function CodeYamIsolationPage() {
+  const params = useParams();
+  const componentName = params.component as string;
+  const scenarioSlug = params.scenario as string;
+
+  const [Component, setComponent] = useState<React.ComponentType<any> | null>(null);
+  const [mockData, setMockData] = useState<Record<string, unknown> | null>(null);
+  const [error, setError] = useState<string | null>(null);
+
+  useEffect(() => {
+    async function loadComponent() {
+      try {
+        // Fetch scenario data from CodeYam API
+        const res = await fetch(
+          `http://localhost:${process.env.NEXT_PUBLIC_CODEYAM_PORT || '3111'}/api/editor-scenario-data?component=${componentName}&scenario=${scenarioSlug}`
+        );
+        if (res.ok) {
+          const data: ScenarioData = await res.json();
+          setMockData(data.mockData);
+        }
+
+        // Try to dynamically import the component
+        // Claude should update this mapping when adding new components
+        const componentModules: Record<string, () => Promise<any>> = {
+          // Example: 'TaskCard': () => import('@/components/TaskCard'),
+        };
+
+        const loader = componentModules[componentName];
+        if (loader) {
+          const mod = await loader();
+          setComponent(() => mod.default || mod[componentName]);
+        } else {
+          setError(`Component "${componentName}" not registered in isolation route`);
+        }
+      } catch (err) {
+        setError(`Failed to load component: ${err}`);
+      }
+    }
+
+    void loadComponent();
+  }, [componentName, scenarioSlug]);
+
+  if (error) {
+    return (
+      <div style={{ padding: 24, fontFamily: 'monospace', color: '#e74c3c' }}>
+        <h2>CodeYam Isolation Error</h2>
+        <p>{error}</p>
+      </div>
+    );
+  }
+
+  if (!Component || !mockData) {
+    return (
+      <div style={{ padding: 24, fontFamily: 'monospace', color: '#666' }}>
+        Loading {componentName} / {scenarioSlug}...
+      </div>
+    );
+  }
+
+  return <Component {...mockData} />;
+}

package/codeyam-cli/templates/isolation-route/next-pages.tsx.template

@@ -0,0 +1,79 @@
+/**
+ * CodeYam Isolation Route — Next.js Pages Router
+ *
+ * Place this file at: pages/__codeyam__/[component]/[scenario].tsx
+ *
+ * This route dynamically imports a component and renders it with mock data
+ * from the specified scenario, enabling isolated component preview.
+ *
+ * Usage: http://localhost:3000/__codeyam__/TaskCard/Default
+ */
+import { useRouter } from 'next/router';
+import { useEffect, useState } from 'react';
+
+interface ScenarioData {
+  mockData: Record<string, unknown>;
+}
+
+export default function CodeYamIsolationPage() {
+  const router = useRouter();
+  const { component: componentName, scenario: scenarioSlug } = router.query;
+
+  const [Component, setComponent] = useState<React.ComponentType<any> | null>(null);
+  const [mockData, setMockData] = useState<Record<string, unknown> | null>(null);
+  const [error, setError] = useState<string | null>(null);
+
+  useEffect(() => {
+    if (!componentName || !scenarioSlug) return;
+
+    async function loadComponent() {
+      try {
+        // Fetch scenario data from CodeYam API
+        const res = await fetch(
+          `http://localhost:${process.env.NEXT_PUBLIC_CODEYAM_PORT || '3111'}/api/editor-scenario-data?component=${componentName}&scenario=${scenarioSlug}`
+        );
+        if (res.ok) {
+          const data: ScenarioData = await res.json();
+          setMockData(data.mockData);
+        }
+
+        // Try to dynamically import the component
+        // Claude should update this mapping when adding new components
+        const componentModules: Record<string, () => Promise<any>> = {
+          // Example: 'TaskCard': () => import('../components/TaskCard'),
+        };
+
+        const loader = componentModules[componentName as string];
+        if (loader) {
+          const mod = await loader();
+          setComponent(() => mod.default || mod[componentName as string]);
+        } else {
+          setError(`Component "${componentName}" not registered in isolation route`);
+        }
+      } catch (err) {
+        setError(`Failed to load component: ${err}`);
+      }
+    }
+
+    void loadComponent();
+  }, [componentName, scenarioSlug]);
+
+  if (error) {
+    return (
+      <div style={{ padding: 24, fontFamily: 'monospace', color: '#e74c3c' }}>
+        <h2>CodeYam Isolation Error</h2>
+        <p>{error}</p>
+      </div>
+    );
+  }
+
+  if (!Component || !mockData) {
+    return (
+      <div style={{ padding: 24, fontFamily: 'monospace', color: '#666' }}>
+        Loading {componentName} / {scenarioSlug}...
+      </div>
+    );
+  }
+
+  return <Component {...mockData} />;
+}