@sub-zero/cocoa 0.2.0 → 0.2.2

package/README.md

@@ -169,3 +169,11 @@ may be private.
 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,6 +35,9 @@ 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:relative;margin:0 0 12px auto;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}
@@ -84,6 +89,12 @@ function createCocoa(options = {}) {
   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';
@@ -98,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');
@@ -111,6 +126,41 @@ function createCocoa(options = {}) {
   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 = () => {
@@ -146,6 +196,7 @@ function createCocoa(options = {}) {
   welcome();
   const controls = () => {
     const focusWasInComposer = root.activeElement === input || root.activeElement === send;
+    if (incident || !handoff.hidden || terminal || paused) thinking.hidden = true;
     help.disabled = sending || submittingIncident || expired || paused;
     help.hidden = !!incident || !handoff.hidden;
     handoffResult.hidden = !incident;
@@ -162,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. */ }
@@ -230,6 +282,8 @@ function createCocoa(options = {}) {
     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() {
@@ -262,6 +316,7 @@ function createCocoa(options = {}) {
   }
   function open() {
     if (destroyed) return;
+    dismissGreeting();
     panel.hidden = false;
     launcher.setAttribute('aria-expanded', 'true');
     (!handoff.hidden ? fields.email : terminal ? fresh : input).focus();
@@ -271,6 +326,7 @@ function createCocoa(options = {}) {
     if (destroyed) return;
     generation++;
     sending = refreshing = false;
+    thinking.hidden = true;
     for (const request of requests) request.abort();
     clearTimeout(timer);
     session = pending = incident = incidentPending = null;
@@ -293,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();
@@ -307,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) => {
@@ -317,6 +376,7 @@ function createCocoa(options = {}) {
     const body = input.value.trim();
     if (!body || sending || submittingIncident || terminal || paused || destroyed) return;
     sending = true;
+    thinking.hidden = true;
     controls();
     clearTimeout(timer);
     const current = generation;
@@ -361,6 +421,7 @@ function createCocoa(options = {}) {
     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;
@@ -399,6 +460,11 @@ function createCocoa(options = {}) {
       }
     }
   };
+  if (!greetingSeen && !session && options.greetingMessage !== false) {
+    document.addEventListener('pointerdown', unlockAudio);
+    document.addEventListener('keydown', unlockAudio);
+    greetingTimer=setTimeout(showGreeting,greetingDelay);
+  }
   instances.set(key, widget);
   return widget;
 }
@@ -413,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,6 +33,9 @@ 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:relative;margin:0 0 12px auto;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}
@@ -82,6 +87,12 @@ function createCocoa(options = {}) {
   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';
@@ -96,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');
@@ -109,6 +124,41 @@ function createCocoa(options = {}) {
   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 = () => {
@@ -144,6 +194,7 @@ function createCocoa(options = {}) {
   welcome();
   const controls = () => {
     const focusWasInComposer = root.activeElement === input || root.activeElement === send;
+    if (incident || !handoff.hidden || terminal || paused) thinking.hidden = true;
     help.disabled = sending || submittingIncident || expired || paused;
     help.hidden = !!incident || !handoff.hidden;
     handoffResult.hidden = !incident;
@@ -160,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. */ }
@@ -228,6 +280,8 @@ function createCocoa(options = {}) {
     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() {
@@ -260,6 +314,7 @@ function createCocoa(options = {}) {
   }
   function open() {
     if (destroyed) return;
+    dismissGreeting();
     panel.hidden = false;
     launcher.setAttribute('aria-expanded', 'true');
     (!handoff.hidden ? fields.email : terminal ? fresh : input).focus();
@@ -269,6 +324,7 @@ function createCocoa(options = {}) {
     if (destroyed) return;
     generation++;
     sending = refreshing = false;
+    thinking.hidden = true;
     for (const request of requests) request.abort();
     clearTimeout(timer);
     session = pending = incident = incidentPending = null;
@@ -291,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();
@@ -305,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) => {
@@ -315,6 +374,7 @@ function createCocoa(options = {}) {
     const body = input.value.trim();
     if (!body || sending || submittingIncident || terminal || paused || destroyed) return;
     sending = true;
+    thinking.hidden = true;
     controls();
     clearTimeout(timer);
     const current = generation;
@@ -359,6 +419,7 @@ function createCocoa(options = {}) {
     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;
@@ -397,6 +458,11 @@ function createCocoa(options = {}) {
       }
     }
   };
+  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,6 +33,9 @@ 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:relative;margin:0 0 12px auto;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}
@@ -82,6 +87,12 @@ export function createCocoa(options = {}) {
   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';
@@ -96,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');
@@ -109,6 +124,41 @@ export function createCocoa(options = {}) {
   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 = () => {
@@ -144,6 +194,7 @@ export function createCocoa(options = {}) {
   welcome();
   const controls = () => {
     const focusWasInComposer = root.activeElement === input || root.activeElement === send;
+    if (incident || !handoff.hidden || terminal || paused) thinking.hidden = true;
     help.disabled = sending || submittingIncident || expired || paused;
     help.hidden = !!incident || !handoff.hidden;
     handoffResult.hidden = !incident;
@@ -160,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. */ }
@@ -228,6 +280,8 @@ export function createCocoa(options = {}) {
     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() {
@@ -260,6 +314,7 @@ export function createCocoa(options = {}) {
   }
   function open() {
     if (destroyed) return;
+    dismissGreeting();
     panel.hidden = false;
     launcher.setAttribute('aria-expanded', 'true');
     (!handoff.hidden ? fields.email : terminal ? fresh : input).focus();
@@ -269,6 +324,7 @@ export function createCocoa(options = {}) {
     if (destroyed) return;
     generation++;
     sending = refreshing = false;
+    thinking.hidden = true;
     for (const request of requests) request.abort();
     clearTimeout(timer);
     session = pending = incident = incidentPending = null;
@@ -291,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();
@@ -305,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) => {
@@ -315,6 +374,7 @@ export function createCocoa(options = {}) {
     const body = input.value.trim();
     if (!body || sending || submittingIncident || terminal || paused || destroyed) return;
     sending = true;
+    thinking.hidden = true;
     controls();
     clearTimeout(timer);
     const current = generation;
@@ -359,6 +419,7 @@ export function createCocoa(options = {}) {
     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;
@@ -397,6 +458,11 @@ export function createCocoa(options = {}) {
       }
     }
   };
+  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.2.0",
+  "version": "0.2.2",
   "description": "Drop-in Cocoa support chat for any website, powered by SubZero.",
   "type": "module",
   "main": "./dist/index.cjs",