@sub-zero/cocoa 0.1.1 → 0.2.1

package/README.md

@@ -163,3 +163,17 @@ contains only `dist`, this README, and package metadata. Do not publish the priv
 Angular application root. Review the version and `npm pack --dry-run` output before
 publishing. No open-source license is granted (`UNLICENSED`); the source repository
 may be private.
+
+## Incident handoff
+
+The visible **Get further help** action opens a review form. The visitor chooses a correspondence email and explicitly submits an incident; neither opening chat nor mentioning an email creates one. The current visitor session authorizes creation in the chatbot's project. A confirmed reference survives reload, and failed submissions retain their text and idempotency key for retry. The team's follow-up is by email. The email is not verified account identity.
+
+Requires the SubZero chat-escalation API. Closed conversations can still submit while their visitor credential is valid; paused deployments cannot accept new submissions. No model call is needed for handoff. `reset()` clears the chat, pending form and visitor credential; call it on logout/account changes. SMTP acknowledgement delivery retries are at-least-once; a stable Message-ID assists threading but cannot guarantee exactly-once delivery by an external mail server.
+
+### Greeting and reply feedback
+
+The launcher shows “Hi! Ask me anything.” after five seconds, once per browser tab. Click to chat or dismiss it. Opening chat first suppresses the greeting. A soft chime plays only if a previous user interaction has enabled browser audio; otherwise the greeting appears silently. Nothing starts a conversation until the visitor sends a message or explicitly submits an incident.
+
+Customize with `greetingMessage` (string, or `false` to disable), `greetingDelay` (milliseconds), and `greetingSound` (`false` for silent greetings). Script embeds accept `data-greeting-message`, `data-greeting-delay` and `data-greeting-sound`.
+
+Animated dots indicate a reply is pending while the agent is online. They clear when an answer arrives, a person takes over, the chat is paused/closed, an incident is submitted, or a request fails. Reduced-motion preferences disable animation. The indicator reflects an unanswered message, not provider-level token streaming.

package/dist/cocoa.js

@@ -23,6 +23,8 @@ function createCocoa(options = {}) {
   if (!Number.isInteger(zIndex) || zIndex < 0 || zIndex > 2147483647) throw new Error('Invalid zIndex.');
   const pollInterval = options.pollInterval ?? 2500;
   if (!Number.isFinite(pollInterval) || pollInterval < 2500) throw new Error('pollInterval must be at least 2500ms.');
+  const greetingDelay = options.greetingDelay ?? 5000;
+  if (!Number.isFinite(greetingDelay) || greetingDelay < 0) throw new Error('greetingDelay must be a nonnegative number.');
   const host = document.createElement('div');
   host.dataset.cocoaWidget = '';
   const root = host.attachShadow({ mode: 'open' });
@@ -33,11 +35,15 @@ function createCocoa(options = {}) {
     *,*::before,*::after{box-sizing:border-box} [hidden]{display:none!important}
     button,input,textarea{font:inherit}button{cursor:pointer;border:1px solid #647078;border-radius:12px;padding:10px 14px;background:#26343a;color:#fff}button:hover{filter:brightness(1.15)}button:disabled{opacity:.55;cursor:default}button:focus-visible,input:focus-visible,textarea:focus-visible{outline:3px solid #99dbc4;outline-offset:2px}
     .launcher{display:block;margin-left:auto;width:72px;height:72px;padding:0;border:2px solid #e1f4fa;border-radius:50%;overflow:hidden;background:#92c5d5;box-shadow:0 6px 24px #0005}.launcher img{display:block;width:100%;height:100%;object-fit:cover;transform:scale(1.18);pointer-events:none}.launcher:hover{filter:brightness(1.06)}
+    .greeting{position:absolute;right:0;bottom:84px;display:flex;align-items:center;max-width:calc(100vw - 32px);width:250px;background:#fff5e9;color:#392516;border-radius:18px;box-shadow:0 6px 24px #0003;padding:6px}.greeting::after{content:'';position:absolute;right:28px;bottom:-8px;border:8px solid transparent;border-top-color:#fff5e9;border-bottom:0}.greeting button{color:inherit;background:transparent;border:0}.greeting .greeting-open{text-align:left;flex:1}.greeting .greeting-dismiss{padding:8px;min-width:40px;min-height:40px}
+    .thinking{display:flex;align-items:center;gap:8px;padding:8px 16px;color:#c8d4dd;font-size:12px}.dots{display:flex;gap:4px}.dots i{width:5px;height:5px;border-radius:50%;background:#92c5d5}
+    @media(prefers-reduced-motion:no-preference){.greeting{animation:appear .25s ease-out}.dots i{animation:think 1.2s ease-in-out infinite}.dots i:nth-child(2){animation-delay:.15s}.dots i:nth-child(3){animation-delay:.3s}@keyframes think{0%,60%,100%{opacity:.4;transform:translateY(0)}30%{opacity:1;transform:translateY(-3px)}}}
     .panel{display:flex;flex-direction:column;width:370px;max-width:calc(100vw - 32px);height:520px;max-height:calc(100dvh - 116px);background:#141c22;border:1px solid #44515b;border-radius:18px;box-shadow:0 12px 50px #0005;overflow:hidden;margin-bottom:12px}
     header{display:flex;align-items:center;justify-content:space-between;gap:12px;padding:14px 16px;border-bottom:1px solid #39454e}header strong{font-size:16px;overflow-wrap:anywhere}header small{display:block;color:#bac9d2}header button{min-width:44px;min-height:44px;font-size:22px;background:transparent}
     .messages{flex:1;min-height:50px;overflow:auto;overscroll-behavior:contain;padding:16px;display:flex;flex-direction:column;gap:12px}.message{flex-shrink:0;align-self:flex-start;max-width:92%;background:#27333d;padding:10px 12px;border-radius:12px;white-space:pre-wrap;overflow-wrap:anywhere}.customer{align-self:flex-end;background:${accent}}.message small{display:block;color:#fff;font-weight:600;font-size:11px;margin-bottom:4px}
     .welcome{color:#c8d4dd;margin:0;white-space:pre-wrap;overflow-wrap:anywhere}.status{color:#c8d4dd;font-size:12px;margin:0;padding:8px 16px}.error{color:#ffc3c3}
     form{padding:12px 16px;border-top:1px solid #39454e;display:grid;gap:8px}label{display:grid;gap:4px;font-size:12px}input,textarea{width:100%;border:1px solid #61717e;border-radius:8px;background:#1e2932;color:#fff;padding:8px;font-size:16px}textarea{height:64px;resize:none}.actions{display:flex;justify-content:flex-end;gap:8px}.new{margin-right:auto}
+    .help{margin:0 16px 10px}.handoff{overflow:auto;min-height:0;flex:1}.handoff p{margin:0;color:#c8d4dd;font-size:12px}.handoff textarea{height:90px}.handoff-result{padding:12px 16px;overflow-wrap:anywhere}
     @media(prefers-reduced-motion:no-preference){.panel{animation:appear .15s ease-out}@keyframes appear{from{opacity:0;transform:translateY(6px)}to{opacity:1;transform:translateY(0)}}}
     @media(max-height:540px){.panel{height:calc(100dvh - 116px)}.name{display:none}header{padding:4px 12px}form{padding:6px 12px}textarea{height:42px}}
   `;
@@ -63,6 +69,32 @@ function createCocoa(options = {}) {
   actions.append(element('button', { class: 'new', type: 'button', hidden: '' }, 'New conversation'), element('button', { class: 'send', type: 'submit' }, 'Send'));
   composer.append(nameLabel, messageLabel, actions);
   panel.append(header, element('div', { class: 'messages', role: 'log', 'aria-label': 'Conversation', 'aria-live': 'polite', 'aria-relevant': 'additions text' }), element('p', { class: 'status', role: 'status' }), composer);
+  const help = element('button', { type: 'button', class: 'help' }, 'Get further help');
+  const handoff = element('form', { class: 'handoff', hidden: '' });
+  const fields = {};
+  for (const [key, label, tag, max, type] of [
+    ['email', 'Correspondence email', 'input', 254, 'email'],
+    ['name', 'Your name (optional)', 'input', 120, 'text'],
+    ['summary', 'Summary', 'input', 200, 'text'],
+    ['details', 'What do you still need help with?', 'textarea', 6000, null],
+  ]) {
+    const field = element(tag, { maxlength: String(max), ...(type ? {type} : {}), ...(key !== 'name' ? {required:''} : {}) });
+    const labelNode = element('label', {}, label); labelNode.append(field); handoff.append(labelNode); fields[key] = field;
+  }
+  handoff.append(element('p', {}, 'Review these details before submitting. Your visible conversation will accompany the incident. The support team will follow up at this email. Never include passwords, seed phrases or private keys.'));
+  const handoffError = element('p', {class:'error', role:'alert'});
+  const back = element('button', {type:'button'}, 'Back to chat');
+  const submitIncident = element('button', {type:'submit'}, 'Submit incident');
+  const handoffActions = element('div', {class:'actions'}); handoffActions.append(back, submitIncident);
+  handoff.append(handoffError, handoffActions);
+  const handoffResult = element('p', {class:'handoff-result',role:'status',tabindex:'-1',hidden:''});
+  panel.append(help, handoff, handoffResult);
+  const thinking = element('div', {class:'thinking',role:'status',hidden:''});
+  const dots = element('span', {class:'dots','aria-hidden':'true'});
+  dots.append(element('i'),element('i'),element('i'));
+  const thinkingLabel = element('span', {}, 'Cocoa is thinking…');
+  thinking.append(dots, thinkingLabel);
+  composer.before(thinking);
   panel.querySelector('strong').textContent = options.title || 'Cocoa support';
   const launcher = document.createElement('button');
   launcher.type = 'button';
@@ -77,7 +109,11 @@ function createCocoa(options = {}) {
   launcher.setAttribute('aria-expanded', 'false');
   launcher.setAttribute('aria-controls', panel.id);
   launcher.setAttribute('aria-haspopup', 'dialog');
-  root.append(panel, launcher);
+  const greeting = element('div', {class:'greeting',hidden:''});
+  const greetingOpen = element('button', {type:'button',class:'greeting-open'}, options.greetingMessage || 'Hi! Ask me anything.');
+  const greetingDismiss = element('button', {type:'button',class:'greeting-dismiss','aria-label':'Dismiss greeting'}, '×');
+  greeting.append(greetingOpen,greetingDismiss);
+  root.append(panel, greeting, launcher);
   document.body.append(host);
   const messages = panel.querySelector('.messages');
   const status = panel.querySelector('.status');
@@ -89,12 +125,48 @@ function createCocoa(options = {}) {
   name.value = String(options.visitorLabel || '').slice(0, 120);
   let session = null, pending = null, timer, destroyed = false, sending = false, refreshing = false;
   let generation = 0, terminal = false, paused = false, version = -1, failures = 0;
+  let incident = null, incidentPending = null, submittingIncident = false, expired = false;
+  let greetingTimer, audioContext, greetingSeen = false;
+  const greetingKey = key + ':greeted';
+  try { greetingSeen = sessionStorage.getItem(greetingKey) === '1'; } catch {}
+  const dismissGreeting = (remember = true) => {
+    clearTimeout(greetingTimer); greeting.hidden = true;
+    if (remember) { greetingSeen = true; try { sessionStorage.setItem(greetingKey,'1'); } catch {} }
+    document.removeEventListener('pointerdown', unlockAudio);
+    document.removeEventListener('keydown', unlockAudio);
+    if (audioContext) { void audioContext.close().catch(()=>{}); audioContext = null; }
+  };
+  function unlockAudio() {
+    if (destroyed || greetingSeen || options.greetingSound === false || audioContext) return;
+    try {
+      const Audio = window.AudioContext || window.webkitAudioContext;
+      if (Audio) { audioContext = new Audio(); void audioContext.resume().catch(()=>{}); }
+    } catch { /* Greeting still works when audio is unavailable. */ }
+  }
+  function showGreeting() {
+    if (destroyed || greetingSeen || !panel.hidden || session || options.greetingMessage === false || document.hidden) return;
+    greeting.hidden = false; greetingSeen = true;
+    try { sessionStorage.setItem(greetingKey,'1'); } catch {}
+    document.removeEventListener('pointerdown', unlockAudio);
+    document.removeEventListener('keydown', unlockAudio);
+    // Only play after a prior user gesture unlocked audio. Never queue a surprise sound.
+    if (audioContext?.state === 'running') {
+      try {
+        const tone = audioContext.createOscillator(), volume = audioContext.createGain();
+        const now = audioContext.currentTime;
+        tone.type = 'sine'; tone.frequency.setValueAtTime(660,now); tone.frequency.exponentialRampToValueAtTime(880,now+.1);
+        volume.gain.setValueAtTime(0,now); volume.gain.linearRampToValueAtTime(.045,now+.015); volume.gain.exponentialRampToValueAtTime(.001,now+.2);
+        tone.connect(volume); volume.connect(audioContext.destination); tone.start(now); tone.stop(now+.22);
+        tone.onended = () => { tone.disconnect(); volume.disconnect(); if (audioContext) { void audioContext.close().catch(()=>{}); audioContext=null; } };
+      } catch { if (audioContext) { void audioContext.close().catch(()=>{}); audioContext=null; } }
+    } else if (audioContext) { void audioContext.close().catch(()=>{}); audioContext=null; }
+  }
   const rendered = new Set();
   const requests = new Set();
   const persist = () => {
     if (options.persistSession === false) return;
     try {
-      if (session) sessionStorage.setItem(key, JSON.stringify({ ...session, pending }));
+      if (session) sessionStorage.setItem(key, JSON.stringify({ ...session, pending, incidentPending }));
       else sessionStorage.removeItem(key);
     } catch { /* Storage may be unavailable; an in-memory session still works. */ }
   };
@@ -103,6 +175,11 @@ function createCocoa(options = {}) {
       const stored = JSON.parse(sessionStorage.getItem(key) || 'null');
       if (uuid.test(stored?.id || '') && /^[a-f0-9]{64}$/.test(stored?.token || '')) {
         session = { id: stored.id, token: stored.token };
+        const saved = stored.incidentPending;
+        if (saved && uuid.test(saved.idempotencyKey || '') && ['email','name','summary','details'].every(k=>typeof saved[k]==='string' && saved[k].length<=Number(fields[k].maxLength))) {
+          incidentPending = saved;
+          for (const k of Object.keys(fields)) fields[k].value = saved[k];
+        }
         if (typeof stored.pending?.body === 'string' && stored.pending.body.length <= 12000 && uuid.test(stored.pending.idempotencyKey)) {
           pending = stored.pending;
           input.value = pending.body;
@@ -119,7 +196,12 @@ function createCocoa(options = {}) {
   welcome();
   const controls = () => {
     const focusWasInComposer = root.activeElement === input || root.activeElement === send;
-    input.disabled = sending || terminal || paused;
+    if (incident || !handoff.hidden || terminal || paused) thinking.hidden = true;
+    help.disabled = sending || submittingIncident || expired || paused;
+    help.hidden = !!incident || !handoff.hidden;
+    handoffResult.hidden = !incident;
+    if (incident) handoffResult.textContent = `Incident ${incident.reference} submitted. Follow-up will be by email at ${incident.email}.`;
+    input.disabled = sending || terminal || paused || submittingIncident;
     send.disabled = sending || terminal || paused;
     name.disabled = sending;
     fresh.hidden = !terminal;
@@ -131,6 +213,7 @@ function createCocoa(options = {}) {
   };
   controls();
   const report = (error) => {
+    thinking.hidden = true;
     status.classList.add('error');
     status.textContent = error.message;
     try { options.onError?.(error); } catch { /* Host callback must not break chat. */ }
@@ -165,7 +248,7 @@ function createCocoa(options = {}) {
   }
   function expire(error) {
     if (error.status === 401 || error.status === 404) {
-      terminal = true;
+      terminal = true; expired = true;
       session = null;
       pending = null;
       persist();
@@ -192,12 +275,15 @@ function createCocoa(options = {}) {
       if (atBottom || version < 0) messages.scrollTop = messages.scrollHeight;
       version = data.version;
     }
+    incident = data.escalation || incident;
     terminal = data.state === 'closed';
     paused = !data.enabled;
     status.classList.remove('error');
-    status.textContent = terminal ? 'This conversation is closed.' : paused ? 'This chat is paused.' :
+    status.textContent = incident ? 'Your incident is with the support team. Follow-up will be by email.' : terminal ? 'This conversation is closed.' : paused ? 'This chat is paused.' :
       data.state === 'human' ? 'A person is handling your conversation.' :
       data.agentOnline ? 'Connected to support.' : 'The agent is offline. Your messages are saved for the team.';
+    const last = data.messages.filter(m=>['customer','agent','human'].includes(m.actor)).at(-1);
+    thinking.hidden = !(last?.actor === 'customer' && data.agentOnline && data.state === 'agent' && !terminal && !paused && !incident && handoff.hidden);
     controls();
   }
   function schedule() {
@@ -207,7 +293,7 @@ function createCocoa(options = {}) {
     }
   }
   async function refresh() {
-    if (destroyed || refreshing || sending || panel.hidden || document.hidden || !session || terminal) return;
+    if (destroyed || refreshing || sending || submittingIncident || panel.hidden || document.hidden || !session || terminal) return;
     refreshing = true;
     const current = generation;
     try {
@@ -230,18 +316,25 @@ function createCocoa(options = {}) {
   }
   function open() {
     if (destroyed) return;
+    dismissGreeting();
     panel.hidden = false;
     launcher.setAttribute('aria-expanded', 'true');
-    (terminal ? fresh : input).focus();
+    (!handoff.hidden ? fields.email : terminal ? fresh : input).focus();
     void refresh();
   }
   function reset() {
     if (destroyed) return;
     generation++;
     sending = refreshing = false;
+    thinking.hidden = true;
     for (const request of requests) request.abort();
     clearTimeout(timer);
-    session = pending = null;
+    session = pending = incident = incidentPending = null;
+    expired = submittingIncident = false;
+    handoff.hidden = true; composer.hidden = messages.hidden = false;
+    submitIncident.disabled = back.disabled = false;
+    for(const field of Object.values(fields)) { field.value = ''; field.disabled = false; }
+    handoffError.textContent = '';
     terminal = paused = false;
     version = -1;
     failures = 0;
@@ -256,12 +349,13 @@ function createCocoa(options = {}) {
   }
   const visibility = () => {
     clearTimeout(timer);
-    if (!document.hidden) void refresh();
+    if (!document.hidden) { void refresh(); if (!greetingSeen) { clearTimeout(greetingTimer); greetingTimer=setTimeout(showGreeting,greetingDelay); } }
   };
   document.addEventListener('visibilitychange', visibility);
   const widget = { open, close, reset, toggle: () => panel.hidden ? open() : close(), destroy() {
     if (destroyed) return;
     destroyed = true;
+    dismissGreeting(false);
     generation++;
     clearTimeout(timer);
     for (const request of requests) request.abort();
@@ -270,6 +364,8 @@ function createCocoa(options = {}) {
     instances.delete(key);
   } };
   launcher.onclick = widget.toggle;
+  greetingOpen.onclick = open;
+  greetingDismiss.onclick = () => { dismissGreeting(); launcher.focus(); };
   panel.querySelector('header button').onclick = close;
   fresh.onclick = reset;
   root.addEventListener('keydown', (event) => {
@@ -278,8 +374,9 @@ function createCocoa(options = {}) {
   form.onsubmit = async (event) => {
     event.preventDefault();
     const body = input.value.trim();
-    if (!body || sending || terminal || paused || destroyed) return;
+    if (!body || sending || submittingIncident || terminal || paused || destroyed) return;
     sending = true;
+    thinking.hidden = true;
     controls();
     clearTimeout(timer);
     const current = generation;
@@ -314,6 +411,60 @@ function createCocoa(options = {}) {
       }
     }
   };
+  function showChat() {
+    handoff.hidden = true; composer.hidden = messages.hidden = false; controls();
+    if (!panel.hidden) (input.disabled ? help : input).focus();
+  }
+  help.onclick = () => {
+    if (expired || paused || incident || sending || submittingIncident) return;
+    const last = [...messages.querySelectorAll('.customer span')].at(-1)?.textContent || input.value.trim();
+    if (!fields.summary.value) fields.summary.value = (last || 'Help with ' + (options.title || 'this application')).slice(0,200);
+    if (!fields.details.value) fields.details.value = last || '';
+    if (!fields.name.value) fields.name.value = name.value;
+    thinking.hidden = true;
+    handoff.hidden = false; composer.hidden = messages.hidden = true; controls(); fields.email.focus();
+  };
+  back.onclick = showChat;
+  handoff.onsubmit = async event => {
+    event.preventDefault();
+    if (submittingIncident || sending || expired || paused || incident || destroyed) return;
+    const data = Object.fromEntries(Object.entries(fields).map(([k,v])=>[k,v.value.trim()]));
+    if (!data.summary || !data.details || !data.email) return;
+    submittingIncident = true; submitIncident.disabled = back.disabled = true;
+    for(const field of Object.values(fields)) field.disabled = true;
+    handoffError.textContent = ''; controls();
+    const current = generation;
+    try {
+      if (!session) {
+        const result = await call(`/chat/${options.chatbotId}/sessions`, { label: data.name || 'Visitor' });
+        if (destroyed || current !== generation) return;
+        if (!uuid.test(result.id || '') || !/^[a-f0-9]{64}$/.test(result.token || '')) throw new Error('Chat returned an invalid session. Please try again.');
+        session = {id:result.id,token:result.token};
+      }
+      if (!incidentPending || Object.keys(data).some(k=>data[k]!==incidentPending[k])) incidentPending = {...data,idempotencyKey:crypto.randomUUID()};
+      persist();
+      const result = await call(`/chat/sessions/${session.id}/escalations`, incidentPending, session.token);
+      if (destroyed || current !== generation) return;
+      if (!result?.reference || !result?.email) throw new Error('Submission could not be confirmed. Please retry.');
+      incident = result; incidentPending = null; persist(); showChat(); handoffResult.focus();
+    } catch(error) {
+      if (!destroyed && current === generation) {
+        expire(error);
+        handoffError.textContent = expired ? 'This session expired. Return to chat and explicitly start a new conversation before submitting.' : 'Submission could not be confirmed. Your details are kept here; retry to check or submit the same incident.';
+      }
+    } finally {
+      if (!destroyed && current === generation) {
+        submittingIncident = false; submitIncident.disabled = back.disabled = false;
+        for(const field of Object.values(fields)) field.disabled = false;
+        controls(); schedule();
+      }
+    }
+  };
+  if (!greetingSeen && !session && options.greetingMessage !== false) {
+    document.addEventListener('pointerdown', unlockAudio);
+    document.addEventListener('keydown', unlockAudio);
+    greetingTimer=setTimeout(showGreeting,greetingDelay);
+  }
   instances.set(key, widget);
   return widget;
 }
@@ -328,6 +479,9 @@ if (script?.dataset.chatbot) {
     launcherLabel: script.dataset.launcherLabel,
     accentColor: script.dataset.accentColor,
     nonce: script.nonce,
+    greetingMessage: script.dataset.greetingMessage === 'false' ? false : script.dataset.greetingMessage,
+    greetingDelay: script.dataset.greetingDelay === undefined ? undefined : Number(script.dataset.greetingDelay),
+    greetingSound: script.dataset.greetingSound !== 'false',
   };
   const mount = () => { window.Cocoa.widget = createCocoa(options); };
   if (document.body) mount();

package/dist/index.cjs

@@ -21,6 +21,8 @@ function createCocoa(options = {}) {
   if (!Number.isInteger(zIndex) || zIndex < 0 || zIndex > 2147483647) throw new Error('Invalid zIndex.');
   const pollInterval = options.pollInterval ?? 2500;
   if (!Number.isFinite(pollInterval) || pollInterval < 2500) throw new Error('pollInterval must be at least 2500ms.');
+  const greetingDelay = options.greetingDelay ?? 5000;
+  if (!Number.isFinite(greetingDelay) || greetingDelay < 0) throw new Error('greetingDelay must be a nonnegative number.');
   const host = document.createElement('div');
   host.dataset.cocoaWidget = '';
   const root = host.attachShadow({ mode: 'open' });
@@ -31,11 +33,15 @@ function createCocoa(options = {}) {
     *,*::before,*::after{box-sizing:border-box} [hidden]{display:none!important}
     button,input,textarea{font:inherit}button{cursor:pointer;border:1px solid #647078;border-radius:12px;padding:10px 14px;background:#26343a;color:#fff}button:hover{filter:brightness(1.15)}button:disabled{opacity:.55;cursor:default}button:focus-visible,input:focus-visible,textarea:focus-visible{outline:3px solid #99dbc4;outline-offset:2px}
     .launcher{display:block;margin-left:auto;width:72px;height:72px;padding:0;border:2px solid #e1f4fa;border-radius:50%;overflow:hidden;background:#92c5d5;box-shadow:0 6px 24px #0005}.launcher img{display:block;width:100%;height:100%;object-fit:cover;transform:scale(1.18);pointer-events:none}.launcher:hover{filter:brightness(1.06)}
+    .greeting{position:absolute;right:0;bottom:84px;display:flex;align-items:center;max-width:calc(100vw - 32px);width:250px;background:#fff5e9;color:#392516;border-radius:18px;box-shadow:0 6px 24px #0003;padding:6px}.greeting::after{content:'';position:absolute;right:28px;bottom:-8px;border:8px solid transparent;border-top-color:#fff5e9;border-bottom:0}.greeting button{color:inherit;background:transparent;border:0}.greeting .greeting-open{text-align:left;flex:1}.greeting .greeting-dismiss{padding:8px;min-width:40px;min-height:40px}
+    .thinking{display:flex;align-items:center;gap:8px;padding:8px 16px;color:#c8d4dd;font-size:12px}.dots{display:flex;gap:4px}.dots i{width:5px;height:5px;border-radius:50%;background:#92c5d5}
+    @media(prefers-reduced-motion:no-preference){.greeting{animation:appear .25s ease-out}.dots i{animation:think 1.2s ease-in-out infinite}.dots i:nth-child(2){animation-delay:.15s}.dots i:nth-child(3){animation-delay:.3s}@keyframes think{0%,60%,100%{opacity:.4;transform:translateY(0)}30%{opacity:1;transform:translateY(-3px)}}}
     .panel{display:flex;flex-direction:column;width:370px;max-width:calc(100vw - 32px);height:520px;max-height:calc(100dvh - 116px);background:#141c22;border:1px solid #44515b;border-radius:18px;box-shadow:0 12px 50px #0005;overflow:hidden;margin-bottom:12px}
     header{display:flex;align-items:center;justify-content:space-between;gap:12px;padding:14px 16px;border-bottom:1px solid #39454e}header strong{font-size:16px;overflow-wrap:anywhere}header small{display:block;color:#bac9d2}header button{min-width:44px;min-height:44px;font-size:22px;background:transparent}
     .messages{flex:1;min-height:50px;overflow:auto;overscroll-behavior:contain;padding:16px;display:flex;flex-direction:column;gap:12px}.message{flex-shrink:0;align-self:flex-start;max-width:92%;background:#27333d;padding:10px 12px;border-radius:12px;white-space:pre-wrap;overflow-wrap:anywhere}.customer{align-self:flex-end;background:${accent}}.message small{display:block;color:#fff;font-weight:600;font-size:11px;margin-bottom:4px}
     .welcome{color:#c8d4dd;margin:0;white-space:pre-wrap;overflow-wrap:anywhere}.status{color:#c8d4dd;font-size:12px;margin:0;padding:8px 16px}.error{color:#ffc3c3}
     form{padding:12px 16px;border-top:1px solid #39454e;display:grid;gap:8px}label{display:grid;gap:4px;font-size:12px}input,textarea{width:100%;border:1px solid #61717e;border-radius:8px;background:#1e2932;color:#fff;padding:8px;font-size:16px}textarea{height:64px;resize:none}.actions{display:flex;justify-content:flex-end;gap:8px}.new{margin-right:auto}
+    .help{margin:0 16px 10px}.handoff{overflow:auto;min-height:0;flex:1}.handoff p{margin:0;color:#c8d4dd;font-size:12px}.handoff textarea{height:90px}.handoff-result{padding:12px 16px;overflow-wrap:anywhere}
     @media(prefers-reduced-motion:no-preference){.panel{animation:appear .15s ease-out}@keyframes appear{from{opacity:0;transform:translateY(6px)}to{opacity:1;transform:translateY(0)}}}
     @media(max-height:540px){.panel{height:calc(100dvh - 116px)}.name{display:none}header{padding:4px 12px}form{padding:6px 12px}textarea{height:42px}}
   `;
@@ -61,6 +67,32 @@ function createCocoa(options = {}) {
   actions.append(element('button', { class: 'new', type: 'button', hidden: '' }, 'New conversation'), element('button', { class: 'send', type: 'submit' }, 'Send'));
   composer.append(nameLabel, messageLabel, actions);
   panel.append(header, element('div', { class: 'messages', role: 'log', 'aria-label': 'Conversation', 'aria-live': 'polite', 'aria-relevant': 'additions text' }), element('p', { class: 'status', role: 'status' }), composer);
+  const help = element('button', { type: 'button', class: 'help' }, 'Get further help');
+  const handoff = element('form', { class: 'handoff', hidden: '' });
+  const fields = {};
+  for (const [key, label, tag, max, type] of [
+    ['email', 'Correspondence email', 'input', 254, 'email'],
+    ['name', 'Your name (optional)', 'input', 120, 'text'],
+    ['summary', 'Summary', 'input', 200, 'text'],
+    ['details', 'What do you still need help with?', 'textarea', 6000, null],
+  ]) {
+    const field = element(tag, { maxlength: String(max), ...(type ? {type} : {}), ...(key !== 'name' ? {required:''} : {}) });
+    const labelNode = element('label', {}, label); labelNode.append(field); handoff.append(labelNode); fields[key] = field;
+  }
+  handoff.append(element('p', {}, 'Review these details before submitting. Your visible conversation will accompany the incident. The support team will follow up at this email. Never include passwords, seed phrases or private keys.'));
+  const handoffError = element('p', {class:'error', role:'alert'});
+  const back = element('button', {type:'button'}, 'Back to chat');
+  const submitIncident = element('button', {type:'submit'}, 'Submit incident');
+  const handoffActions = element('div', {class:'actions'}); handoffActions.append(back, submitIncident);
+  handoff.append(handoffError, handoffActions);
+  const handoffResult = element('p', {class:'handoff-result',role:'status',tabindex:'-1',hidden:''});
+  panel.append(help, handoff, handoffResult);
+  const thinking = element('div', {class:'thinking',role:'status',hidden:''});
+  const dots = element('span', {class:'dots','aria-hidden':'true'});
+  dots.append(element('i'),element('i'),element('i'));
+  const thinkingLabel = element('span', {}, 'Cocoa is thinking…');
+  thinking.append(dots, thinkingLabel);
+  composer.before(thinking);
   panel.querySelector('strong').textContent = options.title || 'Cocoa support';
   const launcher = document.createElement('button');
   launcher.type = 'button';
@@ -75,7 +107,11 @@ function createCocoa(options = {}) {
   launcher.setAttribute('aria-expanded', 'false');
   launcher.setAttribute('aria-controls', panel.id);
   launcher.setAttribute('aria-haspopup', 'dialog');
-  root.append(panel, launcher);
+  const greeting = element('div', {class:'greeting',hidden:''});
+  const greetingOpen = element('button', {type:'button',class:'greeting-open'}, options.greetingMessage || 'Hi! Ask me anything.');
+  const greetingDismiss = element('button', {type:'button',class:'greeting-dismiss','aria-label':'Dismiss greeting'}, '×');
+  greeting.append(greetingOpen,greetingDismiss);
+  root.append(panel, greeting, launcher);
   document.body.append(host);
   const messages = panel.querySelector('.messages');
   const status = panel.querySelector('.status');
@@ -87,12 +123,48 @@ function createCocoa(options = {}) {
   name.value = String(options.visitorLabel || '').slice(0, 120);
   let session = null, pending = null, timer, destroyed = false, sending = false, refreshing = false;
   let generation = 0, terminal = false, paused = false, version = -1, failures = 0;
+  let incident = null, incidentPending = null, submittingIncident = false, expired = false;
+  let greetingTimer, audioContext, greetingSeen = false;
+  const greetingKey = key + ':greeted';
+  try { greetingSeen = sessionStorage.getItem(greetingKey) === '1'; } catch {}
+  const dismissGreeting = (remember = true) => {
+    clearTimeout(greetingTimer); greeting.hidden = true;
+    if (remember) { greetingSeen = true; try { sessionStorage.setItem(greetingKey,'1'); } catch {} }
+    document.removeEventListener('pointerdown', unlockAudio);
+    document.removeEventListener('keydown', unlockAudio);
+    if (audioContext) { void audioContext.close().catch(()=>{}); audioContext = null; }
+  };
+  function unlockAudio() {
+    if (destroyed || greetingSeen || options.greetingSound === false || audioContext) return;
+    try {
+      const Audio = window.AudioContext || window.webkitAudioContext;
+      if (Audio) { audioContext = new Audio(); void audioContext.resume().catch(()=>{}); }
+    } catch { /* Greeting still works when audio is unavailable. */ }
+  }
+  function showGreeting() {
+    if (destroyed || greetingSeen || !panel.hidden || session || options.greetingMessage === false || document.hidden) return;
+    greeting.hidden = false; greetingSeen = true;
+    try { sessionStorage.setItem(greetingKey,'1'); } catch {}
+    document.removeEventListener('pointerdown', unlockAudio);
+    document.removeEventListener('keydown', unlockAudio);
+    // Only play after a prior user gesture unlocked audio. Never queue a surprise sound.
+    if (audioContext?.state === 'running') {
+      try {
+        const tone = audioContext.createOscillator(), volume = audioContext.createGain();
+        const now = audioContext.currentTime;
+        tone.type = 'sine'; tone.frequency.setValueAtTime(660,now); tone.frequency.exponentialRampToValueAtTime(880,now+.1);
+        volume.gain.setValueAtTime(0,now); volume.gain.linearRampToValueAtTime(.045,now+.015); volume.gain.exponentialRampToValueAtTime(.001,now+.2);
+        tone.connect(volume); volume.connect(audioContext.destination); tone.start(now); tone.stop(now+.22);
+        tone.onended = () => { tone.disconnect(); volume.disconnect(); if (audioContext) { void audioContext.close().catch(()=>{}); audioContext=null; } };
+      } catch { if (audioContext) { void audioContext.close().catch(()=>{}); audioContext=null; } }
+    } else if (audioContext) { void audioContext.close().catch(()=>{}); audioContext=null; }
+  }
   const rendered = new Set();
   const requests = new Set();
   const persist = () => {
     if (options.persistSession === false) return;
     try {
-      if (session) sessionStorage.setItem(key, JSON.stringify({ ...session, pending }));
+      if (session) sessionStorage.setItem(key, JSON.stringify({ ...session, pending, incidentPending }));
       else sessionStorage.removeItem(key);
     } catch { /* Storage may be unavailable; an in-memory session still works. */ }
   };
@@ -101,6 +173,11 @@ function createCocoa(options = {}) {
       const stored = JSON.parse(sessionStorage.getItem(key) || 'null');
       if (uuid.test(stored?.id || '') && /^[a-f0-9]{64}$/.test(stored?.token || '')) {
         session = { id: stored.id, token: stored.token };
+        const saved = stored.incidentPending;
+        if (saved && uuid.test(saved.idempotencyKey || '') && ['email','name','summary','details'].every(k=>typeof saved[k]==='string' && saved[k].length<=Number(fields[k].maxLength))) {
+          incidentPending = saved;
+          for (const k of Object.keys(fields)) fields[k].value = saved[k];
+        }
         if (typeof stored.pending?.body === 'string' && stored.pending.body.length <= 12000 && uuid.test(stored.pending.idempotencyKey)) {
           pending = stored.pending;
           input.value = pending.body;
@@ -117,7 +194,12 @@ function createCocoa(options = {}) {
   welcome();
   const controls = () => {
     const focusWasInComposer = root.activeElement === input || root.activeElement === send;
-    input.disabled = sending || terminal || paused;
+    if (incident || !handoff.hidden || terminal || paused) thinking.hidden = true;
+    help.disabled = sending || submittingIncident || expired || paused;
+    help.hidden = !!incident || !handoff.hidden;
+    handoffResult.hidden = !incident;
+    if (incident) handoffResult.textContent = `Incident ${incident.reference} submitted. Follow-up will be by email at ${incident.email}.`;
+    input.disabled = sending || terminal || paused || submittingIncident;
     send.disabled = sending || terminal || paused;
     name.disabled = sending;
     fresh.hidden = !terminal;
@@ -129,6 +211,7 @@ function createCocoa(options = {}) {
   };
   controls();
   const report = (error) => {
+    thinking.hidden = true;
     status.classList.add('error');
     status.textContent = error.message;
     try { options.onError?.(error); } catch { /* Host callback must not break chat. */ }
@@ -163,7 +246,7 @@ function createCocoa(options = {}) {
   }
   function expire(error) {
     if (error.status === 401 || error.status === 404) {
-      terminal = true;
+      terminal = true; expired = true;
       session = null;
       pending = null;
       persist();
@@ -190,12 +273,15 @@ function createCocoa(options = {}) {
       if (atBottom || version < 0) messages.scrollTop = messages.scrollHeight;
       version = data.version;
     }
+    incident = data.escalation || incident;
     terminal = data.state === 'closed';
     paused = !data.enabled;
     status.classList.remove('error');
-    status.textContent = terminal ? 'This conversation is closed.' : paused ? 'This chat is paused.' :
+    status.textContent = incident ? 'Your incident is with the support team. Follow-up will be by email.' : terminal ? 'This conversation is closed.' : paused ? 'This chat is paused.' :
       data.state === 'human' ? 'A person is handling your conversation.' :
       data.agentOnline ? 'Connected to support.' : 'The agent is offline. Your messages are saved for the team.';
+    const last = data.messages.filter(m=>['customer','agent','human'].includes(m.actor)).at(-1);
+    thinking.hidden = !(last?.actor === 'customer' && data.agentOnline && data.state === 'agent' && !terminal && !paused && !incident && handoff.hidden);
     controls();
   }
   function schedule() {
@@ -205,7 +291,7 @@ function createCocoa(options = {}) {
     }
   }
   async function refresh() {
-    if (destroyed || refreshing || sending || panel.hidden || document.hidden || !session || terminal) return;
+    if (destroyed || refreshing || sending || submittingIncident || panel.hidden || document.hidden || !session || terminal) return;
     refreshing = true;
     const current = generation;
     try {
@@ -228,18 +314,25 @@ function createCocoa(options = {}) {
   }
   function open() {
     if (destroyed) return;
+    dismissGreeting();
     panel.hidden = false;
     launcher.setAttribute('aria-expanded', 'true');
-    (terminal ? fresh : input).focus();
+    (!handoff.hidden ? fields.email : terminal ? fresh : input).focus();
     void refresh();
   }
   function reset() {
     if (destroyed) return;
     generation++;
     sending = refreshing = false;
+    thinking.hidden = true;
     for (const request of requests) request.abort();
     clearTimeout(timer);
-    session = pending = null;
+    session = pending = incident = incidentPending = null;
+    expired = submittingIncident = false;
+    handoff.hidden = true; composer.hidden = messages.hidden = false;
+    submitIncident.disabled = back.disabled = false;
+    for(const field of Object.values(fields)) { field.value = ''; field.disabled = false; }
+    handoffError.textContent = '';
     terminal = paused = false;
     version = -1;
     failures = 0;
@@ -254,12 +347,13 @@ function createCocoa(options = {}) {
   }
   const visibility = () => {
     clearTimeout(timer);
-    if (!document.hidden) void refresh();
+    if (!document.hidden) { void refresh(); if (!greetingSeen) { clearTimeout(greetingTimer); greetingTimer=setTimeout(showGreeting,greetingDelay); } }
   };
   document.addEventListener('visibilitychange', visibility);
   const widget = { open, close, reset, toggle: () => panel.hidden ? open() : close(), destroy() {
     if (destroyed) return;
     destroyed = true;
+    dismissGreeting(false);
     generation++;
     clearTimeout(timer);
     for (const request of requests) request.abort();
@@ -268,6 +362,8 @@ function createCocoa(options = {}) {
     instances.delete(key);
   } };
   launcher.onclick = widget.toggle;
+  greetingOpen.onclick = open;
+  greetingDismiss.onclick = () => { dismissGreeting(); launcher.focus(); };
   panel.querySelector('header button').onclick = close;
   fresh.onclick = reset;
   root.addEventListener('keydown', (event) => {
@@ -276,8 +372,9 @@ function createCocoa(options = {}) {
   form.onsubmit = async (event) => {
     event.preventDefault();
     const body = input.value.trim();
-    if (!body || sending || terminal || paused || destroyed) return;
+    if (!body || sending || submittingIncident || terminal || paused || destroyed) return;
     sending = true;
+    thinking.hidden = true;
     controls();
     clearTimeout(timer);
     const current = generation;
@@ -312,6 +409,60 @@ function createCocoa(options = {}) {
       }
     }
   };
+  function showChat() {
+    handoff.hidden = true; composer.hidden = messages.hidden = false; controls();
+    if (!panel.hidden) (input.disabled ? help : input).focus();
+  }
+  help.onclick = () => {
+    if (expired || paused || incident || sending || submittingIncident) return;
+    const last = [...messages.querySelectorAll('.customer span')].at(-1)?.textContent || input.value.trim();
+    if (!fields.summary.value) fields.summary.value = (last || 'Help with ' + (options.title || 'this application')).slice(0,200);
+    if (!fields.details.value) fields.details.value = last || '';
+    if (!fields.name.value) fields.name.value = name.value;
+    thinking.hidden = true;
+    handoff.hidden = false; composer.hidden = messages.hidden = true; controls(); fields.email.focus();
+  };
+  back.onclick = showChat;
+  handoff.onsubmit = async event => {
+    event.preventDefault();
+    if (submittingIncident || sending || expired || paused || incident || destroyed) return;
+    const data = Object.fromEntries(Object.entries(fields).map(([k,v])=>[k,v.value.trim()]));
+    if (!data.summary || !data.details || !data.email) return;
+    submittingIncident = true; submitIncident.disabled = back.disabled = true;
+    for(const field of Object.values(fields)) field.disabled = true;
+    handoffError.textContent = ''; controls();
+    const current = generation;
+    try {
+      if (!session) {
+        const result = await call(`/chat/${options.chatbotId}/sessions`, { label: data.name || 'Visitor' });
+        if (destroyed || current !== generation) return;
+        if (!uuid.test(result.id || '') || !/^[a-f0-9]{64}$/.test(result.token || '')) throw new Error('Chat returned an invalid session. Please try again.');
+        session = {id:result.id,token:result.token};
+      }
+      if (!incidentPending || Object.keys(data).some(k=>data[k]!==incidentPending[k])) incidentPending = {...data,idempotencyKey:crypto.randomUUID()};
+      persist();
+      const result = await call(`/chat/sessions/${session.id}/escalations`, incidentPending, session.token);
+      if (destroyed || current !== generation) return;
+      if (!result?.reference || !result?.email) throw new Error('Submission could not be confirmed. Please retry.');
+      incident = result; incidentPending = null; persist(); showChat(); handoffResult.focus();
+    } catch(error) {
+      if (!destroyed && current === generation) {
+        expire(error);
+        handoffError.textContent = expired ? 'This session expired. Return to chat and explicitly start a new conversation before submitting.' : 'Submission could not be confirmed. Your details are kept here; retry to check or submit the same incident.';
+      }
+    } finally {
+      if (!destroyed && current === generation) {
+        submittingIncident = false; submitIncident.disabled = back.disabled = false;
+        for(const field of Object.values(fields)) field.disabled = false;
+        controls(); schedule();
+      }
+    }
+  };
+  if (!greetingSeen && !session && options.greetingMessage !== false) {
+    document.addEventListener('pointerdown', unlockAudio);
+    document.addEventListener('keydown', unlockAudio);
+    greetingTimer=setTimeout(showGreeting,greetingDelay);
+  }
   instances.set(key, widget);
   return widget;
 }

package/dist/index.d.cts

@@ -7,6 +7,12 @@ export interface CocoaOptions {
   /** Accessible name and hover tooltip for the circular Cocoa portrait button. */
   launcherLabel?: string;
   welcomeMessage?: string;
+  /** Once-per-tab launcher greeting; false disables it. Default: Hi! Ask me anything. */
+  greetingMessage?: string | false;
+  /** Delay before greeting, in milliseconds. Defaults to 5000. */
+  greetingDelay?: number;
+  /** Soft chime if prior interaction permits audio. Defaults to true. */
+  greetingSound?: boolean;
   /** Unverified display name, never an authentication credential. */
   visitorLabel?: string;
   /** Six-digit hex color, e.g. #385b50. */

package/dist/index.d.ts

@@ -7,6 +7,12 @@ export interface CocoaOptions {
   /** Accessible name and hover tooltip for the circular Cocoa portrait button. */
   launcherLabel?: string;
   welcomeMessage?: string;
+  /** Once-per-tab launcher greeting; false disables it. Default: Hi! Ask me anything. */
+  greetingMessage?: string | false;
+  /** Delay before greeting, in milliseconds. Defaults to 5000. */
+  greetingDelay?: number;
+  /** Soft chime if prior interaction permits audio. Defaults to true. */
+  greetingSound?: boolean;
   /** Unverified display name, never an authentication credential. */
   visitorLabel?: string;
   /** Six-digit hex color, e.g. #385b50. */

package/dist/index.js

@@ -21,6 +21,8 @@ export function createCocoa(options = {}) {
   if (!Number.isInteger(zIndex) || zIndex < 0 || zIndex > 2147483647) throw new Error('Invalid zIndex.');
   const pollInterval = options.pollInterval ?? 2500;
   if (!Number.isFinite(pollInterval) || pollInterval < 2500) throw new Error('pollInterval must be at least 2500ms.');
+  const greetingDelay = options.greetingDelay ?? 5000;
+  if (!Number.isFinite(greetingDelay) || greetingDelay < 0) throw new Error('greetingDelay must be a nonnegative number.');
   const host = document.createElement('div');
   host.dataset.cocoaWidget = '';
   const root = host.attachShadow({ mode: 'open' });
@@ -31,11 +33,15 @@ export function createCocoa(options = {}) {
     *,*::before,*::after{box-sizing:border-box} [hidden]{display:none!important}
     button,input,textarea{font:inherit}button{cursor:pointer;border:1px solid #647078;border-radius:12px;padding:10px 14px;background:#26343a;color:#fff}button:hover{filter:brightness(1.15)}button:disabled{opacity:.55;cursor:default}button:focus-visible,input:focus-visible,textarea:focus-visible{outline:3px solid #99dbc4;outline-offset:2px}
     .launcher{display:block;margin-left:auto;width:72px;height:72px;padding:0;border:2px solid #e1f4fa;border-radius:50%;overflow:hidden;background:#92c5d5;box-shadow:0 6px 24px #0005}.launcher img{display:block;width:100%;height:100%;object-fit:cover;transform:scale(1.18);pointer-events:none}.launcher:hover{filter:brightness(1.06)}
+    .greeting{position:absolute;right:0;bottom:84px;display:flex;align-items:center;max-width:calc(100vw - 32px);width:250px;background:#fff5e9;color:#392516;border-radius:18px;box-shadow:0 6px 24px #0003;padding:6px}.greeting::after{content:'';position:absolute;right:28px;bottom:-8px;border:8px solid transparent;border-top-color:#fff5e9;border-bottom:0}.greeting button{color:inherit;background:transparent;border:0}.greeting .greeting-open{text-align:left;flex:1}.greeting .greeting-dismiss{padding:8px;min-width:40px;min-height:40px}
+    .thinking{display:flex;align-items:center;gap:8px;padding:8px 16px;color:#c8d4dd;font-size:12px}.dots{display:flex;gap:4px}.dots i{width:5px;height:5px;border-radius:50%;background:#92c5d5}
+    @media(prefers-reduced-motion:no-preference){.greeting{animation:appear .25s ease-out}.dots i{animation:think 1.2s ease-in-out infinite}.dots i:nth-child(2){animation-delay:.15s}.dots i:nth-child(3){animation-delay:.3s}@keyframes think{0%,60%,100%{opacity:.4;transform:translateY(0)}30%{opacity:1;transform:translateY(-3px)}}}
     .panel{display:flex;flex-direction:column;width:370px;max-width:calc(100vw - 32px);height:520px;max-height:calc(100dvh - 116px);background:#141c22;border:1px solid #44515b;border-radius:18px;box-shadow:0 12px 50px #0005;overflow:hidden;margin-bottom:12px}
     header{display:flex;align-items:center;justify-content:space-between;gap:12px;padding:14px 16px;border-bottom:1px solid #39454e}header strong{font-size:16px;overflow-wrap:anywhere}header small{display:block;color:#bac9d2}header button{min-width:44px;min-height:44px;font-size:22px;background:transparent}
     .messages{flex:1;min-height:50px;overflow:auto;overscroll-behavior:contain;padding:16px;display:flex;flex-direction:column;gap:12px}.message{flex-shrink:0;align-self:flex-start;max-width:92%;background:#27333d;padding:10px 12px;border-radius:12px;white-space:pre-wrap;overflow-wrap:anywhere}.customer{align-self:flex-end;background:${accent}}.message small{display:block;color:#fff;font-weight:600;font-size:11px;margin-bottom:4px}
     .welcome{color:#c8d4dd;margin:0;white-space:pre-wrap;overflow-wrap:anywhere}.status{color:#c8d4dd;font-size:12px;margin:0;padding:8px 16px}.error{color:#ffc3c3}
     form{padding:12px 16px;border-top:1px solid #39454e;display:grid;gap:8px}label{display:grid;gap:4px;font-size:12px}input,textarea{width:100%;border:1px solid #61717e;border-radius:8px;background:#1e2932;color:#fff;padding:8px;font-size:16px}textarea{height:64px;resize:none}.actions{display:flex;justify-content:flex-end;gap:8px}.new{margin-right:auto}
+    .help{margin:0 16px 10px}.handoff{overflow:auto;min-height:0;flex:1}.handoff p{margin:0;color:#c8d4dd;font-size:12px}.handoff textarea{height:90px}.handoff-result{padding:12px 16px;overflow-wrap:anywhere}
     @media(prefers-reduced-motion:no-preference){.panel{animation:appear .15s ease-out}@keyframes appear{from{opacity:0;transform:translateY(6px)}to{opacity:1;transform:translateY(0)}}}
     @media(max-height:540px){.panel{height:calc(100dvh - 116px)}.name{display:none}header{padding:4px 12px}form{padding:6px 12px}textarea{height:42px}}
   `;
@@ -61,6 +67,32 @@ export function createCocoa(options = {}) {
   actions.append(element('button', { class: 'new', type: 'button', hidden: '' }, 'New conversation'), element('button', { class: 'send', type: 'submit' }, 'Send'));
   composer.append(nameLabel, messageLabel, actions);
   panel.append(header, element('div', { class: 'messages', role: 'log', 'aria-label': 'Conversation', 'aria-live': 'polite', 'aria-relevant': 'additions text' }), element('p', { class: 'status', role: 'status' }), composer);
+  const help = element('button', { type: 'button', class: 'help' }, 'Get further help');
+  const handoff = element('form', { class: 'handoff', hidden: '' });
+  const fields = {};
+  for (const [key, label, tag, max, type] of [
+    ['email', 'Correspondence email', 'input', 254, 'email'],
+    ['name', 'Your name (optional)', 'input', 120, 'text'],
+    ['summary', 'Summary', 'input', 200, 'text'],
+    ['details', 'What do you still need help with?', 'textarea', 6000, null],
+  ]) {
+    const field = element(tag, { maxlength: String(max), ...(type ? {type} : {}), ...(key !== 'name' ? {required:''} : {}) });
+    const labelNode = element('label', {}, label); labelNode.append(field); handoff.append(labelNode); fields[key] = field;
+  }
+  handoff.append(element('p', {}, 'Review these details before submitting. Your visible conversation will accompany the incident. The support team will follow up at this email. Never include passwords, seed phrases or private keys.'));
+  const handoffError = element('p', {class:'error', role:'alert'});
+  const back = element('button', {type:'button'}, 'Back to chat');
+  const submitIncident = element('button', {type:'submit'}, 'Submit incident');
+  const handoffActions = element('div', {class:'actions'}); handoffActions.append(back, submitIncident);
+  handoff.append(handoffError, handoffActions);
+  const handoffResult = element('p', {class:'handoff-result',role:'status',tabindex:'-1',hidden:''});
+  panel.append(help, handoff, handoffResult);
+  const thinking = element('div', {class:'thinking',role:'status',hidden:''});
+  const dots = element('span', {class:'dots','aria-hidden':'true'});
+  dots.append(element('i'),element('i'),element('i'));
+  const thinkingLabel = element('span', {}, 'Cocoa is thinking…');
+  thinking.append(dots, thinkingLabel);
+  composer.before(thinking);
   panel.querySelector('strong').textContent = options.title || 'Cocoa support';
   const launcher = document.createElement('button');
   launcher.type = 'button';
@@ -75,7 +107,11 @@ export function createCocoa(options = {}) {
   launcher.setAttribute('aria-expanded', 'false');
   launcher.setAttribute('aria-controls', panel.id);
   launcher.setAttribute('aria-haspopup', 'dialog');
-  root.append(panel, launcher);
+  const greeting = element('div', {class:'greeting',hidden:''});
+  const greetingOpen = element('button', {type:'button',class:'greeting-open'}, options.greetingMessage || 'Hi! Ask me anything.');
+  const greetingDismiss = element('button', {type:'button',class:'greeting-dismiss','aria-label':'Dismiss greeting'}, '×');
+  greeting.append(greetingOpen,greetingDismiss);
+  root.append(panel, greeting, launcher);
   document.body.append(host);
   const messages = panel.querySelector('.messages');
   const status = panel.querySelector('.status');
@@ -87,12 +123,48 @@ export function createCocoa(options = {}) {
   name.value = String(options.visitorLabel || '').slice(0, 120);
   let session = null, pending = null, timer, destroyed = false, sending = false, refreshing = false;
   let generation = 0, terminal = false, paused = false, version = -1, failures = 0;
+  let incident = null, incidentPending = null, submittingIncident = false, expired = false;
+  let greetingTimer, audioContext, greetingSeen = false;
+  const greetingKey = key + ':greeted';
+  try { greetingSeen = sessionStorage.getItem(greetingKey) === '1'; } catch {}
+  const dismissGreeting = (remember = true) => {
+    clearTimeout(greetingTimer); greeting.hidden = true;
+    if (remember) { greetingSeen = true; try { sessionStorage.setItem(greetingKey,'1'); } catch {} }
+    document.removeEventListener('pointerdown', unlockAudio);
+    document.removeEventListener('keydown', unlockAudio);
+    if (audioContext) { void audioContext.close().catch(()=>{}); audioContext = null; }
+  };
+  function unlockAudio() {
+    if (destroyed || greetingSeen || options.greetingSound === false || audioContext) return;
+    try {
+      const Audio = window.AudioContext || window.webkitAudioContext;
+      if (Audio) { audioContext = new Audio(); void audioContext.resume().catch(()=>{}); }
+    } catch { /* Greeting still works when audio is unavailable. */ }
+  }
+  function showGreeting() {
+    if (destroyed || greetingSeen || !panel.hidden || session || options.greetingMessage === false || document.hidden) return;
+    greeting.hidden = false; greetingSeen = true;
+    try { sessionStorage.setItem(greetingKey,'1'); } catch {}
+    document.removeEventListener('pointerdown', unlockAudio);
+    document.removeEventListener('keydown', unlockAudio);
+    // Only play after a prior user gesture unlocked audio. Never queue a surprise sound.
+    if (audioContext?.state === 'running') {
+      try {
+        const tone = audioContext.createOscillator(), volume = audioContext.createGain();
+        const now = audioContext.currentTime;
+        tone.type = 'sine'; tone.frequency.setValueAtTime(660,now); tone.frequency.exponentialRampToValueAtTime(880,now+.1);
+        volume.gain.setValueAtTime(0,now); volume.gain.linearRampToValueAtTime(.045,now+.015); volume.gain.exponentialRampToValueAtTime(.001,now+.2);
+        tone.connect(volume); volume.connect(audioContext.destination); tone.start(now); tone.stop(now+.22);
+        tone.onended = () => { tone.disconnect(); volume.disconnect(); if (audioContext) { void audioContext.close().catch(()=>{}); audioContext=null; } };
+      } catch { if (audioContext) { void audioContext.close().catch(()=>{}); audioContext=null; } }
+    } else if (audioContext) { void audioContext.close().catch(()=>{}); audioContext=null; }
+  }
   const rendered = new Set();
   const requests = new Set();
   const persist = () => {
     if (options.persistSession === false) return;
     try {
-      if (session) sessionStorage.setItem(key, JSON.stringify({ ...session, pending }));
+      if (session) sessionStorage.setItem(key, JSON.stringify({ ...session, pending, incidentPending }));
       else sessionStorage.removeItem(key);
     } catch { /* Storage may be unavailable; an in-memory session still works. */ }
   };
@@ -101,6 +173,11 @@ export function createCocoa(options = {}) {
       const stored = JSON.parse(sessionStorage.getItem(key) || 'null');
       if (uuid.test(stored?.id || '') && /^[a-f0-9]{64}$/.test(stored?.token || '')) {
         session = { id: stored.id, token: stored.token };
+        const saved = stored.incidentPending;
+        if (saved && uuid.test(saved.idempotencyKey || '') && ['email','name','summary','details'].every(k=>typeof saved[k]==='string' && saved[k].length<=Number(fields[k].maxLength))) {
+          incidentPending = saved;
+          for (const k of Object.keys(fields)) fields[k].value = saved[k];
+        }
         if (typeof stored.pending?.body === 'string' && stored.pending.body.length <= 12000 && uuid.test(stored.pending.idempotencyKey)) {
           pending = stored.pending;
           input.value = pending.body;
@@ -117,7 +194,12 @@ export function createCocoa(options = {}) {
   welcome();
   const controls = () => {
     const focusWasInComposer = root.activeElement === input || root.activeElement === send;
-    input.disabled = sending || terminal || paused;
+    if (incident || !handoff.hidden || terminal || paused) thinking.hidden = true;
+    help.disabled = sending || submittingIncident || expired || paused;
+    help.hidden = !!incident || !handoff.hidden;
+    handoffResult.hidden = !incident;
+    if (incident) handoffResult.textContent = `Incident ${incident.reference} submitted. Follow-up will be by email at ${incident.email}.`;
+    input.disabled = sending || terminal || paused || submittingIncident;
     send.disabled = sending || terminal || paused;
     name.disabled = sending;
     fresh.hidden = !terminal;
@@ -129,6 +211,7 @@ export function createCocoa(options = {}) {
   };
   controls();
   const report = (error) => {
+    thinking.hidden = true;
     status.classList.add('error');
     status.textContent = error.message;
     try { options.onError?.(error); } catch { /* Host callback must not break chat. */ }
@@ -163,7 +246,7 @@ export function createCocoa(options = {}) {
   }
   function expire(error) {
     if (error.status === 401 || error.status === 404) {
-      terminal = true;
+      terminal = true; expired = true;
       session = null;
       pending = null;
       persist();
@@ -190,12 +273,15 @@ export function createCocoa(options = {}) {
       if (atBottom || version < 0) messages.scrollTop = messages.scrollHeight;
       version = data.version;
     }
+    incident = data.escalation || incident;
     terminal = data.state === 'closed';
     paused = !data.enabled;
     status.classList.remove('error');
-    status.textContent = terminal ? 'This conversation is closed.' : paused ? 'This chat is paused.' :
+    status.textContent = incident ? 'Your incident is with the support team. Follow-up will be by email.' : terminal ? 'This conversation is closed.' : paused ? 'This chat is paused.' :
       data.state === 'human' ? 'A person is handling your conversation.' :
       data.agentOnline ? 'Connected to support.' : 'The agent is offline. Your messages are saved for the team.';
+    const last = data.messages.filter(m=>['customer','agent','human'].includes(m.actor)).at(-1);
+    thinking.hidden = !(last?.actor === 'customer' && data.agentOnline && data.state === 'agent' && !terminal && !paused && !incident && handoff.hidden);
     controls();
   }
   function schedule() {
@@ -205,7 +291,7 @@ export function createCocoa(options = {}) {
     }
   }
   async function refresh() {
-    if (destroyed || refreshing || sending || panel.hidden || document.hidden || !session || terminal) return;
+    if (destroyed || refreshing || sending || submittingIncident || panel.hidden || document.hidden || !session || terminal) return;
     refreshing = true;
     const current = generation;
     try {
@@ -228,18 +314,25 @@ export function createCocoa(options = {}) {
   }
   function open() {
     if (destroyed) return;
+    dismissGreeting();
     panel.hidden = false;
     launcher.setAttribute('aria-expanded', 'true');
-    (terminal ? fresh : input).focus();
+    (!handoff.hidden ? fields.email : terminal ? fresh : input).focus();
     void refresh();
   }
   function reset() {
     if (destroyed) return;
     generation++;
     sending = refreshing = false;
+    thinking.hidden = true;
     for (const request of requests) request.abort();
     clearTimeout(timer);
-    session = pending = null;
+    session = pending = incident = incidentPending = null;
+    expired = submittingIncident = false;
+    handoff.hidden = true; composer.hidden = messages.hidden = false;
+    submitIncident.disabled = back.disabled = false;
+    for(const field of Object.values(fields)) { field.value = ''; field.disabled = false; }
+    handoffError.textContent = '';
     terminal = paused = false;
     version = -1;
     failures = 0;
@@ -254,12 +347,13 @@ export function createCocoa(options = {}) {
   }
   const visibility = () => {
     clearTimeout(timer);
-    if (!document.hidden) void refresh();
+    if (!document.hidden) { void refresh(); if (!greetingSeen) { clearTimeout(greetingTimer); greetingTimer=setTimeout(showGreeting,greetingDelay); } }
   };
   document.addEventListener('visibilitychange', visibility);
   const widget = { open, close, reset, toggle: () => panel.hidden ? open() : close(), destroy() {
     if (destroyed) return;
     destroyed = true;
+    dismissGreeting(false);
     generation++;
     clearTimeout(timer);
     for (const request of requests) request.abort();
@@ -268,6 +362,8 @@ export function createCocoa(options = {}) {
     instances.delete(key);
   } };
   launcher.onclick = widget.toggle;
+  greetingOpen.onclick = open;
+  greetingDismiss.onclick = () => { dismissGreeting(); launcher.focus(); };
   panel.querySelector('header button').onclick = close;
   fresh.onclick = reset;
   root.addEventListener('keydown', (event) => {
@@ -276,8 +372,9 @@ export function createCocoa(options = {}) {
   form.onsubmit = async (event) => {
     event.preventDefault();
     const body = input.value.trim();
-    if (!body || sending || terminal || paused || destroyed) return;
+    if (!body || sending || submittingIncident || terminal || paused || destroyed) return;
     sending = true;
+    thinking.hidden = true;
     controls();
     clearTimeout(timer);
     const current = generation;
@@ -312,6 +409,60 @@ export function createCocoa(options = {}) {
       }
     }
   };
+  function showChat() {
+    handoff.hidden = true; composer.hidden = messages.hidden = false; controls();
+    if (!panel.hidden) (input.disabled ? help : input).focus();
+  }
+  help.onclick = () => {
+    if (expired || paused || incident || sending || submittingIncident) return;
+    const last = [...messages.querySelectorAll('.customer span')].at(-1)?.textContent || input.value.trim();
+    if (!fields.summary.value) fields.summary.value = (last || 'Help with ' + (options.title || 'this application')).slice(0,200);
+    if (!fields.details.value) fields.details.value = last || '';
+    if (!fields.name.value) fields.name.value = name.value;
+    thinking.hidden = true;
+    handoff.hidden = false; composer.hidden = messages.hidden = true; controls(); fields.email.focus();
+  };
+  back.onclick = showChat;
+  handoff.onsubmit = async event => {
+    event.preventDefault();
+    if (submittingIncident || sending || expired || paused || incident || destroyed) return;
+    const data = Object.fromEntries(Object.entries(fields).map(([k,v])=>[k,v.value.trim()]));
+    if (!data.summary || !data.details || !data.email) return;
+    submittingIncident = true; submitIncident.disabled = back.disabled = true;
+    for(const field of Object.values(fields)) field.disabled = true;
+    handoffError.textContent = ''; controls();
+    const current = generation;
+    try {
+      if (!session) {
+        const result = await call(`/chat/${options.chatbotId}/sessions`, { label: data.name || 'Visitor' });
+        if (destroyed || current !== generation) return;
+        if (!uuid.test(result.id || '') || !/^[a-f0-9]{64}$/.test(result.token || '')) throw new Error('Chat returned an invalid session. Please try again.');
+        session = {id:result.id,token:result.token};
+      }
+      if (!incidentPending || Object.keys(data).some(k=>data[k]!==incidentPending[k])) incidentPending = {...data,idempotencyKey:crypto.randomUUID()};
+      persist();
+      const result = await call(`/chat/sessions/${session.id}/escalations`, incidentPending, session.token);
+      if (destroyed || current !== generation) return;
+      if (!result?.reference || !result?.email) throw new Error('Submission could not be confirmed. Please retry.');
+      incident = result; incidentPending = null; persist(); showChat(); handoffResult.focus();
+    } catch(error) {
+      if (!destroyed && current === generation) {
+        expire(error);
+        handoffError.textContent = expired ? 'This session expired. Return to chat and explicitly start a new conversation before submitting.' : 'Submission could not be confirmed. Your details are kept here; retry to check or submit the same incident.';
+      }
+    } finally {
+      if (!destroyed && current === generation) {
+        submittingIncident = false; submitIncident.disabled = back.disabled = false;
+        for(const field of Object.values(fields)) field.disabled = false;
+        controls(); schedule();
+      }
+    }
+  };
+  if (!greetingSeen && !session && options.greetingMessage !== false) {
+    document.addEventListener('pointerdown', unlockAudio);
+    document.addEventListener('keydown', unlockAudio);
+    greetingTimer=setTimeout(showGreeting,greetingDelay);
+  }
   instances.set(key, widget);
   return widget;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sub-zero/cocoa",
-  "version": "0.1.1",
+  "version": "0.2.1",
   "description": "Drop-in Cocoa support chat for any website, powered by SubZero.",
   "type": "module",
   "main": "./dist/index.cjs",