@contractspec/lib.example-shared-ui 1.11.0 → 1.13.0

package/dist/hooks/index.js

@@ -0,0 +1,1517 @@
+// @bun
+// src/hooks/useEvolution.ts
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+"use client";
+var EVOLUTION_STORAGE_KEY = "contractspec-evolution-data";
+function useEvolution(templateId) {
+  const [usageStats, setUsageStats] = useState([]);
+  const [anomalies, setAnomalies] = useState([]);
+  const [suggestions, setSuggestions] = useState([]);
+  const [hints, setHints] = useState([]);
+  const [loading, setLoading] = useState(false);
+  const metricsRef = useRef([]);
+  const [operationCount, setOperationCount] = useState(0);
+  useEffect(() => {
+    try {
+      const stored = localStorage.getItem(`${EVOLUTION_STORAGE_KEY}-${templateId}`);
+      if (stored) {
+        const data = JSON.parse(stored);
+        setSuggestions(data.suggestions.map((s) => ({
+          ...s,
+          createdAt: new Date(s.createdAt)
+        })));
+      }
+    } catch {}
+  }, [templateId]);
+  useEffect(() => {
+    try {
+      localStorage.setItem(`${EVOLUTION_STORAGE_KEY}-${templateId}`, JSON.stringify({ suggestions }));
+    } catch {}
+  }, [suggestions, templateId]);
+  const trackOperation = useCallback((operationName, durationMs, success, errorCode) => {
+    const sample = {
+      operation: {
+        name: operationName,
+        version: "1.0.0",
+        tenantId: "sandbox"
+      },
+      durationMs,
+      success,
+      timestamp: new Date,
+      errorCode
+    };
+    metricsRef.current.push(sample);
+    setOperationCount((prev) => prev + 1);
+  }, []);
+  const analyzeUsage = useCallback(() => {
+    const samples = metricsRef.current;
+    if (samples.length < 5)
+      return;
+    const groups = new Map;
+    for (const sample of samples) {
+      const key = `${sample.operation.name}.v${sample.operation.version}`;
+      const arr = groups.get(key) ?? [];
+      arr.push(sample);
+      groups.set(key, arr);
+    }
+    const stats = [];
+    const detectedAnomalies = [];
+    groups.forEach((opSamples) => {
+      if (opSamples.length < 3)
+        return;
+      const durations = opSamples.map((s) => s.durationMs).sort((a, b) => a - b);
+      const errors = opSamples.filter((s) => !s.success);
+      const totalCalls = opSamples.length;
+      const errorRate = errors.length / totalCalls;
+      const averageLatencyMs = durations.reduce((sum, value) => sum + value, 0) / totalCalls;
+      const timestamps = opSamples.map((s) => s.timestamp.getTime());
+      const firstSample = opSamples[0];
+      if (!firstSample)
+        return;
+      const stat = {
+        operation: firstSample.operation,
+        totalCalls,
+        successRate: 1 - errorRate,
+        errorRate,
+        averageLatencyMs,
+        p95LatencyMs: percentile(durations, 0.95),
+        p99LatencyMs: percentile(durations, 0.99),
+        maxLatencyMs: Math.max(...durations),
+        lastSeenAt: new Date(Math.max(...timestamps)),
+        windowStart: new Date(Math.min(...timestamps)),
+        windowEnd: new Date(Math.max(...timestamps)),
+        topErrors: errors.reduce((acc, s) => {
+          if (s.errorCode) {
+            acc[s.errorCode] = (acc[s.errorCode] ?? 0) + 1;
+          }
+          return acc;
+        }, {})
+      };
+      stats.push(stat);
+      if (errorRate > 0.1) {
+        detectedAnomalies.push({
+          operation: stat.operation,
+          severity: errorRate > 0.3 ? "high" : errorRate > 0.2 ? "medium" : "low",
+          metric: "error-rate",
+          description: `Error rate ${(errorRate * 100).toFixed(1)}% exceeds threshold`,
+          detectedAt: new Date,
+          threshold: 0.1,
+          observedValue: errorRate
+        });
+      }
+      if (stat.p99LatencyMs > 500) {
+        detectedAnomalies.push({
+          operation: stat.operation,
+          severity: stat.p99LatencyMs > 1000 ? "high" : stat.p99LatencyMs > 750 ? "medium" : "low",
+          metric: "latency",
+          description: `P99 latency ${stat.p99LatencyMs.toFixed(0)}ms exceeds threshold`,
+          detectedAt: new Date,
+          threshold: 500,
+          observedValue: stat.p99LatencyMs
+        });
+      }
+    });
+    setUsageStats(stats);
+    setAnomalies(detectedAnomalies);
+    const newHints = detectedAnomalies.map((anomaly) => ({
+      operation: anomaly.operation,
+      category: anomaly.metric === "latency" ? "performance" : "error-handling",
+      summary: anomaly.metric === "latency" ? "Latency regression detected" : "Error spike detected",
+      justification: anomaly.description,
+      recommendedActions: anomaly.metric === "latency" ? [
+        "Add caching layer",
+        "Optimize database queries",
+        "Consider pagination"
+      ] : [
+        "Add retry logic",
+        "Improve error handling",
+        "Add circuit breaker"
+      ]
+    }));
+    setHints(newHints);
+  }, []);
+  const generateSuggestions = useCallback(async () => {
+    if (anomalies.length === 0)
+      return;
+    setLoading(true);
+    await new Promise((resolve) => setTimeout(resolve, 800));
+    const newSuggestions = anomalies.map((anomaly) => ({
+      id: `suggestion-${Date.now()}-${Math.random().toString(36).slice(2, 9)}`,
+      intent: {
+        id: `intent-${anomaly.operation.name}`,
+        type: anomaly.metric === "latency" ? "latency-regression" : anomaly.metric === "error-rate" ? "error-spike" : "throughput-drop",
+        description: anomaly.description,
+        operation: anomaly.operation,
+        confidence: {
+          score: anomaly.severity === "high" ? 0.9 : anomaly.severity === "medium" ? 0.7 : 0.5,
+          sampleSize: usageStats.find((s) => s.operation.name === anomaly.operation.name)?.totalCalls ?? 0
+        }
+      },
+      target: anomaly.operation,
+      proposal: {
+        summary: generateSuggestionSummary(anomaly),
+        rationale: generateSuggestionRationale(anomaly),
+        changeType: anomaly.metric === "error-rate" ? "policy-update" : "revision",
+        recommendedActions: generateRecommendedActions(anomaly)
+      },
+      confidence: anomaly.severity === "high" ? 0.85 : anomaly.severity === "medium" ? 0.7 : 0.55,
+      createdAt: new Date,
+      createdBy: "ai-evolution-agent",
+      status: "pending",
+      priority: anomaly.severity
+    }));
+    setSuggestions((prev) => [...prev, ...newSuggestions]);
+    setLoading(false);
+  }, [anomalies, usageStats]);
+  const approveSuggestion = useCallback((id, _notes) => {
+    setSuggestions((prev) => prev.map((s) => s.id === id ? { ...s, status: "approved" } : s));
+  }, []);
+  const rejectSuggestion = useCallback((id, _notes) => {
+    setSuggestions((prev) => prev.map((s) => s.id === id ? { ...s, status: "rejected" } : s));
+  }, []);
+  const clear = useCallback(() => {
+    metricsRef.current = [];
+    setOperationCount(0);
+    setUsageStats([]);
+    setAnomalies([]);
+    setSuggestions([]);
+    setHints([]);
+    localStorage.removeItem(`${EVOLUTION_STORAGE_KEY}-${templateId}`);
+  }, [templateId]);
+  return useMemo(() => ({
+    usageStats,
+    anomalies,
+    suggestions,
+    hints,
+    loading,
+    trackOperation,
+    analyzeUsage,
+    generateSuggestions,
+    approveSuggestion,
+    rejectSuggestion,
+    clear,
+    operationCount
+  }), [
+    usageStats,
+    anomalies,
+    suggestions,
+    hints,
+    loading,
+    trackOperation,
+    analyzeUsage,
+    generateSuggestions,
+    approveSuggestion,
+    rejectSuggestion,
+    clear,
+    operationCount
+  ]);
+}
+function percentile(values, p) {
+  if (!values.length)
+    return 0;
+  if (values.length === 1)
+    return values[0] ?? 0;
+  const idx = Math.min(values.length - 1, Math.floor(p * values.length));
+  return values[idx] ?? 0;
+}
+function generateSuggestionSummary(anomaly) {
+  if (anomaly.metric === "latency") {
+    return `Add caching and pagination to ${anomaly.operation.name} to reduce latency`;
+  }
+  if (anomaly.metric === "error-rate") {
+    return `Add retry policy and circuit breaker to ${anomaly.operation.name}`;
+  }
+  return `Optimize ${anomaly.operation.name} for improved throughput`;
+}
+function generateSuggestionRationale(anomaly) {
+  if (anomaly.metric === "latency") {
+    return `The operation ${anomaly.operation.name} is experiencing P99 latency of ${anomaly.observedValue?.toFixed(0)}ms, which is above the recommended threshold of ${anomaly.threshold}ms. This can impact user experience and downstream operations.`;
+  }
+  if (anomaly.metric === "error-rate") {
+    return `The error rate for ${anomaly.operation.name} is ${((anomaly.observedValue ?? 0) * 100).toFixed(1)}%, indicating potential issues with input validation, external dependencies, or resource limits.`;
+  }
+  return `Throughput for ${anomaly.operation.name} has dropped significantly, suggesting potential bottlenecks or reduced demand that should be investigated.`;
+}
+function generateRecommendedActions(anomaly) {
+  if (anomaly.metric === "latency") {
+    return [
+      "Add response caching for frequently accessed data",
+      "Implement pagination for large result sets",
+      "Optimize database queries with proper indexing",
+      "Consider adding a GraphQL DataLoader for batching"
+    ];
+  }
+  if (anomaly.metric === "error-rate") {
+    return [
+      "Add input validation at the contract level",
+      "Implement retry policy with exponential backoff",
+      "Add circuit breaker for external dependencies",
+      "Enhance error logging for better debugging"
+    ];
+  }
+  return [
+    "Review resource allocation and scaling policies",
+    "Check for upstream routing or load balancer issues",
+    "Validate feature flag configurations",
+    "Monitor dependency health metrics"
+  ];
+}
+
+// src/lib/runtime-context.tsx
+import { createContext, useContext } from "react";
+"use client";
+var TemplateRuntimeContext = createContext(null);
+function useTemplateRuntime() {
+  const context = useContext(TemplateRuntimeContext);
+  if (!context) {
+    throw new Error("useTemplateRuntime must be used within a TemplateRuntimeProvider");
+  }
+  return context;
+}
+
+// src/hooks/useBehaviorTracking.ts
+import { useCallback as useCallback2, useEffect as useEffect2, useMemo as useMemo2, useRef as useRef2, useState as useState2 } from "react";
+"use client";
+var BEHAVIOR_STORAGE_KEY = "contractspec-behavior-data";
+var ALL_FEATURES = [
+  "playground",
+  "specs",
+  "builder",
+  "markdown",
+  "evolution",
+  "canvas_add",
+  "canvas_delete",
+  "spec_save",
+  "spec_validate",
+  "ai_suggestions"
+];
+function useBehaviorTracking(templateId) {
+  const [events, setEvents] = useState2([]);
+  const sessionStartRef = useRef2(new Date);
+  const [eventCount, setEventCount] = useState2(0);
+  useEffect2(() => {
+    try {
+      const stored = localStorage.getItem(BEHAVIOR_STORAGE_KEY);
+      if (stored) {
+        const data = JSON.parse(stored);
+        setEvents(data.events.map((e) => ({
+          ...e,
+          timestamp: new Date(e.timestamp)
+        })));
+        sessionStartRef.current = new Date(data.sessionStart);
+      }
+    } catch {}
+  }, []);
+  useEffect2(() => {
+    if (events.length > 0) {
+      try {
+        localStorage.setItem(BEHAVIOR_STORAGE_KEY, JSON.stringify({
+          events: events.map((e) => ({
+            ...e,
+            timestamp: e.timestamp.toISOString()
+          })),
+          sessionStart: sessionStartRef.current.toISOString()
+        }));
+      } catch {}
+    }
+  }, [events]);
+  const trackEvent = useCallback2((type, metadata) => {
+    const event = {
+      type,
+      timestamp: new Date,
+      templateId,
+      metadata
+    };
+    setEvents((prev) => [...prev, event]);
+    setEventCount((prev) => prev + 1);
+  }, [templateId]);
+  const getEventsByType = useCallback2((type) => {
+    return events.filter((e) => e.type === type);
+  }, [events]);
+  const getSummary = useCallback2(() => {
+    const now = new Date;
+    const sessionDuration = now.getTime() - sessionStartRef.current.getTime();
+    const templateCounts = new Map;
+    for (const event of events) {
+      const count = templateCounts.get(event.templateId) ?? 0;
+      templateCounts.set(event.templateId, count + 1);
+    }
+    const mostUsedTemplates = Array.from(templateCounts.entries()).map(([templateId2, count]) => ({ templateId: templateId2, count })).sort((a, b) => b.count - a.count).slice(0, 3);
+    const modeCounts = new Map;
+    for (const event of events) {
+      if (event.type === "mode_change" && event.metadata?.mode) {
+        const mode = event.metadata.mode;
+        const count = modeCounts.get(mode) ?? 0;
+        modeCounts.set(mode, count + 1);
+      }
+    }
+    const mostUsedModes = Array.from(modeCounts.entries()).map(([mode, count]) => ({ mode, count })).sort((a, b) => b.count - a.count);
+    const featuresUsed = new Set;
+    for (const event of events) {
+      if (event.type === "mode_change" && event.metadata?.mode) {
+        featuresUsed.add(event.metadata.mode);
+      }
+      if (event.type === "feature_usage" && event.metadata?.feature) {
+        featuresUsed.add(event.metadata.feature);
+      }
+      if (event.type === "canvas_interaction") {
+        const action = event.metadata?.action;
+        if (action === "add")
+          featuresUsed.add("canvas_add");
+        if (action === "delete")
+          featuresUsed.add("canvas_delete");
+      }
+      if (event.type === "spec_edit") {
+        const action = event.metadata?.action;
+        if (action === "save")
+          featuresUsed.add("spec_save");
+        if (action === "validate")
+          featuresUsed.add("spec_validate");
+      }
+    }
+    const unusedFeatures = ALL_FEATURES.filter((f) => !featuresUsed.has(f));
+    const errorCount = events.filter((e) => e.type === "error").length;
+    const recommendations = generateRecommendations(Array.from(featuresUsed), unusedFeatures, mostUsedModes, events.length);
+    return {
+      totalEvents: events.length,
+      sessionDuration,
+      mostUsedTemplates,
+      mostUsedModes,
+      featuresUsed: Array.from(featuresUsed),
+      unusedFeatures,
+      errorCount,
+      recommendations
+    };
+  }, [events]);
+  const clear = useCallback2(() => {
+    setEvents([]);
+    setEventCount(0);
+    sessionStartRef.current = new Date;
+    localStorage.removeItem(BEHAVIOR_STORAGE_KEY);
+  }, []);
+  return useMemo2(() => ({
+    trackEvent,
+    getSummary,
+    getEventsByType,
+    eventCount,
+    sessionStart: sessionStartRef.current,
+    clear
+  }), [trackEvent, getSummary, getEventsByType, eventCount, clear]);
+}
+function generateRecommendations(featuresUsed, unusedFeatures, mostUsedModes, totalEvents) {
+  const recommendations = [];
+  if (unusedFeatures.includes("evolution")) {
+    recommendations.push("Try the AI Evolution mode to get automated improvement suggestions");
+  }
+  if (unusedFeatures.includes("markdown")) {
+    recommendations.push("Use Markdown preview to see documentation for your specs");
+  }
+  if (unusedFeatures.includes("builder")) {
+    recommendations.push("Explore the Visual Builder to design your UI components");
+  }
+  if (!featuresUsed.includes("spec_validate") && featuresUsed.includes("specs")) {
+    recommendations.push("Don't forget to validate your specs before saving");
+  }
+  if (featuresUsed.includes("evolution") && !featuresUsed.includes("ai_suggestions")) {
+    recommendations.push("Generate AI suggestions to get actionable improvement recommendations");
+  }
+  if (totalEvents > 50) {
+    recommendations.push("Great engagement! Consider saving your work regularly");
+  }
+  if (mostUsedModes.length === 1) {
+    recommendations.push("Try different modes to explore all sandbox capabilities");
+  }
+  return recommendations;
+}
+
+// src/utils/generateSpecFromTemplate.ts
+function generateSpecFromTemplate(template) {
+  const templateId = template?.id ?? "unknown";
+  if (!template) {
+    return generateDefaultSpec(templateId);
+  }
+  switch (templateId) {
+    case "crm-pipeline":
+      return generateCrmPipelineSpec(template.schema.contracts);
+    case "saas-boilerplate":
+      return generateSaasBoilerplateSpec(template.schema.contracts);
+    case "agent-console":
+      return generateAgentConsoleSpec(template.schema.contracts);
+    case "todos-app":
+      return generateTodosSpec(template.schema.contracts);
+    case "messaging-app":
+      return generateMessagingSpec(template.schema.contracts);
+    case "recipe-app-i18n":
+      return generateRecipeSpec(template.schema.contracts);
+    default:
+      return generateDefaultSpec(templateId);
+  }
+}
+function generateCrmPipelineSpec(contracts) {
+  return `// CRM Pipeline Specs
+// Contracts: ${contracts.join(", ")}
+
+contractSpec("crm.deal.updateStage.v1", {
+  goal: "Move a deal to a different pipeline stage",
+  transport: { gql: { mutation: "updateDealStage" } },
+  io: {
+    input: { 
+      dealId: "string",
+      stageId: "string",
+      notes: "string?"
+    },
+    output: { 
+      deal: {
+        id: "string",
+        stage: "string",
+        probability: "number",
+        value: "number"
+      }
+    }
+  },
+  events: ["deal.stage.changed"],
+  policy: { auth: "user", rbac: "org:sales" }
+});
+
+contractSpec("crm.deal.create.v1", {
+  goal: "Create a new deal in the pipeline",
+  transport: { gql: { mutation: "createDeal" } },
+  io: {
+    input: { 
+      title: "string",
+      value: "number",
+      contactId: "string",
+      stageId: "string",
+      ownerId: "string?"
+    },
+    output: { 
+      deal: {
+        id: "string",
+        title: "string",
+        value: "number",
+        stage: "string",
+        createdAt: "ISO8601"
+      }
+    }
+  },
+  events: ["deal.created"]
+});
+
+contractSpec("crm.contact.list.v1", {
+  goal: "List contacts with filtering and pagination",
+  transport: { gql: { query: "listContacts" } },
+  io: {
+    input: { 
+      filter: {
+        search: "string?",
+        companyId: "string?",
+        tags: "string[]?"
+      },
+      pagination: {
+        page: "number",
+        limit: "number"
+      }
+    },
+    output: { 
+      contacts: "array<Contact>",
+      total: "number",
+      hasMore: "boolean"
+    }
+  }
+});`;
+}
+function generateSaasBoilerplateSpec(contracts) {
+  return `// SaaS Boilerplate Specs
+// Contracts: ${contracts.join(", ")}
+
+contractSpec("saas.project.create.v1", {
+  goal: "Create a new project in an organization",
+  transport: { gql: { mutation: "createProject" } },
+  io: {
+    input: { 
+      orgId: "string",
+      name: "string",
+      description: "string?"
+    },
+    output: { 
+      project: {
+        id: "string",
+        name: "string",
+        description: "string?",
+        createdAt: "ISO8601"
+      }
+    }
+  },
+  policy: { auth: "user", rbac: "org:member" }
+});
+
+contractSpec("saas.billing.recordUsage.v1", {
+  goal: "Record usage for billing purposes",
+  transport: { gql: { mutation: "recordUsage" } },
+  io: {
+    input: { 
+      orgId: "string",
+      metric: "enum<'api_calls'|'storage_gb'|'seats'>",
+      quantity: "number",
+      timestamp: "ISO8601?"
+    },
+    output: { 
+      usage: {
+        id: "string",
+        metric: "string",
+        quantity: "number",
+        recordedAt: "ISO8601"
+      }
+    }
+  },
+  events: ["billing.usage.recorded"]
+});
+
+contractSpec("saas.settings.update.v1", {
+  goal: "Update organization or user settings",
+  transport: { gql: { mutation: "updateSettings" } },
+  io: {
+    input: { 
+      scope: "enum<'org'|'user'>",
+      targetId: "string",
+      settings: "Record<string, unknown>"
+    },
+    output: { 
+      settings: {
+        scope: "string",
+        values: "Record<string, unknown>",
+        updatedAt: "ISO8601"
+      }
+    }
+  },
+  events: ["settings.updated"]
+});`;
+}
+function generateAgentConsoleSpec(contracts) {
+  return `// Agent Console Specs
+// Contracts: ${contracts.join(", ")}
+
+contractSpec("agent.run.execute.v1", {
+  goal: "Execute an agent run with specified tools",
+  transport: { gql: { mutation: "executeAgentRun" } },
+  io: {
+    input: { 
+      agentId: "string",
+      input: "string",
+      tools: "string[]?",
+      maxSteps: "number?"
+    },
+    output: { 
+      runId: "string",
+      status: "enum<'running'|'completed'|'failed'>",
+      steps: "number"
+    }
+  },
+  events: ["run.started", "run.completed", "run.failed"]
+});
+
+contractSpec("agent.tool.create.v1", {
+  goal: "Register a new tool in the tool registry",
+  transport: { gql: { mutation: "createTool" } },
+  io: {
+    input: { 
+      name: "string",
+      description: "string",
+      category: "enum<'code'|'data'|'api'|'file'|'custom'>",
+      schema: "JSONSchema",
+      handler: "string"
+    },
+    output: { 
+      tool: {
+        id: "string",
+        name: "string",
+        category: "string",
+        createdAt: "ISO8601"
+      }
+    }
+  },
+  events: ["tool.created"]
+});
+
+contractSpec("agent.agent.create.v1", {
+  goal: "Create a new AI agent configuration",
+  transport: { gql: { mutation: "createAgent" } },
+  io: {
+    input: { 
+      name: "string",
+      description: "string",
+      model: "string",
+      systemPrompt: "string?",
+      tools: "string[]?"
+    },
+    output: { 
+      agent: {
+        id: "string",
+        name: "string",
+        model: "string",
+        toolCount: "number",
+        createdAt: "ISO8601"
+      }
+    }
+  },
+  events: ["agent.created"]
+});`;
+}
+function generateTodosSpec(contracts) {
+  return `// To-dos App Specs
+// Contracts: ${contracts.join(", ")}
+
+contractSpec("tasks.board.v1", {
+  goal: "Assign and approve craft work",
+  transport: { gql: { field: "tasksBoard" } },
+  io: {
+    input: { 
+      tenantId: "string", 
+      assignee: "string?",
+      status: "enum<'pending'|'in_progress'|'completed'>?"
+    },
+    output: { 
+      tasks: "array<Task>",
+      summary: {
+        total: "number",
+        completed: "number",
+        overdue: "number"
+      }
+    }
+  }
+});
+
+contractSpec("tasks.create.v1", {
+  goal: "Create a new task",
+  transport: { gql: { mutation: "createTask" } },
+  io: {
+    input: { 
+      title: "string",
+      description: "string?",
+      assignee: "string?",
+      priority: "enum<'low'|'medium'|'high'>",
+      dueDate: "ISO8601?"
+    },
+    output: { 
+      task: {
+        id: "string",
+        title: "string",
+        status: "string",
+        createdAt: "ISO8601"
+      }
+    }
+  },
+  events: ["task.created"]
+});
+
+contractSpec("tasks.complete.v1", {
+  goal: "Mark a task as completed",
+  transport: { gql: { mutation: "completeTask" } },
+  io: {
+    input: { taskId: "string" },
+    output: { 
+      task: {
+        id: "string",
+        status: "string",
+        completedAt: "ISO8601"
+      }
+    }
+  },
+  events: ["task.completed"]
+});`;
+}
+function generateMessagingSpec(contracts) {
+  return `// Messaging App Specs
+// Contracts: ${contracts.join(", ")}
+
+contractSpec("messaging.send.v1", {
+  goal: "Deliver intent-rich updates",
+  io: {
+    input: { 
+      conversationId: "string", 
+      body: "richtext",
+      attachments: "array<Attachment>?"
+    },
+    output: { 
+      messageId: "string", 
+      deliveredAt: "ISO8601"
+    }
+  },
+  events: ["message.sent", "message.delivered"]
+});
+
+contractSpec("messaging.conversation.create.v1", {
+  goal: "Start a new conversation",
+  transport: { gql: { mutation: "createConversation" } },
+  io: {
+    input: { 
+      participants: "string[]",
+      title: "string?",
+      type: "enum<'direct'|'group'>"
+    },
+    output: { 
+      conversation: {
+        id: "string",
+        title: "string?",
+        participantCount: "number",
+        createdAt: "ISO8601"
+      }
+    }
+  },
+  events: ["conversation.created"]
+});
+
+contractSpec("messaging.read.v1", {
+  goal: "Mark messages as read",
+  transport: { gql: { mutation: "markRead" } },
+  io: {
+    input: { 
+      conversationId: "string",
+      messageIds: "string[]"
+    },
+    output: { 
+      readCount: "number",
+      readAt: "ISO8601"
+    }
+  },
+  events: ["message.read"]
+});`;
+}
+function generateRecipeSpec(contracts) {
+  return `// Recipe App (i18n) Specs
+// Contracts: ${contracts.join(", ")}
+
+contractSpec("recipes.lookup.v1", {
+  goal: "Serve bilingual rituals",
+  io: {
+    input: { 
+      locale: "enum<'EN'|'FR'>", 
+      slug: "string" 
+    },
+    output: { 
+      title: "string", 
+      content: "markdown",
+      ingredients: "array<Ingredient>",
+      instructions: "array<Instruction>"
+    }
+  }
+});
+
+contractSpec("recipes.list.v1", {
+  goal: "Browse recipes with filtering",
+  transport: { gql: { query: "listRecipes" } },
+  io: {
+    input: { 
+      locale: "enum<'EN'|'FR'>",
+      category: "string?",
+      search: "string?",
+      favorites: "boolean?"
+    },
+    output: { 
+      recipes: "array<RecipeSummary>",
+      categories: "array<Category>",
+      total: "number"
+    }
+  }
+});
+
+contractSpec("recipes.favorite.toggle.v1", {
+  goal: "Toggle recipe favorite status",
+  transport: { gql: { mutation: "toggleFavorite" } },
+  io: {
+    input: { recipeId: "string" },
+    output: { 
+      isFavorite: "boolean",
+      totalFavorites: "number"
+    }
+  },
+  events: ["recipe.favorited", "recipe.unfavorited"]
+});`;
+}
+function generateDefaultSpec(templateId) {
+  return `// ${templateId} Specs
+
+contractSpec("${templateId}.main.v1", {
+  goal: "Main operation for ${templateId}",
+  transport: { gql: { query: "main" } },
+  io: {
+    input: { 
+      id: "string"
+    },
+    output: { 
+      result: "unknown"
+    }
+  }
+});`;
+}
+
+// src/hooks/useSpecContent.ts
+import { useCallback as useCallback3, useEffect as useEffect3, useState as useState3 } from "react";
+"use client";
+var SPEC_STORAGE_KEY = "contractspec-spec-content";
+function useSpecContent(templateId) {
+  const { template } = useTemplateRuntime();
+  const [content, setContentState] = useState3("");
+  const [savedContent, setSavedContent] = useState3("");
+  const [loading, setLoading] = useState3(true);
+  const [validation, setValidation] = useState3(null);
+  const [lastSaved, setLastSaved] = useState3(null);
+  useEffect3(() => {
+    setLoading(true);
+    try {
+      const stored = localStorage.getItem(`${SPEC_STORAGE_KEY}-${templateId}`);
+      if (stored) {
+        const parsed = JSON.parse(stored);
+        if (parsed.content) {
+          setContentState(parsed.content);
+          setSavedContent(parsed.content);
+          setLastSaved(parsed.savedAt);
+        } else {
+          const generated = generateSpecFromTemplate(template);
+          setContentState(generated);
+          setSavedContent(generated);
+        }
+      } else {
+        const generated = generateSpecFromTemplate(template);
+        setContentState(generated);
+        setSavedContent(generated);
+      }
+    } catch {
+      const generated = generateSpecFromTemplate(template);
+      setContentState(generated);
+      setSavedContent(generated);
+    }
+    setLoading(false);
+  }, [templateId]);
+  const setContent = useCallback3((newContent) => {
+    setContentState(newContent);
+    setValidation(null);
+  }, []);
+  const save = useCallback3(() => {
+    try {
+      const savedAt = new Date().toISOString();
+      localStorage.setItem(`${SPEC_STORAGE_KEY}-${templateId}`, JSON.stringify({
+        content,
+        savedAt
+      }));
+      setSavedContent(content);
+      setLastSaved(savedAt);
+    } catch {}
+  }, [content, templateId]);
+  const validate = useCallback3(() => {
+    const errors = [];
+    const lines = content.split(`
+`);
+    if (!content.includes("contractSpec(")) {
+      errors.push({
+        line: 1,
+        message: "Spec must contain a contractSpec() definition",
+        severity: "error"
+      });
+    }
+    if (!content.includes("goal:")) {
+      errors.push({
+        line: 1,
+        message: "Spec should have a goal field",
+        severity: "warning"
+      });
+    }
+    if (!content.includes("io:")) {
+      errors.push({
+        line: 1,
+        message: "Spec should define io (input/output)",
+        severity: "warning"
+      });
+    }
+    const openBraces = (content.match(/{/g) ?? []).length;
+    const closeBraces = (content.match(/}/g) ?? []).length;
+    if (openBraces !== closeBraces) {
+      errors.push({
+        line: lines.length,
+        message: `Unbalanced braces: ${openBraces} opening, ${closeBraces} closing`,
+        severity: "error"
+      });
+    }
+    const openParens = (content.match(/\(/g) ?? []).length;
+    const closeParens = (content.match(/\)/g) ?? []).length;
+    if (openParens !== closeParens) {
+      errors.push({
+        line: lines.length,
+        message: `Unbalanced parentheses: ${openParens} opening, ${closeParens} closing`,
+        severity: "error"
+      });
+    }
+    lines.forEach((line, index) => {
+      const singleQuotes = (line.match(/'/g) ?? []).length;
+      const doubleQuotes = (line.match(/"/g) ?? []).length;
+      if (singleQuotes % 2 !== 0) {
+        errors.push({
+          line: index + 1,
+          message: "Unclosed single quote",
+          severity: "error"
+        });
+      }
+      if (doubleQuotes % 2 !== 0) {
+        errors.push({
+          line: index + 1,
+          message: "Unclosed double quote",
+          severity: "error"
+        });
+      }
+    });
+    const result = {
+      valid: errors.filter((e) => e.severity === "error").length === 0,
+      errors
+    };
+    setValidation(result);
+    return result;
+  }, [content]);
+  const reset = useCallback3(() => {
+    const generated = generateSpecFromTemplate(template);
+    setContentState(generated);
+    setSavedContent(generated);
+    setValidation(null);
+    setLastSaved(null);
+    try {
+      localStorage.removeItem(`${SPEC_STORAGE_KEY}-${templateId}`);
+    } catch {}
+  }, [templateId]);
+  return {
+    content,
+    loading,
+    isDirty: content !== savedContent,
+    validation,
+    setContent,
+    save,
+    validate,
+    reset,
+    lastSaved
+  };
+}
+
+// src/hooks/useWorkflowComposer.ts
+import { useCallback as useCallback4, useEffect as useEffect4, useMemo as useMemo3, useState as useState4 } from "react";
+"use client";
+function useWorkflowComposer(templateId) {
+  const [selectedWorkflow, setSelectedWorkflow] = useState4(null);
+  const [extensions, setExtensions] = useState4([]);
+  const [loading, _setLoading] = useState4(false);
+  const [error, _setError] = useState4(null);
+  const baseWorkflows = useMemo3(() => getTemplateWorkflows(templateId), [templateId]);
+  useEffect4(() => {
+    const firstWorkflow = baseWorkflows[0];
+    if (baseWorkflows.length > 0 && !selectedWorkflow && firstWorkflow) {
+      setSelectedWorkflow(firstWorkflow.meta.key);
+    }
+  }, [baseWorkflows, selectedWorkflow]);
+  const currentBase = useMemo3(() => {
+    return baseWorkflows.find((w) => w.meta.key === selectedWorkflow) ?? null;
+  }, [baseWorkflows, selectedWorkflow]);
+  const compose = useCallback4((scope) => {
+    if (!currentBase)
+      return null;
+    const applicableExtensions = extensions.filter((ext) => ext.workflow === currentBase.meta.key).filter((ext) => matchesScope(ext, scope)).sort((a, b) => (a.priority ?? 0) - (b.priority ?? 0));
+    if (applicableExtensions.length === 0) {
+      return currentBase;
+    }
+    let composedWorkflow = { ...currentBase, steps: [...currentBase.steps] };
+    for (const extension of applicableExtensions) {
+      composedWorkflow = applyExtension(composedWorkflow, extension);
+    }
+    return composedWorkflow;
+  }, [currentBase, extensions]);
+  const workflow = useMemo3(() => compose(), [compose]);
+  const selectWorkflow = useCallback4((workflowName) => {
+    setSelectedWorkflow(workflowName);
+  }, []);
+  const addExtension = useCallback4((extension) => {
+    setExtensions((prev) => [...prev, extension]);
+  }, []);
+  const removeExtension = useCallback4((workflowName, index) => {
+    setExtensions((prev) => {
+      const forWorkflow = prev.filter((e) => e.workflow === workflowName);
+      const others = prev.filter((e) => e.workflow !== workflowName);
+      forWorkflow.splice(index, 1);
+      return [...others, ...forWorkflow];
+    });
+  }, []);
+  const generateSpecCode = useCallback4(() => {
+    const composed = workflow;
+    if (!composed) {
+      return "// No workflow selected";
+    }
+    const stepsCode = composed.steps.map((step) => `    {
+      id: '${step.id}',
+      name: '${step.name}',
+      type: '${step.type}',${step.description ? `
+      description: '${step.description}',` : ""}${step.next ? `
+      next: ${JSON.stringify(step.next)},` : ""}${step.condition ? `
+      condition: '${step.condition}',` : ""}${step.timeout ? `
+      timeout: ${step.timeout},` : ""}${step.retries ? `
+      retries: ${step.retries},` : ""}${step.onError ? `
+      onError: '${step.onError}',` : ""}
+    }`).join(`,
+`);
+    const extensionsCode = extensions.length > 0 ? `
+
+// Extensions applied:
+${extensions.map((ext) => `// - ${ext.workflow} (priority: ${ext.priority ?? 0})${ext.customSteps?.length ? ` +${ext.customSteps.length} steps` : ""}${ext.hiddenSteps?.length ? ` -${ext.hiddenSteps.length} hidden` : ""}`).join(`
+`)}` : "";
+    return `// Workflow Spec: ${composed.meta.key} v${composed.meta.version}
+// Generated from ${templateId} template
+${extensionsCode}
+
+import { workflowSpec } from '@contractspec/lib.contracts/workflow';
+
+export const ${toCamelCase(composed.meta.key)}Workflow = workflowSpec({
+  meta: {
+    key: '${composed.meta.key}',
+    version: ${composed.meta.version},${composed.meta.description ? `
+    description: '${composed.meta.description}',` : ""}
+  },
+  start: '${composed.start}',
+  steps: [
+${stepsCode}
+  ],${composed.context ? `
+  context: ${JSON.stringify(composed.context, null, 2)},` : ""}
+});
+`;
+  }, [workflow, extensions, templateId]);
+  return {
+    workflow,
+    baseWorkflows,
+    extensions,
+    selectWorkflow,
+    addExtension,
+    removeExtension,
+    compose,
+    generateSpecCode,
+    loading,
+    error
+  };
+}
+function matchesScope(extension, scope) {
+  if (!scope)
+    return true;
+  if (extension.tenantId && extension.tenantId !== scope.tenantId) {
+    return false;
+  }
+  if (extension.role && extension.role !== scope.role) {
+    return false;
+  }
+  if (extension.device && extension.device !== scope.device) {
+    return false;
+  }
+  return true;
+}
+function applyExtension(workflow, extension) {
+  let steps = [...workflow.steps];
+  if (extension.hiddenSteps) {
+    steps = steps.filter((s) => !extension.hiddenSteps?.includes(s.id));
+  }
+  if (extension.customSteps) {
+    for (const injection of extension.customSteps) {
+      const stepToInject = {
+        ...injection.inject,
+        id: injection.id ?? injection.inject.id
+      };
+      if (injection.after) {
+        const afterIndex = steps.findIndex((s) => s.id === injection.after);
+        if (afterIndex !== -1) {
+          steps.splice(afterIndex + 1, 0, stepToInject);
+        }
+      } else if (injection.before) {
+        const beforeIndex = steps.findIndex((s) => s.id === injection.before);
+        if (beforeIndex !== -1) {
+          steps.splice(beforeIndex, 0, stepToInject);
+        }
+      } else {
+        steps.push(stepToInject);
+      }
+    }
+  }
+  return { ...workflow, steps };
+}
+function toCamelCase(str) {
+  return str.replace(/[^a-zA-Z0-9]+(.)/g, (_, c) => c.toUpperCase()).replace(/^./, (c) => c.toLowerCase());
+}
+function getTemplateWorkflows(templateId) {
+  const templateWorkflows = {
+    "crm-pipeline": [
+      {
+        meta: {
+          key: "deal.qualification",
+          version: "1.0.0",
+          description: "Deal qualification workflow"
+        },
+        start: "lead-received",
+        steps: [
+          {
+            id: "lead-received",
+            name: "Lead Received",
+            type: "action",
+            description: "New lead enters the pipeline",
+            next: "qualify-lead"
+          },
+          {
+            id: "qualify-lead",
+            name: "Qualify Lead",
+            type: "decision",
+            description: "Determine if lead meets qualification criteria",
+            next: ["qualified", "disqualified"],
+            condition: "lead.score >= threshold"
+          },
+          {
+            id: "qualified",
+            name: "Lead Qualified",
+            type: "action",
+            next: "assign-rep"
+          },
+          {
+            id: "disqualified",
+            name: "Lead Disqualified",
+            type: "end"
+          },
+          {
+            id: "assign-rep",
+            name: "Assign Sales Rep",
+            type: "action",
+            next: "complete"
+          },
+          {
+            id: "complete",
+            name: "Workflow Complete",
+            type: "end"
+          }
+        ]
+      },
+      {
+        meta: {
+          key: "deal.closing",
+          version: "1.0.0",
+          description: "Deal closing workflow"
+        },
+        start: "proposal-sent",
+        steps: [
+          {
+            id: "proposal-sent",
+            name: "Proposal Sent",
+            type: "action",
+            next: "wait-response"
+          },
+          {
+            id: "wait-response",
+            name: "Wait for Response",
+            type: "wait",
+            timeout: 604800000,
+            next: "negotiate",
+            onError: "follow-up"
+          },
+          {
+            id: "follow-up",
+            name: "Follow Up",
+            type: "action",
+            next: "wait-response",
+            retries: 3
+          },
+          {
+            id: "negotiate",
+            name: "Negotiation",
+            type: "action",
+            next: "finalize"
+          },
+          {
+            id: "finalize",
+            name: "Finalize Deal",
+            type: "decision",
+            next: ["won", "lost"],
+            condition: "deal.accepted"
+          },
+          {
+            id: "won",
+            name: "Deal Won",
+            type: "end"
+          },
+          {
+            id: "lost",
+            name: "Deal Lost",
+            type: "end"
+          }
+        ]
+      }
+    ],
+    "saas-boilerplate": [
+      {
+        meta: {
+          key: "user.onboarding",
+          version: "1.0.0",
+          description: "User onboarding workflow"
+        },
+        start: "signup",
+        steps: [
+          {
+            id: "signup",
+            name: "User Signup",
+            type: "action",
+            next: "verify-email"
+          },
+          {
+            id: "verify-email",
+            name: "Verify Email",
+            type: "wait",
+            timeout: 86400000,
+            next: "profile-setup",
+            onError: "resend-verification"
+          },
+          {
+            id: "resend-verification",
+            name: "Resend Verification",
+            type: "action",
+            next: "verify-email",
+            retries: 2
+          },
+          {
+            id: "profile-setup",
+            name: "Setup Profile",
+            type: "action",
+            next: "onboarding-tour"
+          },
+          {
+            id: "onboarding-tour",
+            name: "Onboarding Tour",
+            type: "action",
+            next: "complete"
+          },
+          {
+            id: "complete",
+            name: "Onboarding Complete",
+            type: "end"
+          }
+        ]
+      }
+    ],
+    "agent-console": [
+      {
+        meta: {
+          key: "agent.execution",
+          version: "1.0.0",
+          description: "Agent execution workflow"
+        },
+        start: "receive-task",
+        steps: [
+          {
+            id: "receive-task",
+            name: "Receive Task",
+            type: "action",
+            next: "plan-execution"
+          },
+          {
+            id: "plan-execution",
+            name: "Plan Execution",
+            type: "action",
+            next: "execute-steps"
+          },
+          {
+            id: "execute-steps",
+            name: "Execute Steps",
+            type: "parallel",
+            next: ["tool-call", "observe", "reason"]
+          },
+          {
+            id: "tool-call",
+            name: "Tool Call",
+            type: "action",
+            next: "evaluate"
+          },
+          {
+            id: "observe",
+            name: "Observe",
+            type: "action",
+            next: "evaluate"
+          },
+          {
+            id: "reason",
+            name: "Reason",
+            type: "action",
+            next: "evaluate"
+          },
+          {
+            id: "evaluate",
+            name: "Evaluate Result",
+            type: "decision",
+            condition: "task.isComplete",
+            next: ["complete", "execute-steps"]
+          },
+          {
+            id: "complete",
+            name: "Task Complete",
+            type: "end"
+          }
+        ]
+      }
+    ],
+    "todos-app": [
+      {
+        meta: {
+          key: "task.lifecycle",
+          version: "1.0.0",
+          description: "Task lifecycle workflow"
+        },
+        start: "created",
+        steps: [
+          {
+            id: "created",
+            name: "Task Created",
+            type: "action",
+            next: "in-progress"
+          },
+          {
+            id: "in-progress",
+            name: "In Progress",
+            type: "action",
+            next: "review"
+          },
+          {
+            id: "review",
+            name: "Review",
+            type: "decision",
+            condition: "task.approved",
+            next: ["done", "in-progress"]
+          },
+          {
+            id: "done",
+            name: "Done",
+            type: "end"
+          }
+        ]
+      }
+    ],
+    "messaging-app": [
+      {
+        meta: {
+          key: "message.delivery",
+          version: "1.0.0",
+          description: "Message delivery workflow"
+        },
+        start: "compose",
+        steps: [
+          {
+            id: "compose",
+            name: "Compose Message",
+            type: "action",
+            next: "send"
+          },
+          {
+            id: "send",
+            name: "Send Message",
+            type: "action",
+            next: "deliver"
+          },
+          {
+            id: "deliver",
+            name: "Deliver",
+            type: "decision",
+            condition: "recipient.online",
+            next: ["delivered", "queue"]
+          },
+          {
+            id: "queue",
+            name: "Queue for Delivery",
+            type: "wait",
+            next: "deliver"
+          },
+          {
+            id: "delivered",
+            name: "Message Delivered",
+            type: "action",
+            next: "read"
+          },
+          {
+            id: "read",
+            name: "Message Read",
+            type: "end"
+          }
+        ]
+      }
+    ],
+    "recipe-app-i18n": [
+      {
+        meta: {
+          key: "recipe.creation",
+          version: "1.0.0",
+          description: "Recipe creation workflow"
+        },
+        start: "draft",
+        steps: [
+          {
+            id: "draft",
+            name: "Draft Recipe",
+            type: "action",
+            next: "add-ingredients"
+          },
+          {
+            id: "add-ingredients",
+            name: "Add Ingredients",
+            type: "action",
+            next: "add-steps"
+          },
+          {
+            id: "add-steps",
+            name: "Add Steps",
+            type: "action",
+            next: "review"
+          },
+          {
+            id: "review",
+            name: "Review Recipe",
+            type: "decision",
+            condition: "recipe.isComplete",
+            next: ["publish", "draft"]
+          },
+          {
+            id: "publish",
+            name: "Publish Recipe",
+            type: "end"
+          }
+        ]
+      }
+    ]
+  };
+  return templateWorkflows[templateId] ?? [];
+}
+
+// src/hooks/useRegistryTemplates.ts
+import { useQuery } from "@tanstack/react-query";
+function useRegistryTemplates() {
+  return useQuery({
+    queryKey: ["registryTemplates"],
+    queryFn: async () => {
+      const registryUrl = process.env.NEXT_PUBLIC_CONTRACTSPEC_REGISTRY_URL ?? "";
+      if (!registryUrl)
+        return [];
+      const res = await fetch(`${registryUrl.replace(/\/$/, "")}/r/contractspec.json`, {
+        method: "GET",
+        headers: { Accept: "application/json" }
+      });
+      if (!res.ok)
+        return [];
+      const json = await res.json();
+      const items = json.items ?? [];
+      return items.filter((i) => i.type === "contractspec:template").map((i) => ({
+        id: i.name,
+        name: i.title ?? i.name,
+        description: i.description,
+        tags: i.meta?.tags ?? [],
+        source: "registry",
+        registryUrl
+      }));
+    }
+  });
+}
+export {
+  useWorkflowComposer,
+  useSpecContent,
+  useRegistryTemplates,
+  useEvolution,
+  useBehaviorTracking
+};