@sub-zero/cocoa 0.1.1 → 0.2.0

package/README.md

@@ -163,3 +163,9 @@ 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.

package/dist/cocoa.js

@@ -38,6 +38,7 @@ function createCocoa(options = {}) {
     .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 +64,26 @@ 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);
   panel.querySelector('strong').textContent = options.title || 'Cocoa support';
   const launcher = document.createElement('button');
   launcher.type = 'button';
@@ -89,12 +110,13 @@ 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;
   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 +125,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 +146,11 @@ function createCocoa(options = {}) {
   welcome();
   const controls = () => {
     const focusWasInComposer = root.activeElement === input || root.activeElement === send;
-    input.disabled = sending || terminal || paused;
+    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;
@@ -165,7 +196,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,10 +223,11 @@ 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.';
     controls();
@@ -207,7 +239,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 {
@@ -232,7 +264,7 @@ function createCocoa(options = {}) {
     if (destroyed) return;
     panel.hidden = false;
     launcher.setAttribute('aria-expanded', 'true');
-    (terminal ? fresh : input).focus();
+    (!handoff.hidden ? fields.email : terminal ? fresh : input).focus();
     void refresh();
   }
   function reset() {
@@ -241,7 +273,12 @@ function createCocoa(options = {}) {
     sending = refreshing = false;
     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;
@@ -278,7 +315,7 @@ 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;
     controls();
     clearTimeout(timer);
@@ -314,6 +351,54 @@ 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;
+    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();
+      }
+    }
+  };
   instances.set(key, widget);
   return widget;
 }

package/dist/index.cjs

@@ -36,6 +36,7 @@ function createCocoa(options = {}) {
     .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 +62,26 @@ 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);
   panel.querySelector('strong').textContent = options.title || 'Cocoa support';
   const launcher = document.createElement('button');
   launcher.type = 'button';
@@ -87,12 +108,13 @@ 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;
   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 +123,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 +144,11 @@ function createCocoa(options = {}) {
   welcome();
   const controls = () => {
     const focusWasInComposer = root.activeElement === input || root.activeElement === send;
-    input.disabled = sending || terminal || paused;
+    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;
@@ -163,7 +194,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,10 +221,11 @@ 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.';
     controls();
@@ -205,7 +237,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,7 +262,7 @@ function createCocoa(options = {}) {
     if (destroyed) return;
     panel.hidden = false;
     launcher.setAttribute('aria-expanded', 'true');
-    (terminal ? fresh : input).focus();
+    (!handoff.hidden ? fields.email : terminal ? fresh : input).focus();
     void refresh();
   }
   function reset() {
@@ -239,7 +271,12 @@ function createCocoa(options = {}) {
     sending = refreshing = false;
     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;
@@ -276,7 +313,7 @@ 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;
     controls();
     clearTimeout(timer);
@@ -312,6 +349,54 @@ 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;
+    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();
+      }
+    }
+  };
   instances.set(key, widget);
   return widget;
 }

package/dist/index.js

@@ -36,6 +36,7 @@ export function createCocoa(options = {}) {
     .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 +62,26 @@ 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);
   panel.querySelector('strong').textContent = options.title || 'Cocoa support';
   const launcher = document.createElement('button');
   launcher.type = 'button';
@@ -87,12 +108,13 @@ 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;
   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 +123,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 +144,11 @@ export function createCocoa(options = {}) {
   welcome();
   const controls = () => {
     const focusWasInComposer = root.activeElement === input || root.activeElement === send;
-    input.disabled = sending || terminal || paused;
+    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;
@@ -163,7 +194,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,10 +221,11 @@ 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.';
     controls();
@@ -205,7 +237,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 {
@@ -230,7 +262,7 @@ export function createCocoa(options = {}) {
     if (destroyed) return;
     panel.hidden = false;
     launcher.setAttribute('aria-expanded', 'true');
-    (terminal ? fresh : input).focus();
+    (!handoff.hidden ? fields.email : terminal ? fresh : input).focus();
     void refresh();
   }
   function reset() {
@@ -239,7 +271,12 @@ export function createCocoa(options = {}) {
     sending = refreshing = false;
     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;
@@ -276,7 +313,7 @@ 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;
     controls();
     clearTimeout(timer);
@@ -312,6 +349,54 @@ 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;
+    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();
+      }
+    }
+  };
   instances.set(key, widget);
   return widget;
 }

package/package.json

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