cyclecad 3.9.20 → 3.10.1

package/app/js/modules/ai-copilot.js

@@ -0,0 +1,274 @@
+limit',hint:'Rate-limited. Wait 60s or switch providers.'};
+  }
+  if(m.includes('missing')&&m.includes('key')){
+    return{kind:'no_key',hint:'Click 🔑 to add your API key.'};
+  }
+  return{kind:'other',hint:''};
+}
+
+async function callClaude(m,sys,u,k){const r=await fetch('https://api.anthropic.com/v1/messages',{method:'POST',headers:{'x-api-key':k,'anthropic-version':'2023-06-01','content-type':'application/json','anthropic-dangerous-direct-browser-access':'true'},body:JSON.stringify({model:m,max_tokens:4096,system:sys,messages:[{role:'user',content:u}]})});if(!r.ok)throw new Error(`Claude ${r.status}: ${(await r.text()).slice(0,400)}`);return(await r.json()).content?.[0]?.text||''}
+async function callGemini(m,sys,u,k){
+  // Try the requested model, then fall back to gemini-1.5-flash if the model is not found on v1beta
+  const fallbacks=[m,'gemini-1.5-flash','gemini-1.5-flash-latest'];
+  let lastErr;
+  for(const model of fallbacks){
+    try{
+      const r=await fetch(`https://generativelanguage.googleapis.com/v1beta/models/${model}:generateContent?key=${k}`,{method:'POST',headers:{'content-type':'application/json'},body:JSON.stringify({systemInstruction:{parts:[{text:sys}]},contents:[{role:'user',parts:[{text:u}]}],generationConfig:{temperature:0.2,maxOutputTokens:4096}})});
+      if(r.ok)return(await r.json()).candidates?.[0]?.content?.parts?.[0]?.text||'';
+      const errTxt=(await r.text()).slice(0,400);
+      lastErr=`Gemini ${r.status}: ${errTxt}`;
+      // Only fall through on 404; other errors (401, 429) should surface immediately
+      if(r.status!==404)throw new Error(lastErr);
+    }catch(e){
+      if(!e.message.startsWith('Gemini 404'))throw e;
+      lastErr=e.message;
+    }
+  }
+  throw new Error(lastErr||'All Gemini fallbacks failed');
+}
+async function callGroq(m,sys,u,k){const r=await fetch('https://api.groq.com/openai/v1/chat/completions',{method:'POST',headers:{'authorization':`Bearer ${k}`,'content-type':'application/json'},body:JSON.stringify({model:m,messages:[{role:'system',content:sys},{role:'user',content:u}],temperature:0.2,max_tokens:4096})});if(!r.ok)throw new Error(`Groq ${r.status}: ${(await r.text()).slice(0,400)}`);return(await r.json()).choices?.[0]?.message?.content||''}
+async function callLLM(mk,sys,u){const c=MODELS[mk];if(!c)throw new Error('Unknown model');const ak=keys()[c.keyField];if(!ak)throw new Error(`Missing ${c.keyField} key — click 🔑 to add one`);if(c.provider==='anthropic')return callClaude(c.model,sys,u,ak);if(c.provider==='gemini')return callGemini(c.model,sys,u,ak);if(c.provider==='groq')return callGroq(c.model,sys,u,ak)}
+
+function parseJson(t){let s=t.trim();const f=s.match(/```(?:json)?\s*([\s\S]*?)\s*```/);if(f)s=f[1];const a=s.indexOf('['),b=s.lastIndexOf(']');if(a<0||b<a)throw new Error('No JSON array');return JSON.parse(s.slice(a,b+1))}
+async function runStep(st){if(!window.cycleCAD?.execute)throw new Error('window.cycleCAD.execute unavailable');const r=window.cycleCAD.execute({method:st.method,params:st.params||{}});if(r?.ok===false)throw new Error(r.error||'step failed');return r}
+
+function log(kind,txt){
+  if(!S.els.log)return;
+  const d=document.createElement('div');
+  d.className=`aic-log-${kind}`;
+  d.textContent=({info:'ℹ',ok:'✓',warn:'⚠',err:'✗',run:'⋯',fail:'✗'})[kind]+' '+txt;
+  S.els.log.appendChild(d);
+  S.els.log.scrollTop=S.els.log.scrollHeight;
+}
+
+function showActionableError(errMsg){
+  const cls=classifyError(errMsg);
+  log('err',errMsg);
+  if(cls.hint){
+    const d=document.createElement('div');
+    d.className='aic-hint-line';
+    d.textContent='💡 '+cls.hint;
+    S.els.log.appendChild(d);
+  }
+  // Auto-suggest switching to a free model if current is paid and failed with no-credit/bad-key
+  if(cls.kind==='no_credit'||cls.kind==='bad_key'){
+    const cur=MODELS[S.els.model.value];
+    if(cur&&!cur.free){
+      const freeAvail=FREE_MODELS.filter(m=>keys()[MODELS[m].keyField]);
+      if(freeAvail.length){
+        const btn=document.createElement('button');
+        btn.className='aic-switch-btn';
+        btn.textContent=`⚡ Switch to ${MODELS[freeAvail[0]].label}`;
+        btn.onclick=()=>{S.els.model.value=freeAvail[0];updateBanner();log('info',`Switched to ${MODELS[freeAvail[0]].label}`);btn.remove()};
+        S.els.log.appendChild(btn);
+      }else{
+        const d=document.createElement('div');
+        d.className='aic-hint-line';
+        d.textContent='→ Get a free Gemini key at aistudio.google.com/apikey (or Groq at console.groq.com/keys), then click 🔑 to add it.';
+        S.els.log.appendChild(d);
+      }
+    }
+  }
+  S.els.log.scrollTop=S.els.log.scrollHeight;
+}
+
+function progress(c,t){const p=t?Math.round(c/t*100):0;S.els.prog.style.width=p+'%';S.els.stat.textContent=`${c}/${t}`}
+
+function updateBanner(){
+  if(!S.els.banner)return;
+  const mk=S.els.model?.value;
+  if(!mk){S.els.banner.style.display='none';return}
+  const cfg=MODELS[mk];
+  const ak=keys()[cfg.keyField];
+  if(!ak){
+    S.els.banner.className='aic-banner aic-banner-warn';
+    S.els.banner.innerHTML=`⚠ No <b>${cfg.keyField}</b> key set. Click 🔑 to add one.`;
+    S.els.banner.style.display='block';
+  }else{
+    S.els.banner.className='aic-banner aic-banner-ok';
+    S.els.banner.innerHTML=` ✓ Ready — using <b>${cfg.label}</b>${cfg.free?' (free tier)':''}`;
+    S.els.banner.style.display='block';
+  }
+}
+
+async function run(){
+  if(S.running)return;
+  const p=S.els.prompt.value.trim();
+  if(!p){log('warn','Enter a prompt first.');return}
+  S.running=true;S.aborted=false;
+  S.els.go.disabled=true;S.els.stop.disabled=false;
+  S.els.log.innerHTML='';
+  log('info',`Planning with ${MODELS[S.els.model.value].label}...`);
+  try{
+    const t=await callLLM(S.els.model.value,SYS,p);
+    // Mark this model as working
+    setLastWorkingModel(S.els.model.value);
+    let plan;
+    try{plan=parseJson(t)}catch(e){
+      log('err',`Parse: ${e.message}`);
+      log('warn',t.slice(0,300));
+      return;
+    }
+    if(!Array.isArray(plan)||!plan.length){log('warn','Empty plan');return}
+    log('ok',`Got ${plan.length}-step plan. Executing...`);
+    S.plan=plan;S.results=[];S.errors=[];
+    let retries=0;
+    for(let i=0;i<S.plan.length;i++){
+      if(S.aborted){log('warn','Aborted.');return}
+      const st=S.plan[i];
+      log('run',`step ${i+1}: ${st.method} — ${st.note||''}`);
+      progress(i,S.plan.length);
+      await new Promise(r=>setTimeout(r,150));
+      try{
+        const r=await runStep(st);
+        S.results.push(r);
+        log('ok',`step ${i+1} done`);
+      }catch(e){
+        log('fail',`step ${i+1}: ${e.message}`);
+        S.errors.push({step:st,error:e.message});
+        if(retries>=2){log('warn','Max retries — stopping.');return}
+        retries++;
+        log('info',`Asking for recovery plan (${retries}/2)...`);
+        const rem=S.plan.slice(i+1);
+        const rp=`Previous step failed:\nFAILED_STEP: ${JSON.stringify(st)}\nERROR: ${e.message}\nREMAINING: ${JSON.stringify(rem)}\nGoal: ${p}\nReturn replacement JSON array of steps to recover and finish.`;
+        try{
+          const rt=await callLLM(S.els.model.value,SYS,rp);
+          const newPlan=parseJson(rt);
+          S.plan=S.plan.slice(0,i+1).concat(newPlan);
+          log('info',`Inserted ${newPlan.length} recovery steps`);
+        }catch(e2){
+          showActionableError(`Recovery failed: ${e2.message}`);
+          return;
+        }
+      }
+    }
+    progress(S.plan.length,S.plan.length);
+    log('ok',`Done — ${S.results.length}/${S.plan.length} succeeded`);
+  }catch(e){
+    showActionableError(e.message);
+  }finally{
+    S.running=false;
+    S.els.go.disabled=false;
+    S.els.stop.disabled=true;
+    updateBanner();
+  }
+}
+
+function abort(){if(S.running){S.aborted=true;log('warn','Abort signaled')}}
+
+function askKey(){
+  const f=MODELS[S.els.model.value].keyField;
+  const c=keys()[f]||'';
+  const n=prompt(`Enter ${f} API key (stored in localStorage):`,c);
+  if(n!==null&&n!==c){
+    saveKey(f,n.trim());
+    log('ok',`${f} key saved`);
+    updateBanner();
+  }
+}
+
+function buildUI(){
+  const p=document.createElement('div');
+  p.innerHTML=`<style>
+.aic{display:flex;flex-direction:column;gap:10px;padding:12px;color:#e2e8f0;background:#1a202c;font:13px -apple-system,sans-serif;min-width:320px;max-width:420px}
+.aic h3{margin:0;font-size:15px;color:#38bdf8}
+.aic-banner{padding:6px 8px;border-radius:4px;font-size:11px;display:none}
+.aic-banner-ok{background:rgba(16,185,129,0.1);color:#10b981;border-left:2px solid #10b981}
+.aic-banner-warn{background:rgba(245,158,11,0.1);color:#f59e0b;border-left:2px solid #f59e0b}
+.aic-row{display:flex;gap:6px;align-items:center}
+.aic-row select{flex:1;background:#0f172a;color:#e2e8f0;border:1px solid #334155;border-radius:4px;padding:4px 6px;font-size:12px}
+.aic-row button{background:#334155;color:#e2e8f0;border:0;border-radius:4px;padding:4px 8px;cursor:pointer}
+.aic textarea{width:100%;min-height:80px;background:#0f172a;color:#e2e8f0;border:1px solid #334155;border-radius:4px;padding:8px;font:13px inherit;resize:vertical;box-sizing:border-box}
+.aic-btns{display:flex;gap:8px}
+.aic-btns button{flex:1;padding:8px 12px;border:0;border-radius:4px;font-weight:600;cursor:pointer}
+.aic-go{background:#38bdf8;color:#0f172a}
+.aic-go:disabled{background:#475569;color:#94a3b8;cursor:not-allowed}
+.aic-stop{background:#ef4444;color:#fff}
+.aic-stop:disabled{background:#334155;color:#64748b;cursor:not-allowed}
+.aic-bar{height:4px;background:#334155;border-radius:2px;overflow:hidden}
+.aic-prog{height:100%;width:0;background:linear-gradient(90deg,#38bdf8,#8b5cf6);transition:width .2s}
+.aic-stat{font-size:11px;color:#94a3b8;text-align:right}
+.aic-log{background:#0f172a;border:1px solid #1e293b;border-radius:4px;padding:8px;min-height:160px;max-height:320px;overflow-y:auto;font:11px 'SF Mono',monospace;line-height:1.5}
+.aic-log>div{white-space:pre-wrap}
+.aic-log-info{color:#94a3b8}
+.aic-log-ok{color:#10b981}
+.aic-log-warn{color:#f59e0b}
+.aic-log-err,.aic-log-fail{color:#ef4444}
+.aic-log-run{color:#38bdf8}
+.aic-hint-line{color:#fbbf24;padding:4px 8px;margin-top:4px;background:rgba(251,191,36,0.08);border-radius:4px}
+.aic-switch-btn{display:block;margin:6px 0;padding:6px 10px;background:#38bdf8;color:#0f172a;border:0;border-radius:4px;font-weight:600;cursor:pointer;font-size:12px;width:auto}
+.aic-switch-btn:hover{background:#0ea5e9}
+.aic-hint{font-size:11px;color:#64748b}
+</style>
+<div class="aic">
+<h3>🤖 AI Copilot</h3>
+<div class="aic-banner"></div>
+<div class="aic-row">
+<select class="aic-model"></select>
+<button class="aic-key" title="Set API key">🔑</button>
+</div>
+<textarea class="aic-prompt" placeholder="Describe what to build. Examples:
+• create a Raspberry Pi 4B case with port cutouts
+• design a 50mm mounting bracket with 4 holes on 40mm PCD
+• make a hex nut M10, 8mm thick"></textarea>
+<div class="aic-btns">
+<button class="aic-go">⚡ Generate</button>
+<button class="aic-stop" disabled>⏹ Stop</button>
+</div>
+<div class="aic-bar"><div class="aic-prog"></div></div>
+<div class="aic-stat">0/0</div>
+<div class="aic-log"></div>
+<div class="aic-hint">Multi-step plan. LLM retries up to 2× on step failure. Cmd/Ctrl+Enter to run.</div>
+</div>`;
+  S.els.prompt=p.querySelector('.aic-prompt');
+  S.els.go=p.querySelector('.aic-go');
+  S.els.stop=p.querySelector('.aic-stop');
+  S.els.log=p.querySelector('.aic-log');
+  S.els.stat=p.querySelector('.aic-stat');
+  S.els.prog=p.querySelector('.aic-prog');
+  S.els.model=p.querySelector('.aic-model');
+  S.els.banner=p.querySelector('.aic-banner');
+
+  for(const[k_c]of Object.entries(MODELS)){
+    const o=document.createElement('option');
+    o.value=k_;o.textContent=c.label;
+    S.els.model.appendChild(o);
+  }
+
+  // Smart default: prefer last-working model, else first free model with a key,
+  // else first paid model with a key, else gemini
+  const storedKeys=keys();
+  const lastWorking=getLastWorkingModel();
+  if(lastWorking&&MODELS[lastWorking]&&storedKeys[MODELS[lastWorking].keyField]){
+    S.els.model.value=lastWorking;
+  }else{
+    const firstUsable=Object.keys(MODELS).find(k=>storedKeys[MODELS[k].keyField]&&MODELS[k].free)
+      ||Object.keys(MODELS).find(k=>storedKeys[MODELS[k].keyField])
+      ||'gemini';
+    S.els.model.value=firstUsable;
+  }
+
+  S.els.go.onclick=run;
+  S.els.stop.onclick=abort;
+  p.querySelector('.aic-key').onclick=askKey;
+  S.els.model.onchange=updateBanner;
+  S.els.prompt.onkeydown=e=>{
+    if(e.key==='Enter'&&(e.metaKey||e.ctrlKey)){e.preventDefault();run()}
+  };
+
+  // Initial banner
+  setTimeout(updateBanner,0);
+  return p;
+}
+
+window.CycleCAD=window.CycleCAD||{};
+window.CycleCAD.AICopilot={
+  init:()=>true,
+  getUI:buildUI,
+  execute:(c,a)=>c==='generate'&&a?.prompt?(S.els.prompt&&(S.els.prompt.value=a.prompt),run()):c==='stop'?abort():null,
+  go:run,
+  abort,
+  getState:()=>({running:S.running,stepIndex:S.plan.length-1,results:S.results.length,errors:S.errors.length,model:S.els.model?.value}),
+};
+console.log('AI Copilot v1.1 module loaded');
+})();

package/app/tests/ai-copilot-tests.html

@@ -0,0 +1,230 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="UTF-8">
+<title>AI Copilot Tests — cycleCAD</title>
+<style>
+  * { margin: 0; padding: 0; box-sizing: border-box; }
+  body { font-family: -apple-system, sans-serif; background: #0f172a; color: #e2e8f0; display: flex; height: 100vh; }
+  .app { flex: 0 0 70%; border: 1px solid #2d3748; }
+  .app iframe { width: 100%; height: 100%; border: 0; }
+  .panel { flex: 0 0 30%; display: flex; flex-direction: column; background: #1a202c; border-left: 1px solid #2d3748; }
+  .header { padding: 16px; border-bottom: 1px solid #2d3748; }
+  .header h1 { font-size: 16px; color: #38bdf8; margin-bottom: 10px; }
+  .stats { display: grid; grid-template-columns: 1fr 1fr 1fr; gap: 6px; font-size: 11px; }
+  .stat { padding: 6px; background: #1e293b; border-radius: 4px; border-left: 2px solid #64748b; }
+  .stat.pass { border-left-color: #10b981; }
+  .stat.fail { border-left-color: #ef4444; }
+  .stat.skip { border-left-color: #f59e0b; }
+  .stat-label { font-size: 10px; color: #94a3b8; }
+  .stat-value { font-size: 16px; font-weight: 600; }
+  .controls { padding: 10px; border-bottom: 1px solid #2d3748; display: flex; gap: 6px; }
+  .controls button { flex: 1; padding: 6px 8px; background: #334155; color: #e2e8f0; border: 0; border-radius: 4px; font-size: 11px; cursor: pointer; }
+  .controls button:hover { background: #475569; }
+  .controls button.primary { background: #38bdf8; color: #0f172a; font-weight: 600; }
+  .log { flex: 1; overflow-y: auto; padding: 10px; font: 11px 'SF Mono', monospace; }
+  .entry { padding: 4px 6px; margin-bottom: 2px; border-radius: 3px; white-space: pre-wrap; }
+  .entry.pass { background: rgba(16, 185, 129, 0.1); color: #10b981; }
+  .entry.fail { background: rgba(239, 68, 68, 0.1); color: #ef4444; }
+  .entry.info { color: #94a3b8; }
+</style>
+</head>
+<body>
+  <div class="app"><iframe id="appFrame" src="/app/index.html"></iframe></div>
+  <div class="panel">
+    <div class="header">
+      <h1>🤖 AI Copilot Tests</h1>
+      <div class="stats">
+        <div class="stat pass"><div class="stat-label">PASSED</div><div class="stat-value" id="passCount">0</div></div>
+        <div class="stat fail"><div class="stat-label">FAILED</div><div class="stat-value" id="failCount">0</div></div>
+        <div class="stat skip"><div class="stat-label">SKIPPED</div><div class="stat-value" id="skipCount">0</div></div>
+      </div>
+    </div>
+    <div class="controls">
+      <button class="primary" onclick="runAllTests()">▶ Run All</button>
+      <button onclick="document.getElementById('log').innerHTML=''">Clear</button>
+    </div>
+    <div class="log" id="log"></div>
+  </div>
+
+<script>
+let passCount = 0, failCount = 0, skipCount = 0;
+
+function log(msg, cls = 'info') {
+  const e = document.createElement('div');
+  e.className = 'entry ' + cls;
+  e.textContent = msg;
+  document.getElementById('log').appendChild(e);
+}
+
+function updateCounts() {
+  document.getElementById('passCount').textContent = passCount;
+  document.getElementById('failCount').textContent = failCount;
+  document.getElementById('skipCount').textContent = skipCount;
+}
+
+async function waitForFrame() {
+  const iframe = document.getElementById('appFrame');
+  iframe.src = 'http://localhost:3000/app/index.html?cb=' + Date.now();
+  await new Promise(r => iframe.addEventListener('load', r, { once: true }));
+  const deadline = Date.now() + 15000;
+  while (Date.now() < deadline) {
+    if (iframe.contentWindow.CycleCAD?.AICopilot) return true;
+    await new Promise(r => setTimeout(r, 200));
+  }
+  return false;
+}
+
+const tests = [
+  // MODULE LOADING
+  { name: 'AICopilot module exists', fn: () => {
+    const f = document.getElementById('appFrame').contentWindow;
+    return !!f.CycleCAD?.AICopilot;
+  }},
+  { name: 'getUI returns valid panel', fn: () => {
+    const f = document.getElementById('appFrame').contentWindow;
+    const ui = f.CycleCAD.AICopilot.getUI();
+    return !!ui && (ui instanceof f.HTMLElement || ui instanceof f.Node || typeof ui === 'object');
+  }},
+  { name: 'init function exists', fn: () => {
+    const f = document.getElementById('appFrame').contentWindow;
+    return typeof f.CycleCAD.AICopilot.init === 'function';
+  }},
+  { name: 'execute function exists', fn: () => {
+    const f = document.getElementById('appFrame').contentWindow;
+    return typeof f.CycleCAD.AICopilot.execute === 'function';
+  }},
+  { name: 'go function exists', fn: () => {
+    const f = document.getElementById('appFrame').contentWindow;
+    return typeof f.CycleCAD.AICopilot.go === 'function';
+  }},
+  { name: 'abort function exists', fn: () => {
+    const f = document.getElementById('appFrame').contentWindow;
+    return typeof f.CycleCAD.AICopilot.abort === 'function';
+  }},
+  { name: 'getState returns object', fn: () => {
+    const f = document.getElementById('appFrame').contentWindow;
+    const s = f.CycleCAD.AICopilot.getState();
+    return s && typeof s === 'object' && 'running' in s;
+  }},
+  // UI STRUCTURE
+  { name: 'UI has prompt textarea', fn: () => {
+    const f = document.getElementById('appFrame').contentWindow;
+    const ui = f.CycleCAD.AICopilot.getUI();
+    return !!ui.querySelector('.aic-prompt');
+  }},
+  { name: 'UI has Generate button', fn: () => {
+    const f = document.getElementById('appFrame').contentWindow;
+    const ui = f.CycleCAD.AICopilot.getUI();
+    return !!ui.querySelector('.aic-go');
+  }},
+  { name: 'UI has Stop button', fn: () => {
+    const f = document.getElementById('appFrame').contentWindow;
+    const ui = f.CycleCAD.AICopilot.getUI();
+    return !!ui.querySelector('.aic-stop');
+  }},
+  { name: 'UI has model dropdown', fn: () => {
+    const f = document.getElementById('appFrame').contentWindow;
+    const ui = f.CycleCAD.AICopilot.getUI();
+    const s = ui.querySelector('.aic-model');
+    return s && s.tagName === 'SELECT';
+  }},
+  { name: 'Model dropdown has 5 options', fn: () => {
+    const f = document.getElementById('appFrame').contentWindow;
+    const ui = f.CycleCAD.AICopilot.getUI();
+    const s = ui.querySelector('.aic-model');
+    return s && s.options.length === 5;
+  }},
+  { name: 'UI has API key button', fn: () => {
+    const f = document.getElementById('appFrame').contentWindow;
+    const ui = f.CycleCAD.AICopilot.getUI();
+    return !!ui.querySelector('.aic-key');
+  }},
+  { name: 'UI has progress bar', fn: () => {
+    const f = document.getElementById('appFrame').contentWindow;
+    const ui = f.CycleCAD.AICopilot.getUI();
+    return !!ui.querySelector('.aic-prog');
+  }},
+  { name: 'UI has log area', fn: () => {
+    const f = document.getElementById('appFrame').contentWindow;
+    const ui = f.CycleCAD.AICopilot.getUI();
+    return !!ui.querySelector('.aic-log');
+  }},
+  // MENU INTEGRATION
+  { name: 'Tools menu has AI Copilot entry', fn: () => {
+    const f = document.getElementById('appFrame').contentWindow;
+    const btn = f.document.querySelector('[data-action="tools-ai-copilot"]');
+    return !!btn;
+  }},
+  // BEHAVIOR
+  { name: 'execute("stop") returns without throwing', fn: () => {
+    const f = document.getElementById('appFrame').contentWindow;
+    f.CycleCAD.AICopilot.execute('stop');
+    return true;
+  }},
+  { name: 'getState.running is false initially', fn: () => {
+    const f = document.getElementById('appFrame').contentWindow;
+    return f.CycleCAD.AICopilot.getState().running === false;
+  }},
+  { name: 'Missing key shows friendly error', async fn() {
+    const f = document.getElementById('appFrame').contentWindow;
+    // Clear keys temporarily
+    const saved = f.localStorage.getItem('cyclecad_api_keys');
+    f.localStorage.setItem('cyclecad_api_keys', '{}');
+    try {
+      const ui = f.CycleCAD.AICopilot.getUI();
+      const prompt = ui.querySelector('.aic-prompt');
+      const log = ui.querySelector('.aic-log');
+      prompt.value = 'test';
+      await f.CycleCAD.AICopilot.go();
+      await new Promise(r => setTimeout(r, 500));
+      // Expect a warning about missing key in the log
+      return log.textContent.toLowerCase().includes('key') || log.textContent.toLowerCase().includes('missing');
+    } finally {
+      if (saved !== null) f.localStorage.setItem('cyclecad_api_keys', saved);
+    }
+  }},
+  { name: 'Empty prompt shows warning', async fn() {
+    const f = document.getElementById('appFrame').contentWindow;
+    const ui = f.CycleCAD.AICopilot.getUI();
+    const prompt = ui.querySelector('.aic-prompt');
+    const log = ui.querySelector('.aic-log');
+    log.innerHTML = '';
+    prompt.value = '';
+    await f.CycleCAD.AICopilot.go();
+    await new Promise(r => setTimeout(r, 200));
+    return log.textContent.toLowerCase().includes('prompt') || log.textContent.toLowerCase().includes('enter');
+  }},
+];
+
+async function runAllTests() {
+  passCount = failCount = skipCount = 0;
+  updateCounts();
+  document.getElementById('log').innerHTML = '';
+
+  log('Waiting for app iframe to populate window.CycleCAD.AICopilot...', 'info');
+  const ready = await waitForFrame();
+  log(ready ? '✓ App iframe ready. Running tests.' : '⚠ App did not populate AICopilot within 15s — tests may fail.', ready ? 'pass' : 'fail');
+
+  for (const t of tests) {
+    try {
+      const result = await Promise.resolve(t.fn());
+      if (result) {
+        passCount++;
+        log(`✓ ${t.name}`, 'pass');
+      } else {
+        failCount++;
+        log(`✗ ${t.name}`, 'fail');
+      }
+    } catch (e) {
+      failCount++;
+      log(`✗ ${t.name}: ${e.message}`, 'fail');
+    }
+    updateCounts();
+  }
+
+  log(`\nDone — ${passCount} passed, ${failCount} failed, ${skipCount} skipped.`, passCount === tests.length ? 'pass' : 'info');
+}
+</script>
+</body>
+</html>

package/docs/AI-COPILOT-TUTORIAL.md

@@ -0,0 +1,150 @@
+# AI Copilot — hands-on tutorial
+
+Goal: design a **Raspberry Pi 4B enclosure** from scratch using only natural language, in under 2 minutes.
+
+## Prereqs
+
+- cycleCAD v3.10.0 or later (`npm install cyclecad@latest`, or pull from GitHub)
+- An API key for one of: Anthropic Claude, Google Gemini, or Groq
+- Modern browser with `fetch` support (any recent Chrome/Safari/Firefox)
+
+## Step 1 — Open the copilot
+
+Tools menu → **AI Copilot (multi-step)**. A dialog opens with a model dropdown, a prompt textarea, Generate/Stop buttons, a progress bar, and a live log.
+
+## Step 2 — Set your API key
+
+Click the **🔑** icon next to the model dropdown. A browser prompt asks for your key. Paste it, click OK. The key is stored in `localStorage['cyclecad_api_keys']` — it never leaves your machine.
+
+If you have a Claude key, the model dropdown defaults to **Claude Sonnet 4.6**. If not, it defaults to **Gemini 2.0 Flash (free)**.
+
+## Step 3 — First prompt
+
+Start simple to validate everything works:
+
+```
+box 100x50x20 with 3mm fillet
+```
+
+Click **⚡ Generate**. You should see:
+
+```
+ℹ Planning with Claude Sonnet 4.6...
+✓ Got 7-step plan. Executing...
+⋯ step 1: sketch.start — Start sketch
+✓ step 1 done
+⋯ step 2: sketch.rect — Rectangle
+✓ step 2 done
+⋯ step 3: sketch.end — Finish
+✓ step 3 done
+⋯ step 4: ops.extrude — Extrude
+✓ step 4 done
+⋯ step 5: ops.fillet — Fillet edges
+✓ step 5 done
+⋯ step 6: view.set — Isometric
+✓ step 6 done
+⋯ step 7: view.fit — Fit
+✓ step 7 done
+✓ Done — 7/7 succeeded
+```
+
+The 3D viewport will show a 100×50×20 box with rounded edges, framed in isometric view.
+
+## Step 4 — The real deal
+
+Clear the prompt and paste:
+
+```
+create a Raspberry Pi 4B case. Use board specs: 85×56mm, 1.4mm thick, mounting holes at (3.5, 3.5), (61.5, 3.5), (3.5, 52.5), (61.5, 52.5) Ø2.7. Add:
+- 2mm wall thickness
+- 12mm internal height
+- USB cutout on the right side
+- HDMI cutout next to USB
+- Ethernet cutout on the left
+- SD card cutout on one short side
+- vent slots on top
+- 3mm fillet on outer edges
+```
+
+Click **⚡ Generate**. This triggers a larger plan — typically 12-18 steps. The log fills in as each step runs. Watch the viewport: the case base appears, then shells into a hollow box, mounting posts rise, port cutouts carve out, vent slots appear, edges round over.
+
+Typical elapsed time: 25-60 seconds (most of it is the LLM thinking; the Agent API calls themselves are instant).
+
+## Step 5 — Handling errors gracefully
+
+Try this deliberately tricky prompt:
+
+```
+extrude the current sketch 10mm
+```
+
+There's no active sketch — the first call to `ops.extrude` will fail. Watch the log:
+
+```
+⋯ step 1: ops.extrude — Extrude sketch
+✗ step 1: No active sketch
+ℹ Asking for recovery plan (1/2)...
+ℹ Inserted 3 recovery steps
+⋯ step 2: sketch.start — Start a sketch first
+✓ step 2 done
+⋯ step 3: sketch.rect — Default rectangle
+✓ step 3 done
+⋯ step 4: sketch.end — Finish sketch
+✓ step 4 done
+⋯ step 5: ops.extrude — Now extrude
+✓ step 5 done
+```
+
+The copilot self-corrected: it inserted the missing sketch steps and resumed.
+
+## Step 6 — Programmatic access
+
+You can kick off a prompt from the browser console:
+
+```js
+window.CycleCAD.AICopilot.execute('generate', {
+  prompt: 'design a 50mm mounting bracket with 4 M5 holes on 40mm PCD'
+});
+```
+
+Monitor state:
+
+```js
+setInterval(() => {
+  const s = window.CycleCAD.AICopilot.getState();
+  console.log(`${s.running ? 'running' : 'idle'} — ${s.results} ok / ${s.errors} errs`);
+}, 500);
+```
+
+Stop mid-run:
+
+```js
+window.CycleCAD.AICopilot.abort();
+```
+
+## Step 7 — Tune your prompts
+
+| Prompt quality | Example |
+|---|---|
+| **Weak**: *"make a case"* | Claude guesses dimensions |
+| **Better**: *"make a 100×60×25 case with 2mm wall"* | Claude knows the envelope |
+| **Best**: *"make a 100×60×25 case. 2mm wall. 4 M3 mounting holes at (5,5), (95,5), (5,55), (95,55). 3mm fillet on outer edges. One USB-C cutout (9×4) on the front face centered horizontally, 10mm up from the base."* | Claude gets it right in one shot |
+
+**Rule of thumb**: mention every dimension you care about. Claude is good at filling gaps with sensible defaults, but precise inputs produce precise parts.
+
+## Step 8 — What's next
+
+- Read `docs/AI-COPILOT.md` for the full feature reference
+- Check `docs/API-REFERENCE.md` for the underlying Agent API the copilot drives
+- Try composing prompts: generate a base plate → save → regenerate with additional features
+
+## Troubleshooting
+
+| Symptom | Fix |
+|---|---|
+| `Missing anthropic key — click 🔑` | Set the key for the selected provider |
+| `Claude 401` | Key is invalid or expired. Regenerate at console.anthropic.com |
+| `Gemini 429` | Rate-limited on free tier. Wait 60s or switch to Groq |
+| Plan executes but nothing appears in viewport | Agent API may not be loaded. Check console for `window.cycleCAD.execute is not available` |
+| Model returns prose instead of JSON | Rerun — sometimes models forget the format. The parser tries to be lenient but fails on pure prose. |
+| Recovery loop doesn't fire | You're already at the 2-retry limit or the recovery call itself failed. Check log for `Recovery failed: ...` |