@floless/app 0.54.1 → 0.56.0

package/dist/web/aware.js

@@ -531,11 +531,208 @@
     });
   }
 
+  // ── Per-workflow onboarding beacon ──────────────────────────────────────────
+  // "New to you" = the user hasn't completed a first real Run of this workflow and
+  // hasn't dismissed its guide. Three bits per app id, persisted per origin; all
+  // default false, so every workflow starts new. Never touches the .flo or lock.
+  const LS_GUIDE = 'floless:guide';
+  function guideStateAll() {
+    try { const v = JSON.parse(localStorage.getItem(LS_GUIDE) || '{}'); return (v && typeof v === 'object') ? v : {}; }
+    catch { return {}; }
+  }
+  function guideFor(id) { return guideStateAll()[id] || {}; }
+  function setGuide(id, patch) {
+    if (!id) return;
+    try {
+      const all = guideStateAll();
+      all[id] = { ...(all[id] || {}), ...patch };
+      localStorage.setItem(LS_GUIDE, JSON.stringify(all));
+    } catch { /* private mode / quota */ }
+  }
+  // The beacon pulses while a workflow is new to the user.
+  function beaconIsNew(id) { const g = guideFor(id); return !g.firstRunDone && !g.dismissed; }
+
+  function paintBeacon(app) {
+    const $b = document.getElementById('guide-beacon');
+    if (!$b) return;
+    if (!app) { $b.hidden = true; $b.classList.remove('is-new', 'spotlit'); return; }
+    const isNew = beaconIsNew(app.id);
+    $b.hidden = false;
+    $b.classList.toggle('is-new', isNew);
+    const ico = $b.querySelector('.guide-beacon-ico');
+    const label = $b.querySelector('.guide-beacon-label');
+    // Monochrome dingbats (✦ / ?), not colour emoji — the locked baseline uses text
+    // glyphs (★, ▸); the pulse, not an emoji, is the "new" signal.
+    if (ico) ico.textContent = isNew ? '✦' : '?';
+    if (label) label.textContent = isNew ? 'Start here' : 'Guide';
+    $b.dataset.tip = isNew
+      ? 'New here? See what this workflow does and how to run it.'
+      : 'Open the guide for this workflow.';
+    $b.setAttribute('aria-label', (isNew ? 'Start here — guide for ' : 'Guide for ') + (app.displayName || app.id));
+  }
+
+  // Record a completed real run → the workflow is no longer new; calm the beacon (and
+  // refresh an open guide so the Run step ticks). Idempotent.
+  function markFirstRunDone(id) {
+    if (!id || guideFor(id).firstRunDone) return;
+    setGuide(id, { firstRunDone: true });
+    if (id === currentId) {
+      const app = apps.get(id);
+      if (app) paintBeacon(app);
+      const $m = document.getElementById('guide-modal');
+      if ($m && $m.classList.contains('show')) renderGuide();
+    }
+  }
+
+  // The guide panel's live checklist — each step ticks from real app state. The
+  // "Set inputs" row is omitted for a workflow with no declared inputs.
+  function guideSteps(app) {
+    const steps = [];
+    if (Array.isArray(app.inputs) && app.inputs.length) {
+      const vals = currentInputs();
+      const allSet = app.inputs.every((i) => {
+        const v = vals[i.name];
+        return v !== undefined && v !== null && String(v).trim() !== '';
+      });
+      steps.push({ label: 'Set inputs', note: 'the values this workflow runs with', done: allSet });
+    }
+    steps.push({ label: 'Compile', note: 'freeze the approved lock', done: app.runState === 'ready' });
+    steps.push({ label: 'Run', note: 'against the live host — results render here', done: !!guideFor(app.id).firstRunDone });
+    return steps;
+  }
+
+  function renderGuide() {
+    const app = currentId && apps.get(currentId);
+    const $body = document.getElementById('guide-body');
+    const $title = document.getElementById('guide-title');
+    const $eyebrow = document.getElementById('guide-eyebrow');
+    if (!app || !$body) return;
+    if ($title) $title.textContent = app.displayName || app.id;
+    if ($eyebrow) $eyebrow.textContent = beaconIsNew(app.id) ? '✦ Start here' : '✦ Workflow guide';
+    const desc = (app.description || '').trim();
+    const descHtml = desc
+      ? `<div class="guide-desc">${desc.split(/\n{2,}/).map((p) => `<p>${mdInline(escapeHtml(p.trim()))}</p>`).join('')}</div>`
+      : `<div class="guide-desc guide-desc-empty"><p>A ${app.nodes.length}-step workflow. Set its inputs, Compile to freeze the approved lock, then Run it against your live host.</p></div>`;
+    const steps = guideSteps(app);
+    const curIdx = steps.findIndex((s) => !s.done);
+    const stepsHtml = `<ol class="guide-steps" role="list">${steps.map((s, i) => {
+      const state = s.done ? 'done' : i === curIdx ? 'current' : 'todo';
+      // Shape carries state, not colour alone: ✓ done · → current · ☐ to-do.
+      const box = s.done ? '✓' : i === curIdx ? '→' : '☐';
+      const cur = i === curIdx ? ' aria-current="step"' : '';
+      return `<li class="guide-step ${state}"${cur}><span class="guide-box" aria-hidden="true">${box}</span>` +
+        `<span class="guide-step-text"><span class="guide-step-label">${escapeHtml(s.label)}</span> ` +
+        `<span class="guide-step-note">— ${escapeHtml(s.note)}</span></span>` +
+        `<span class="sr-only">${s.done ? '(done)' : i === curIdx ? '(next step)' : '(to do)'}</span></li>`;
+    }).join('')}</ol>`;
+    const walkHint = `<div class="guide-walk-hint">A bigger workflow? <strong>Walk me through it</strong> hands off to your terminal AI for a step-by-step tour using this workflow's own skill.</div>`;
+    $body.innerHTML =
+      `<div class="guide-section-label">What this does</div>` + descHtml +
+      `<div class="guide-section-label">How to go through it</div>` + stepsHtml + walkHint;
+  }
+
+  function openGuide() {
+    if (!currentId) { showToast('open a workflow first', 'warn'); return; }
+    renderGuide();
+    const $m = document.getElementById('guide-modal');
+    showModal($m);
+    // Focus the dialog shell (not a button) so the checklist is read first; Tab then
+    // moves to Got it → Walk me through it. Focus returns to the beacon on close.
+    const shell = $m && $m.querySelector('.modal.guide');
+    if (shell) { try { shell.focus(); } catch { /* not focusable */ } }
+  }
+  // Closing the guide (Got it / backdrop / Esc) marks it seen → the beacon stops
+  // pulsing even before a first run (the user has looked; don't nag).
+  function closeGuide() {
+    if (currentId) {
+      setGuide(currentId, { dismissed: true });
+      const app = apps.get(currentId);
+      if (app) paintBeacon(app);
+    }
+    hideModal(document.getElementById('guide-modal'));
+    const $b = document.getElementById('guide-beacon');
+    if ($b && !$b.hidden) { try { $b.focus(); } catch { /* */ } }
+  }
+
+  // "Walk me through it" → relay the ask to the terminal AI, the house way: queue a
+  // request AND copy the prompt, toast, light the footer requests pill, list it in the
+  // Requests window. The UI never guides itself; it hands intent to the assistant.
+  async function requestGuide() {
+    if (!currentId) { showToast('open a workflow first', 'warn'); return; }
+    try {
+      const { request } = await api('/api/guide', { method: 'POST', body: JSON.stringify({ appId: currentId }) });
+      const copied = await copyToClipboard(markedInstruction(request));
+      showToast(copied ? 'Sent to your assistant · copied to clipboard' : 'Sent to your assistant', 'ok');
+      appendNarration(`Asked your terminal AI to walk you through <code>${escapeHtml(currentId)}</code> — watch the glowing <strong>requests</strong> pill (bottom-right), or switch to your terminal.${copied ? ' The prompt is also on your clipboard.' : ''}`);
+      loadRequests();
+      closeGuide(); // engaging with the guidance also calms the beacon
+    } catch (e) { reportErr(e); }
+  }
+
+  // ≡ menu "New workflow…" — the create-from-scratch sibling of requestGuide(). No open
+  // workflow to target (none exists yet), so no currentId gate: relay the ask to the
+  // terminal AI the same house way (queue a request, copy the marked prompt, toast, light
+  // the requests pill). The UI never authors the workflow itself; the AI's
+  // floless-app-new-workflow skill does, step by step.
+  async function requestNewWorkflow() {
+    try {
+      const { request } = await api('/api/guide-new', { method: 'POST', body: '{}' });
+      const copied = await copyToClipboard(markedInstruction(request));
+      showToast(copied ? 'Building your workflow · copied to clipboard' : 'Building your workflow', 'ok');
+      appendNarration(`Asked your terminal AI to interview you and <strong>build a new workflow</strong> from scratch — watch the glowing <strong>requests</strong> pill (bottom-right), or switch to your terminal.${copied ? ' The prompt is also on your clipboard.' : ''}`);
+      loadRequests();
+    } catch (e) { reportErr(e); }
+  }
+
+  // ── First-open spotlight (one-time per workflow) ────────────────────────────
+  // Dims the canvas, raises the beacon, and points a small caption at it; Esc /
+  // click-away / either button dismiss it for good. Slice 2 of the onboarding beacon.
+  let _spotlightKey = null;
+  function maybeSpotlight(app) {
+    if (!app) return;
+    const g = guideFor(app.id);
+    if (g.spotlightShown || g.dismissed || g.firstRunDone) return;
+    if (document.querySelector('.modal-backdrop.show')) return; // don't pile on a dialog
+    if ($contractEditor && !$contractEditor.hidden) return;
+    setTimeout(() => {
+      if (currentId !== app.id) return; // switched away during the delay
+      if (guideFor(app.id).spotlightShown) return;
+      if (document.querySelector('.modal-backdrop.show')) return;
+      showSpotlight(app);
+    }, 700);
+  }
+  function showSpotlight(app) {
+    const $sp = document.getElementById('guide-spotlight');
+    const $b = document.getElementById('guide-beacon');
+    if (!$sp || !$b || $b.hidden) return;
+    setGuide(app.id, { spotlightShown: true });
+    $b.classList.add('spotlit');
+    $sp.hidden = false;
+    // Anchor the caption bubble just under the beacon, right-aligned to it.
+    const bubble = $sp.querySelector('.guide-spotlight-bubble');
+    if (bubble) {
+      const r = $b.getBoundingClientRect();
+      bubble.style.top = (r.bottom + 10) + 'px';
+      bubble.style.right = Math.max(8, window.innerWidth - r.right) + 'px';
+    }
+    _spotlightKey = (e) => { if (e.key === 'Escape') { e.preventDefault(); hideSpotlight(); } };
+    document.addEventListener('keydown', _spotlightKey);
+    if (bubble) { try { bubble.focus(); } catch { /* */ } }
+  }
+  function hideSpotlight() {
+    const $sp = document.getElementById('guide-spotlight');
+    const $b = document.getElementById('guide-beacon');
+    if ($sp) $sp.hidden = true;
+    if ($b) $b.classList.remove('spotlit');
+    if (_spotlightKey) { document.removeEventListener('keydown', _spotlightKey); _spotlightKey = null; }
+  }
+
   // ── load / select / compile / run ───────────────────────────────────────────
 
   let _wfUpdates = []; // workflow updates available, keyed by app id — polled by refreshWorkflowUpdates() below
 
   async function loadApp(id) {
+    hideSpotlight(); // a spotlight pointing at the previous app's beacon must clear on switch
     const { app } = await api(`/api/app/${encodeURIComponent(id)}`);
     apps.set(id, app);
     currentId = id;
@@ -555,8 +752,10 @@
     seedAppInputs(app);
     markSpecialNodes();
     paintGate(app);
+    paintBeacon(app); // pulse "Start here" while this workflow is new to the user
     refreshDirtyIndicator(); // clean app → dot off; switched back to a dirty one → dot on
     renderWfUpdatePill(); // show the "↑ Update to vX" pill when THIS app has a newer published version
+    maybeSpotlight(app); // one-time first-open spotlight pointing at the beacon (slice 2)
   }
 
   async function loadApps() {
@@ -574,6 +773,8 @@
       if ($menuBakeItem) $menuBakeItem.disabled = true;
       if ($wfTrigger) $wfTrigger.disabled = true;
       setComboTriggerLabel('no workflows installed');
+      paintBeacon(null); // no workflow open → hide the per-workflow beacon
+      hideSpotlight();
       renderCanvasPlaceholder('empty');
       return;
     }
@@ -814,8 +1015,18 @@
       if (v != null) localStorage.setItem(lsInputsKey(toId), v);
     } catch { /* private mode / quota */ }
   }
+  // A rename is the SAME workflow under a new id → carry its onboarding-seen state so it
+  // doesn't re-pulse "Start here" / re-show the spotlight. (Not done on duplicate: a copy
+  // is a genuinely new workflow that the user hasn't run, so it should start new.)
+  function migrateGuideLS(fromId, toId) {
+    try {
+      const all = guideStateAll();
+      if (all[fromId]) { all[toId] = all[fromId]; localStorage.setItem(LS_GUIDE, JSON.stringify(all)); }
+    } catch { /* private mode / quota */ }
+  }
   function dropClientAppState(id) {
     try { localStorage.removeItem(lsInputsKey(id)); } catch { /* ignore */ }
+    try { const all = guideStateAll(); if (all[id]) { delete all[id]; localStorage.setItem(LS_GUIDE, JSON.stringify(all)); } } catch { /* ignore */ }
     appInputValues.delete(id); dirtyBaseline.delete(id); apps.delete(id);
   }
 
@@ -843,6 +1054,7 @@
       // so a rename never silently drops the user's inputs (#85 review). loadApp() only seeds
       // inputs when the id is absent, so pre-setting them here preserves unsaved edits.
       migrateInputsLS(oldId, r.id);
+      migrateGuideLS(oldId, r.id); // carry onboarding-seen state so the renamed workflow doesn't re-pulse
       if (appInputValues.has(oldId)) appInputValues.set(r.id, appInputValues.get(oldId));
       if (dirtyBaseline.has(oldId)) dirtyBaseline.set(r.id, dirtyBaseline.get(oldId));
       const wasOpen = currentId === oldId;
@@ -1767,6 +1979,7 @@
         $reportSub.innerHTML = `Live 3D view from <code>${escapeHtml(nodeId)}</code>${inputBadge ? ' · ' + escapeHtml(inputBadge) : ''} — drag to orbit, scroll to zoom, click an element to inspect.`;
       }
       paintReport(html, interactive);
+      markFirstRunDone(app.id); // a real run rendered → this workflow is no longer "new" (app captured pre-await; a mid-run switch must not mark the wrong workflow)
       lastReportByApp.set(currentId, { nodeId, label: inputBadge, html, interactive });
       $reportModal.dataset.html = '1';
       appendNarration(`Rendered the ${interactive ? '3D view' : 'report'} from <strong>${escapeHtml(nodeId)}</strong>${inputBadge ? ' (' + escapeHtml(inputBadge) + ')' : ''} — live run against the model.`);
@@ -2538,6 +2751,7 @@
   // app.js's doOpen/doSave are reassigned from this file).
   const _handleMenuAction = handleMenuAction;
   handleMenuAction = function (action) {
+    if (action === 'new-workflow') { requestNewWorkflow(); return; }
     if (action === 'graft') { openGraftModal(); return; }
     if (action === 'bake') { openBakeModal(); return; }
     if (action === 'import') { triggerImport(); return; }
@@ -3215,6 +3429,7 @@
       appendNarration(simulate
         ? `Simulated run complete · ${steps} node${steps === 1 ? '' : 's'} stubbed (no host needed) · see the <strong>Execution</strong> tab.`
         : `Run complete · ${steps} node${steps === 1 ? '' : 's'} against the live model · see the <strong>Execution</strong> tab.`);
+      if (!simulate) markFirstRunDone(app.id); // a real run completed → calm the beacon (app captured pre-await)
     } catch (e) {
       const msg = (e && e.message) ? e.message : String(e);
       if (cancelRequested) {
@@ -4116,6 +4331,12 @@
         : '';
       return `In floless app "${req.appId}", re-read & re-bake${where} per the floless-app-rebake skill: ${req.instruction}${snaps}`;
     }
+    if (req.type === 'guide') {
+      return `Walk me through the floless workflow "${req.appId}" — explain in plain English what it does and how to run it (set its inputs → Compile → ▶ Run). Use your floless-app-${req.appId} skill if one exists; otherwise read the workflow's own description and node notes from GET /api/app/${req.appId} and explain from those. This is a guided explanation — don't change anything.`;
+    }
+    if (req.type === 'new-workflow') {
+      return `Help me build a brand-new floless workflow from scratch, step by step, with your floless-app-new-workflow skill. Ask me what I want it to do, then before writing any node confirm the agents it needs are installed (offer to install a missing one from the catalogue, or to report a not-yet-existing agent as an idea). Author the .flo node by node, verifying each step is correct (plain-English descriptions, validate, compile, a real run), and finish by installing → Compile → ▶ Run so I can see it work and approve.`;
+    }
     return '';
   }
 
@@ -4126,6 +4347,11 @@
     tweak: 'floless-app-workflows',
     'ui-customize': 'floless-app-ui',
     rebake: 'floless-app-rebake',
+    // The guided-tour ask is picked up by onboarding; the instruction body names the
+    // per-app floless-app-<appId> skill for depth when one exists.
+    guide: 'floless-app-onboarding',
+    // Build-a-workflow-from-scratch: its own guide skill (interview → author → verify).
+    'new-workflow': 'floless-app-new-workflow',
   };
 
   // The COPIED form of a request: instructionFor() prefixed with a self-identifying
@@ -4220,7 +4446,7 @@
       return;
     }
     $list.innerHTML = pendingRequests.map((r) => {
-      const label = r.type === 'use-template' ? 'template' : r.type === 'ui-customize' ? 'dashboard' : r.type === 'rebake' ? 're-bake' : 'tweak';
+      const label = r.type === 'use-template' ? 'template' : r.type === 'ui-customize' ? 'dashboard' : r.type === 'rebake' ? 're-bake' : r.type === 'guide' ? 'guide' : r.type === 'new-workflow' ? 'new workflow' : 'tweak';
       const badgeCls = r.type === 'tweak' || r.type === 'ui-customize' || r.type === 'rebake' ? 'req-type req-type-tweak' : 'req-type';
       const target = r.type === 'tweak' && r.nodeId
         ? ` · node <code>${escapeHtml(r.nodeId)}</code>`
@@ -5034,6 +5260,7 @@
     try {
       const res = await api('/api/trigger-run', { method: 'POST', body: JSON.stringify({ id, inputs: currentInputs() }) });
       foregroundTrigger = { appId: id, sessionId: res.sessionId, firedCount: 0 };
+      markFirstRunDone(id); // a real live session started → a streaming workflow's "first run" is no longer new
       syncRunControls(); // header ■ Stop run becomes reachable; Run disabled while live
       paintForegroundListening();
       appendNarration(`Live session started for <strong>${escapeHtml(id)}</strong> — the report updates on every event. Click <strong>■ Stop run</strong> (top right) to end it.`);
@@ -5718,6 +5945,25 @@
     if (e.key === 'Escape' && $reqModal && $reqModal.classList.contains('show')) $reqModal.classList.remove('show');
   });
 
+  // Per-workflow onboarding beacon + guide panel + first-open spotlight.
+  const $guideBeaconBtn = document.getElementById('guide-beacon');
+  if ($guideBeaconBtn) $guideBeaconBtn.onclick = () => { hideSpotlight(); openGuide(); };
+  const $guideModal = document.getElementById('guide-modal');
+  const $guideGot = document.getElementById('guide-got-it');
+  if ($guideGot) $guideGot.onclick = () => closeGuide();
+  const $guideWalk = document.getElementById('guide-walk');
+  if ($guideWalk) $guideWalk.onclick = () => requestGuide();
+  if ($guideModal) onBackdropDismiss($guideModal, () => closeGuide());
+  document.addEventListener('keydown', (e) => {
+    if (e.key === 'Escape' && $guideModal && $guideModal.classList.contains('show')) closeGuide();
+  });
+  const $spotGot = document.getElementById('guide-spotlight-got');
+  if ($spotGot) $spotGot.onclick = () => hideSpotlight();
+  const $spotShow = document.getElementById('guide-spotlight-show');
+  if ($spotShow) $spotShow.onclick = () => { hideSpotlight(); openGuide(); };
+  const $spotlightEl = document.getElementById('guide-spotlight');
+  if ($spotlightEl) $spotlightEl.onclick = (e) => { if (e.target === $spotlightEl) hideSpotlight(); };
+
   // Pull all workspace data (agents/templates/requests + the apps list). Factored
   // out of bootWorkspace so the health poll can re-pull it after the server comes
   // back from a boot-time outage (setServerStatus → recovery).

package/dist/web/index.html

@@ -58,6 +58,13 @@
         <!-- Agents (⊞) and Routines (⏱) buttons moved into the ≡ menu in #149
              (Ctrl+G / Ctrl+R); the toolbar keeps only the run-critical controls. -->
         <span class="ctl-sep" aria-hidden="true"></span>
+        <!-- Per-workflow onboarding beacon. Pulses "✨ Start here" while this workflow is
+             new to the user (no first Run completed, not dismissed); calms to a quiet
+             "❔ Guide" after — always clickable for re-reference. Hidden until an app loads. -->
+        <button id="guide-beacon" class="guide-beacon" type="button" hidden aria-haspopup="dialog" data-tip="New here? See what this workflow does and how to run it.">
+          <span class="guide-beacon-ico" aria-hidden="true">✦</span>
+          <span class="guide-beacon-label">Start here</span>
+        </button>
         <span class="run-state" id="run-state" role="status" aria-live="polite"></span>
         <button id="compile-btn" data-tip="Compile + approve → freeze the .lock">⎙ Compile</button>
         <button id="sim-btn" data-tip="Simulate: stub every node from its output schema — no live host is contacted. Validates the workflow's composition end-to-end, even when the real agents aren't connected yet.">Simulate</button>
@@ -269,6 +276,10 @@
       <span class="menu-label">Save inputs</span>
       <span class="menu-kbd">Ctrl+S</span>
     </button>
+    <button class="menu-item" data-action="new-workflow" role="menuitem">
+      <span class="menu-icon" aria-hidden="true"><svg viewBox="0 0 24 24"><path d="M15 2H6a2 2 0 0 0-2 2v16a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2V7z"/><path d="M14 2v4a2 2 0 0 0 2 2h4"/><path d="M9 15h6"/><path d="M12 18v-6"/></svg></span>
+      <span class="menu-label">New workflow…</span>
+    </button>
     <button class="menu-item" data-action="import" role="menuitem">
       <span class="menu-icon" aria-hidden="true"><svg viewBox="0 0 24 24"><path d="M12 3v12m0 0-4-4m4 4 4-4"/><path d="M3 17v2a2 2 0 0 0 2 2h14a2 2 0 0 0 2-2v-2"/></svg></span>
       <span class="menu-label">Import workflow…</span>
@@ -511,6 +522,37 @@
     </div>
   </div>
 
+  <!-- Per-workflow onboarding "Start here" guide. Surfaces the workflow's plain-English
+       description + a live "Set inputs → Compile → Run" checklist (ticks from real state),
+       and relays a "walk me through it" ask to the terminal AI. A styled modal — never a
+       native dialog; body (#guide-body) is rendered per-open in aware.js. -->
+  <div class="modal-backdrop" id="guide-modal">
+    <div class="modal guide" role="dialog" aria-modal="true" aria-labelledby="guide-title" tabindex="-1">
+      <div class="guide-eyebrow" id="guide-eyebrow">✦ Start here</div>
+      <div class="modal-title" id="guide-title">Workflow</div>
+      <div class="modal-sub">What this workflow does, and how to go through it.</div>
+      <div id="guide-body"></div>
+      <div class="modal-actions">
+        <button id="guide-got-it">Got it</button>
+        <button id="guide-walk" class="primary">Walk me through it →</button>
+      </div>
+    </div>
+  </div>
+
+  <!-- One-time first-open spotlight: dims the canvas and points at the "Start here"
+       beacon, then collapses into it. Shown once per workflow; Esc / click-away / either
+       button dismiss it. The beacon gets .spotlit so it sits above the dim. The bubble is
+       positioned next to the beacon at open time (aware.js). -->
+  <div id="guide-spotlight" class="guide-spotlight" hidden>
+    <div class="guide-spotlight-bubble" role="dialog" aria-modal="false" aria-label="New workflow tip" tabindex="-1">
+      <div class="guide-spotlight-text">New to this workflow? <strong>Start here</strong> — see what it does and how to run it.</div>
+      <div class="guide-spotlight-actions">
+        <button type="button" id="guide-spotlight-got" class="ghost">Got it</button>
+        <button type="button" id="guide-spotlight-show" class="primary">Show me</button>
+      </div>
+    </div>
+  </div>
+
   <!-- Routines — scheduled .flo runs. The list; the add/edit form is its own modal. -->
   <div class="modal-backdrop" id="routines-modal">
     <div class="modal routines">

package/dist/web/steel-3d-view.js

@@ -16,6 +16,7 @@
  */
 import * as THREE from 'three';
 import { OrbitControls } from 'three/addons/OrbitControls.js';
+import { Brush, Evaluator, SUBTRACTION } from 'three-bvh-csg';
 import { snapCandidates, snapPoint, planPointToWp, memberGeometry, elevationLevels, dim3dGeom } from './steel-3d-core.js';
 
 let renderer, scene, perspCam, orthoCam, camera, controls, root, api, canvasEl, ro, rafId, grid, raycaster, downXY, lastPick = '(none)';
@@ -126,7 +127,7 @@ function init(canvas, theApi) {
   window.addEventListener('pointermove', onMove); // window so a drag keeps tracking off-canvas
   window.addEventListener('pointerup', onUp);
   canvas.addEventListener('pointermove', onHoverMove); // canvas-only: cursor + hover readout when idle
-  canvas.addEventListener('dblclick', onDblClick);     // Tekla "set view point": dbl-click sets the orbit/zoom pivot
+  canvas.addEventListener('dblclick', onDblClick);     // "zoom to detail": dbl-click a part zooms to it (empty = no-op)
   window.addEventListener('keydown', onKey);           // Tekla keyboard nav: arrows pan, Ctrl/Shift+arrows rotate
   ro = new ResizeObserver(resize); ro.observe(canvas.parentElement || canvas);
   initCube();
@@ -223,10 +224,98 @@ function placeMember(mesh, a, b, el) {
   mesh.position.copy(A).addScaledVector(dir, len / 2);
 }
 
+// ---- connection parts (base-plate slice) — the new scene-element kinds the connection engine
+// (server/steel-joints.ts) emits: a plate with holes, anchor rods, a weld bead. These are DERIVED
+// geometry, not contract members, so buildFromScene marks them non-editable (excluded from picks).
+
+// A flat plate (with punched holes) extruded along its normal, oriented by its in-plane axes.
+function placePlate(mesh, el) {
+  const w = Math.max(el.width || 10, 1), d = Math.max(el.depth || 10, 1), t = Math.max(el.thickness || 5, 0.5);
+  const hw = w / 2, hd = d / 2;
+  const shape = new THREE.Shape();
+  shape.moveTo(-hw, -hd); shape.lineTo(hw, -hd); shape.lineTo(hw, hd); shape.lineTo(-hw, hd); shape.closePath();
+  for (const h of el.holes || []) { // bolts own the holes — punch one per fastener
+    const r = Math.max((h.d || 0) / 2, 0.1);
+    const hole = new THREE.Path(); hole.absarc(h.u || 0, h.v || 0, r, 0, Math.PI * 2, true);
+    shape.holes.push(hole);
+  }
+  const g = new THREE.ExtrudeGeometry(shape, { depth: t, bevelEnabled: false });
+  g.translate(0, 0, -t / 2); // centre the slab on the plate plane
+  mesh.geometry = g;
+  const u = V(...(el.uDir || [1, 0, 0])).normalize();
+  const v = V(...(el.vDir || [0, 1, 0])).normalize();
+  const n = new THREE.Vector3().crossVectors(u, v).normalize(); // extrude axis = plate normal
+  mesh.quaternion.setFromRotationMatrix(new THREE.Matrix4().makeBasis(u, v, n));
+  mesh.position.set(...(el.center || [0, 0, 0]));
+}
+
+// A cylinder between two points (anchor rod / bolt shank).
+function placeBar(mesh, a, b, r, radial) {
+  const A = V(a[0], a[1], a[2]), B = V(b[0], b[1], b[2]);
+  const dir = new THREE.Vector3().subVectors(B, A); const len = dir.length() || 1; dir.normalize();
+  mesh.geometry = new THREE.CylinderGeometry(r, r, len, radial || 16, 1, false); // axis = local +Y
+  mesh.quaternion.setFromUnitVectors(_YA, dir);
+  mesh.position.copy(A).addScaledVector(dir, len / 2);
+}
+
+// A fillet weld traced as a thin bead along its path — STRAIGHT segments (no CatmullRom rounding) so it
+// hugs the actual edge. Path points are already world mm. `closed` (default true) wraps end→start (the
+// base-plate column outline). `closed:false` = an OPEN polyline (the shear plate's straight edge weld) —
+// must NOT wrap: a 2-point wrap doubles back into a cusp that degenerates the tube (an invisible weld).
+function placeWeld(mesh, el) {
+  const pts = (el.path || []).map((p) => V(p[0], p[1], p[2]));
+  if (pts.length < 2) { mesh.geometry = new THREE.BufferGeometry(); return; }
+  const r = Math.max((el.leg || 6) * 0.6, 2); // enough girth to read as a fillet bead, not a wire ring
+  const closed = el.closed !== false; // default = a closed loop (back-compat with the base-plate weld)
+  const cp = new THREE.CurvePath();
+  const last = closed ? pts.length : pts.length - 1; // closed → wrap the final segment; open → stop one short
+  for (let i = 0; i < last; i++) { // skip any zero-length segment (avoids NaN tube frames)
+    const a = pts[i], b = pts[(i + 1) % pts.length];
+    if (a.distanceToSquared(b) > 1e-6) cp.add(new THREE.LineCurve3(a, b));
+  }
+  if (!cp.curves.length) { mesh.geometry = new THREE.BufferGeometry(); return; }
+  mesh.geometry = new THREE.TubeGeometry(cp, Math.max(pts.length * 6, 24), r, 8, false);
+  mesh.position.set(0, 0, 0); // geometry carries world coordinates
+}
+
+// A hex nut: a 6-sided prism swept from→to. acrossFlats (wrench size) → circumradius = AF/√3.
+function placeNut(mesh, el) {
+  placeBar(mesh, el.from, el.to, Math.max((el.acrossFlats || 20) / Math.sqrt(3), 0.5), 6);
+}
+
+// A flat washer: an annulus (outer ⌀ with an inner hole) swept from→to along its axis.
+function placeWasher(mesh, el) {
+  const A = V(el.from[0], el.from[1], el.from[2]), B = V(el.to[0], el.to[1], el.to[2]);
+  const dir = new THREE.Vector3().subVectors(B, A); const len = dir.length() || 1; dir.normalize();
+  const ro = Math.max((el.dOuter || 20) / 2, 0.5), ri = Math.min(Math.max((el.dInner || 10) / 2, 0.1), ro - 0.2);
+  const shape = new THREE.Shape(); shape.absarc(0, 0, ro, 0, Math.PI * 2, false);
+  const hole = new THREE.Path(); hole.absarc(0, 0, ri, 0, Math.PI * 2, true); shape.holes.push(hole);
+  mesh.geometry = new THREE.ExtrudeGeometry(shape, { depth: len, bevelEnabled: false, curveSegments: 24 });
+  mesh.quaternion.setFromUnitVectors(_ZA, dir); // shape-plane normal (local +Z) → washer axis
+  mesh.position.copy(A); // extrudes from `from` toward `to`
+}
+
+// Build a mesh for one scene element by kind: a member box (default) or a connection part. Returns
+// false for an unknown kind so the caller skips it (forward-compatible with later part kinds).
+function placeElement(mesh, el) {
+  switch (el.kind || 'box') {
+    case 'box': placeMember(mesh, el.from, el.to, el); return true;
+    case 'plate': placePlate(mesh, el); return true;
+    case 'rod': placeBar(mesh, el.from, el.to, Math.max((el.d || 20) / 2, 0.5), 16); return true;
+    case 'nut': placeNut(mesh, el); return true;
+    case 'washer': placeWasher(mesh, el); return true;
+    case 'weld': placeWeld(mesh, el); return true;
+    default: return false;
+  }
+}
+
 function materialFor(groupKey) {
   if (!baseMat.has(groupKey)) {
     const col = groupColor.get(groupKey) || new THREE.Color(0x94a3b8);
-    baseMat.set(groupKey, new THREE.MeshStandardMaterial({ color: col, metalness: 0.1, roughness: 0.75 }));
+    // Fasteners (anchor rods / bolts / nuts / washers) read more metallic (zinc-plated); plates/welds/members stay matte.
+    const metallic = groupKey === 'anchor' || groupKey === 'bolt' || groupKey === 'nut' || groupKey === 'washer';
+    const metal = metallic ? 0.5 : 0.1, rough = metallic ? 0.4 : 0.75;
+    baseMat.set(groupKey, new THREE.MeshStandardMaterial({ color: col, metalness: metal, roughness: rough }));
   }
   return baseMat.get(groupKey);
 }
@@ -240,6 +329,34 @@ function clearRoot() {
   meshById.clear();
 }
 
+// Subtract each cope (a `cut` part) from a member's solid via CSG — a real coped beam end. Cut boxes are
+// world-space (center/uDir/vDir/width/depth/thickness); we transform them into the member's LOCAL frame so
+// the result keeps the member's placement (drag/select still work), then subtract. On any CSG failure the
+// member is left uncoped rather than breaking the whole scene.
+const _csgEval = new Evaluator();
+_csgEval.useGroups = false; // one solid out → the member's single material applies
+function applyCopes(mesh, cuts) {
+  try {
+    mesh.updateMatrix(); // local TRS (root is identity → local == world mm)
+    const invMember = mesh.matrix.clone().invert();
+    let result = new Brush(mesh.geometry); result.updateMatrixWorld(true); // member-local, identity
+    for (const cut of cuts) {
+      const pad = 0.6; // over-cut so coplanar faces don't leave slivers
+      const g = new THREE.BoxGeometry(Math.max(cut.width || 1, 1) + pad, Math.max(cut.depth || 1, 1) + pad, Math.max(cut.thickness || 1, 1) + pad);
+      const u = V(...(cut.uDir || [1, 0, 0])).normalize(), vv = V(...(cut.vDir || [0, 1, 0])).normalize();
+      const n = new THREE.Vector3().crossVectors(u, vv).normalize();
+      const world = new THREE.Matrix4().makeBasis(u, vv, n); world.setPosition(cut.center[0], cut.center[1], cut.center[2]);
+      const b = new Brush(g);
+      invMember.clone().multiply(world).decompose(b.position, b.quaternion, b.scale); // cut → member-local
+      b.updateMatrixWorld(true);
+      result = _csgEval.evaluate(result, b, SUBTRACTION);
+      g.dispose();
+    }
+    mesh.geometry.dispose();
+    mesh.geometry = result.geometry; // member-local solid carrying the notch(es); mesh keeps its placement
+  } catch (e) { console.warn('[steel-3d] cope CSG failed; member left uncoped', mesh.userData && mesh.userData.id, e); }
+}
+
 function buildFromScene(sc) {
   clearRoot();
   for (const mat of baseMat.values()) mat.dispose(); // shared per-profile materials from the prior build
@@ -247,10 +364,22 @@ function buildFromScene(sc) {
   sceneGroups = (sc.groups || []).map((g) => ({ key: g.key, label: g.label, color: g.color || '#94a3b8' }));
   for (const g of sceneGroups) groupColor.set(g.key, new THREE.Color(g.color));
   const box = new THREE.Box3();
+  // Copes (`cut` parts) are SUBTRACTIVE — they notch their target member's mesh, they don't render as
+  // standalone parts. Collect them by target member id first, then subtract once the member mesh is built.
+  const cutsByMember = new Map();
+  for (const el of sc.elements || []) {
+    if (el && el.kind === 'cut' && el.member) {
+      if (!cutsByMember.has(el.member)) cutsByMember.set(el.member, []);
+      cutsByMember.get(el.member).push(el);
+    }
+  }
   for (const el of sc.elements || []) {
     const mesh = new THREE.Mesh(undefined, materialFor(el.group));
-    placeMember(mesh, el.from, el.to, el); // real cross-section (I / channel / angle / tube / box) from the profile
+    if (!placeElement(mesh, el)) continue; // unknown kind → skip (a `cut` is one of these: applied below, never a standalone mesh)
+    const memberCuts = cutsByMember.get(el.id);
+    if (memberCuts && memberCuts.length) applyCopes(mesh, memberCuts); // notch a coped member end
     mesh.userData.id = el.id; mesh.userData.group = el.group; mesh.userData.profile = el.meta && el.meta.profile;
+    mesh.userData.derived = !!(el.kind && el.kind !== 'box'); // connection parts: rendered, not member-editable
     root.add(mesh); meshById.set(el.id, mesh);
     box.expandByObject(mesh);
   }
@@ -462,14 +591,25 @@ function reflectDimBar() {
   reflectDimAxisBar();
 }
 function reflectDimAxisBar() { document.querySelectorAll('#m3dDimAxis button').forEach((x) => x.classList.toggle('on', x.dataset.d3axis === dimAxis3d)); }
-// Tekla "set view point": double-click a member → make that point the orbit/zoom pivot.
+// "Zoom to detail": double-click a part → zoom to a tight region around the click point so a connection
+// fills the view (members AND their derived connection parts are valid targets), keeping the current view
+// direction. Empty space → no-op (use the Fit button / Home for fit-all, so a stray double-click can't
+// teleport the camera). Replaces the old set-orbit-pivot — zoom-to sets the pivot anyway, and
+// zoomToCursor already lets the wheel zoom toward the cursor.
 function onDblClick(e) {
   camera.updateMatrixWorld(); root.updateMatrixWorld(true);
   const rect = canvasEl.getBoundingClientRect();
   const ndc = new THREE.Vector2(((e.clientX - rect.left) / rect.width) * 2 - 1, -((e.clientY - rect.top) / rect.height) * 2 + 1);
   raycaster.setFromCamera(ndc, camera);
-  const hits = raycaster.intersectObjects([...meshById.values()].filter((m) => m.visible), false);
-  if (hits.length) { controls.target.copy(hits[0].point); controls.update(); }
+  const hits = raycaster.intersectObjects([...meshById.values()].filter((m) => m.visible), false); // incl. connection parts
+  if (!hits.length) return; // empty space → no-op (Fit / Home fit-all; avoids an accidental camera teleport)
+  const p = hits[0].point, mesh = hits[0].object;
+  if (mesh.geometry && !mesh.geometry.boundingBox) mesh.geometry.computeBoundingBox();
+  const s = mesh.geometry && mesh.geometry.boundingBox ? mesh.geometry.boundingBox.getSize(new THREE.Vector3()) : V(400, 400, 400);
+  const sect = Math.max(40, Math.min(s.x, s.y, s.z)); // the part's smallest extent ≈ a section / plate scale
+  const half = Math.min(Math.max(sect * 3, 300), 2500); // a detail-scale zoom box (clamped sane)
+  const viewDir = camera.position.clone().sub(controls.target).normalize(); // keep the current view orientation
+  fitCamera(new THREE.Box3().setFromCenterAndSize(p, new THREE.Vector3(half * 2, half * 2, half * 2)), viewDir.lengthSq() > 0.5 ? viewDir : undefined);
 }
 
 function setSelection(ids) {
@@ -636,7 +776,7 @@ function pickAt(cx, cy) {
   const rect = canvasEl.getBoundingClientRect();
   const ndc = new THREE.Vector2(((cx - rect.left) / rect.width) * 2 - 1, -((cy - rect.top) / rect.height) * 2 + 1);
   raycaster.setFromCamera(ndc, camera);
-  const hits = raycaster.intersectObjects([...meshById.values()].filter((m) => m.visible), false);
+  const hits = raycaster.intersectObjects([...meshById.values()].filter((m) => m.visible && !m.userData.derived), false);
   lastPick = hits.length ? hits[0].object.userData.id : null;
   return lastPick;
 }
@@ -855,7 +995,7 @@ function membersInRect(x0, y0, x1, y1) {
   const lo = { x: Math.min(x0, x1), y: Math.min(y0, y1) }, hi = { x: Math.max(x0, x1), y: Math.max(y0, y1) };
   const out = [];
   for (const [id, m] of meshById) {
-    if (!m.visible) continue;
+    if (!m.visible || m.userData.derived) continue; // derived connection parts aren't member-selectable (mirrors pickAt; dbl-click-zoom deliberately includes them)
     const w = m.getWorldPosition(new THREE.Vector3()).project(camera); if (w.z > 1) continue;
     const sx = rect.left + (w.x * 0.5 + 0.5) * rect.width, sy = rect.top + (-w.y * 0.5 + 0.5) * rect.height;
     if (sx >= lo.x && sx <= hi.x && sy >= lo.y && sy <= hi.y) out.push(id);
@@ -959,7 +1099,7 @@ function updateStatusChip() {
   const showId = hoverId || (selIds.size === 1 ? [...selIds][0] : null);
   if (showId) { const m = members().find((x) => x.id === showId); txt = m ? `${m.id} · ${m.profile || '—'}` : ''; }
   else if (selIds.size > 1) txt = `${selIds.size} members selected`;
-  else txt = 'Drag a member to move · ends to stretch · Alt+drag elevation · right-drag orbits';
+  else txt = 'Drag to move · ends to stretch · Alt+drag elevation · right-drag orbit · dbl-click to zoom in';
   hoverChip.textContent = txt;
   hoverChip.style.left = (rect.left + rect.width / 2) + 'px'; hoverChip.style.transform = 'translateX(-50%)';
   hoverChip.style.top = (rect.bottom - 30) + 'px';