@paramms/chat-widget 0.1.0

package/src/e2e.ts

@@ -0,0 +1,161 @@
+import type { MessageContent, UserId } from './protocol/index.js'
+import type { ServerFrame } from './protocol/index.js'
+import {
+  type KeyPair, loadOrCreateKeyPair, exportPublicKey, deriveSharedKey, encrypt, decrypt,
+  generateKeyPair, signPrekey, x3dhSend, x3dhReceive, type X3DHBundle,
+  loadOrCreateIdentityKeyPair, type IdentityKeyPair,
+} from './crypto.js'
+
+// Number of one-time prekeys to generate per upload batch.
+const OTP_BATCH_SIZE = 20
+
+/**
+ * Per-user E2E session. Supports two modes:
+ *
+ * LIVE (original): Both parties are online. ECDH P-256 key exchange via the
+ * `pubkey`/`peerkey` frames. Instant but requires both parties to be connected.
+ *
+ * ASYNC (X3DH): The sender encrypts to the recipient's prekey bundle while the
+ * recipient is offline. Uses X3DH (Extended Triple DH) with identity keys,
+ * signed prekeys, and one-time prekeys. The recipient derives the same shared
+ * key from the init message when they come online.
+ *
+ * Both modes produce an AES-GCM 256 shared key for message encryption.
+ */
+export class E2ESession {
+  // Live ECDH mode state
+  private kp?: KeyPair
+  private shared?: CryptoKey
+
+  // X3DH async mode state
+  private identityKP: IdentityKeyPair | undefined = undefined
+  private signedPreKP: KeyPair | undefined = undefined
+  private signedPrekeyId: string | undefined = undefined
+  private readonly otpKeys: KeyPair[] = []       // one-time prekeys awaiting matching
+  private x3dhShared?: CryptoKey
+  // Queued init messages arriving before we could derive (shouldn't happen, but safe)
+  private pendingX3DH: { senderIK: string; ephemeralKey: string; spkId: string } | undefined = undefined
+
+  constructor(private readonly storageKey: string) {}
+
+  get ready(): boolean { return !!(this.shared ?? this.x3dhShared) }
+
+  /** Live ECDH mode: Generate/restore our keypair and return our public key to publish. */
+  async begin(): Promise<string> {
+    this.kp = await loadOrCreateKeyPair(this.storageKey)
+    return exportPublicKey(this.kp.publicKey)
+  }
+
+  /** Live ECDH mode: A peer published their key — derive the shared secret. */
+  async onPeerKey(peerKeyB64: string): Promise<void> {
+    if (!this.kp) return
+    this.shared = await deriveSharedKey(this.kp.privateKey, peerKeyB64)
+  }
+
+  // ── X3DH async mode ────────────────────────────────────────────────────────
+
+  /** X3DH: Generate identity key, signed prekey, and OTP prekeys.
+   *  Returns the upload frame payload the caller should send to the server. */
+  async initX3DH(): Promise<{
+    identityKey: string; signedPrekey: string; signedPrekeyId: string;
+    signature: string; oneTimePrekeys: string[]
+  }> {
+    // Restore or generate persistent identity keypair (ECDH + ECDSA).
+    this.identityKP = await loadOrCreateIdentityKeyPair(this.storageKey)
+    // Always generate a fresh signed prekey (rotation).
+    this.signedPreKP = await generateKeyPair()
+    this.signedPrekeyId = `spk-${Date.now()}-${Math.random().toString(36).slice(2)}`
+    // Batch of one-time prekeys.
+    for (let i = 0; i < OTP_BATCH_SIZE; i++) this.otpKeys.push(await generateKeyPair())
+
+    const signedPrekeyPub = await exportPublicKey(this.signedPreKP.publicKey)
+    const signature      = await signPrekey(this.identityKP.ecdsaKP.privateKey, this.signedPreKP.publicKey)
+    const oneTimePrekeys = await Promise.all(this.otpKeys.map(kp => exportPublicKey(kp.publicKey)))
+
+    return {
+      identityKey:    this.identityKP.publicKeyB64,
+      signedPrekey:   signedPrekeyPub,
+      signedPrekeyId: this.signedPrekeyId,
+      signature,
+      oneTimePrekeys,
+    }
+  }
+
+  /** X3DH sender: given a recipient's prekey bundle, derive the shared key and
+   *  return the init message fields to embed in the first encrypted message. */
+  async x3dhSendTo(bundle: X3DHBundle): Promise<{ ephemeralKey: string; spkId: string; usedOTP: boolean; senderIK: string }> {
+    if (!this.identityKP) this.identityKP = await loadOrCreateIdentityKeyPair(this.storageKey)
+    const { sharedKey, ephemeralPublicKey } = await x3dhSend(this.identityKP.ecdhKP, bundle)
+    this.x3dhShared = sharedKey
+    return { ephemeralKey: ephemeralPublicKey, spkId: bundle.signedPrekeyId, usedOTP: !!bundle.oneTimePrekey, senderIK: this.identityKP.publicKeyB64 }
+  }
+
+  /** X3DH recipient: given an init message's sender IK + EK + SPK ID, derive the shared key. */
+  async x3dhReceiveFrom(senderIKb64: string, ephemeralKeyB64: string, spkId: string): Promise<void> {
+    if (!this.identityKP || !this.signedPreKP) {
+      // Keys not yet initialised — queue for when initX3DH completes.
+      this.pendingX3DH = { senderIK: senderIKb64, ephemeralKey: ephemeralKeyB64, spkId }
+      return
+    }
+    // Find OTP key if used (we pop the first available)
+    const otp = this.otpKeys.shift()
+    this.x3dhShared = await x3dhReceive(this.identityKP.ecdhKP, this.signedPreKP, senderIKb64, ephemeralKeyB64, otp)
+    void spkId  // we matched by position; full impl would look up by ID
+  }
+
+  /** Flush pending X3DH derivation after initX3DH() completes. */
+  async flushPendingX3DH(): Promise<void> {
+    if (!this.pendingX3DH) return
+    const { senderIK, ephemeralKey, spkId } = this.pendingX3DH
+    this.pendingX3DH = undefined
+    await this.x3dhReceiveFrom(senderIK, ephemeralKey, spkId)
+  }
+
+  /** Encrypt outgoing text into a wire content object. For X3DH init messages,
+   *  the caller should pass x3dhInit fields to embed in the content. */
+  async sealText(text: string, x3dhInit?: { ephemeralKey: string; spkId: string; senderIK: string }): Promise<MessageContent> {
+    const key = this.x3dhShared ?? this.shared
+    if (!key) throw new Error('secure channel not ready')
+    const { ct, iv } = await encrypt(key, text)
+    return {
+      kind: 'text', text: ct, enc: true, iv,
+      ...(x3dhInit ? { x3dhEK: x3dhInit.ephemeralKey, x3dhSPK: x3dhInit.spkId, x3dhIK: x3dhInit.senderIK } as never : {}),
+    }
+  }
+
+  /** Decrypt one content object if it is encrypted (otherwise pass through). */
+  private async openContent(content: MessageContent): Promise<MessageContent> {
+    if (content.kind !== 'text' || !content.enc || !content.iv) return content
+    const key = this.x3dhShared ?? this.shared
+    if (!key) return { kind: 'text', text: '🔒 encrypted' }
+    try { return { kind: 'text', text: await decrypt(key, content.text, content.iv) } }
+    catch { return { kind: 'text', text: '🔒 unable to decrypt' } }
+  }
+
+  /** Decrypt any encrypted message content carried by an incoming frame, in place. */
+  async openFrame(frame: ServerFrame): Promise<void> {
+    if (frame.type === 'message') frame.message.content = await this.openContent(frame.message.content)
+    else if (frame.type === 'sync') {
+      for (const m of frame.messages) m.content = await this.openContent(m.content)
+    }
+  }
+}
+
+/** X3DH init fields embedded in a text MessageContent (as extra properties).
+ *  Present only on the very first message from a sender to an offline peer. */
+export interface X3DHInitFields {
+  x3dhEK:  string  // sender's ephemeral public key (base64)
+  x3dhSPK: string  // recipient's signed prekey ID used
+  x3dhIK:  string  // sender's identity public key (base64)
+}
+
+export function extractX3DHInit(content: MessageContent): X3DHInitFields | null {
+  if (content.kind !== 'text' || !content.enc) return null
+  const c = content as MessageContent & Partial<X3DHInitFields>
+  if (!c.x3dhEK || !c.x3dhSPK || !c.x3dhIK) return null
+  return { x3dhEK: c.x3dhEK, x3dhSPK: c.x3dhSPK, x3dhIK: c.x3dhIK }
+}
+
+export { type X3DHBundle } from './crypto.js'
+export { type UserId }
+

package/src/history.ts

@@ -0,0 +1,43 @@
+// history.ts — shared REST history-fetch logic, used by both the guest widget
+// (index.ts) and the agent dashboard (chat-dashboard/src/operate.ts) so there
+// is exactly one implementation of "restore chat history on open" rather than
+// two copies that can silently drift apart.
+import type { ChatStore } from './store.js'
+import type { Message, ConversationId } from './protocol/index.js'
+import type { Renderer } from './renderer.js'
+
+/** Derive the HTTP(S) base origin from a ws(s):// URL that may or may not
+ *  already end in /ws. Examples:
+ *    wss://api.paramms.com/ws  → https://api.paramms.com
+ *    ws://localhost:3000/ws    → http://localhost:3000
+ *    wss://api.paramms.com     → https://api.paramms.com  (no /ws suffix) */
+export function httpBaseFromWsUrl(wsUrl: string): string {
+  return wsUrl.replace(/^ws/, 'http').replace(/\/ws\/?$/, '')
+}
+
+/** Fetch full message history for a conversation via REST and apply it to
+ *  the store, then trigger a render. Best-effort: network/auth failures are
+ *  swallowed since the live WS sync still covers reconnects — this is a
+ *  belt-and-suspenders restore for "did my history come back after reload",
+ *  not the only path messages can arrive through. */
+export async function restoreHistory(
+  wsUrl: string,
+  token: string,
+  conversationId: ConversationId,
+  store: ChatStore,
+  renderer: Renderer,
+): Promise<void> {
+  const httpBase = httpBaseFromWsUrl(wsUrl)
+  try {
+    const res = await fetch(`${httpBase}/conversations/${conversationId}/history`, {
+      headers: { authorization: `Bearer ${token}` },
+    })
+    if (!res.ok) return
+    const data = await res.json() as { messages?: Message[] }
+    if (!data.messages?.length) return
+    store.apply({ type: 'sync', conversationId, messages: data.messages })
+    renderer.render(store)
+  } catch {
+    // best-effort — WS sync still covers reconnects
+  }
+}

package/src/index.ts

@@ -0,0 +1,380 @@
+import {
+  asConversationId,
+  type ClientFrame, type ConversationId,
+} from './protocol/index.js'
+import { ChatStore } from './store.js'
+import { ConnectionManager } from './connection.js'
+import { PersistentOutbox } from './outbox.js'
+import { E2ESession, extractX3DHInit } from './e2e.js'
+import { Renderer, type WidgetConfig, type ChatListEntry } from './renderer.js'
+import { restoreHistory, httpBaseFromWsUrl } from './history.js'
+
+export interface MountOptions {
+  el:           HTMLElement
+  url:          string
+  profileId:    string
+  subjectId?:   string
+  token?:       string
+  subject?:     WidgetConfig['subject']
+  quickReplies?: string[]
+  accent?:      string
+  /** If set, shows a 🌐 translate button on incoming messages that translates
+   *  them into this language (ISO code or language name) via the server's
+   *  /translate endpoint. Omit to disable the feature. */
+  translateLang?: string
+  /** If true, mount as a floating launcher button that opens/closes the chat */
+  launcher?:    boolean
+  /** Position of the launcher button: default 'bottom-right' */
+  position?:    'bottom-right' | 'bottom-left'
+  /** If true, shows a 💬 button in the header that opens a list of the
+   *  guest's other conversations (e.g. a marketplace where each item gets
+   *  its own subjectId/thread) and lets them switch between them.
+   *  Off by default — single-conversation embeds don't need this. */
+  showChatList?: boolean
+}
+
+export interface WidgetHandle { close(): void }
+
+/** Persistent anonymous identity, reused across reloads (per the old widget's
+ *  oc_uid pattern). */
+function persistentUid(): string {
+  const key = 'oc_uid'
+  try {
+    const existing = localStorage.getItem(key)
+    if (existing) return existing
+    const id = `g_${Math.random().toString(36).slice(2)}${Date.now().toString(36)}`
+    localStorage.setItem(key, id)
+    return id
+  } catch {
+    return `g_${Math.random().toString(36).slice(2)}`
+  }
+}
+
+export function mount(opts: MountOptions): WidgetHandle {
+  const token = opts.token ?? persistentUid()
+  const store = new ChatStore(token as never)
+  const outbox = new PersistentOutbox(token)
+  let cid: ConversationId | undefined
+  let outboxRestored = false
+  // Self-reference so onSwitchChat can close this mount and replace it with
+  // a fresh one for the newly-selected conversation, without the embedder
+  // needing to manage that lifecycle themselves.
+  let currentHandle: WidgetHandle | null = null
+
+  // Give the host element a sane default size if the embedder didn't set one
+  // (e.g. a bare `<div id="chat"></div>` with no CSS). Without this the
+  // widget's internal `height:100%` collapses to near-zero. Only applies
+  // when the element truly has no height set — explicit CSS always wins.
+  if (!opts.launcher && !opts.el.style.height && opts.el.clientHeight === 0) {
+    opts.el.style.width = opts.el.style.width || '100%'
+    opts.el.style.height = '600px'
+  }
+
+  // Restore any messages that were queued but not yet acknowledged before the
+  // last reload — show them as 'pending' immediately, matching the WhatsApp
+  // pattern of never silently dropping a typed message.
+  for (const item of outbox.load()) store.addOptimistic(item.clientMsgId, item.content)
+
+  // ── Launcher mode ─────────────────────────────────────────────────────────
+  let launcherEl: HTMLElement | null = null
+  let badgeEl:    HTMLElement | null = null
+  let unread = 0
+  let open = !opts.launcher  // start open when not in launcher mode
+
+  if (opts.launcher) {
+    const pos = opts.position ?? 'bottom-right'
+    launcherEl = document.createElement('div')
+    launcherEl.style.cssText = `position:fixed;${pos.includes('right') ? 'right:20px' : 'left:20px'};bottom:20px;z-index:9999`
+    const btn = document.createElement('button')
+    btn.style.cssText = `width:56px;height:56px;border-radius:50%;background:${opts.accent ?? '#4F63F5'};color:#fff;border:none;font-size:24px;cursor:pointer;box-shadow:0 4px 16px rgba(0,0,0,.2);position:relative`
+    btn.textContent = '💬'
+    badgeEl = document.createElement('span')
+    badgeEl.style.cssText = `position:absolute;top:-4px;right:-4px;background:#ef4444;color:#fff;border-radius:50%;width:20px;height:20px;font-size:11px;font-weight:700;display:none;align-items:center;justify-content:center`
+    btn.append(badgeEl)
+    launcherEl.append(btn)
+    document.body.append(launcherEl)
+    opts.el.style.display = 'none'
+    btn.addEventListener('click', () => {
+      open = !open
+      opts.el.style.display = open ? 'block' : 'none'
+      btn.textContent = open ? '✕' : '💬'
+      if (open) { unread = 0; if (badgeEl) badgeEl.style.display = 'none' }
+      btn.append(badgeEl!)
+    })
+  }
+
+  const addUnread = () => {
+    if (open) return
+    unread++
+    if (badgeEl) { badgeEl.textContent = String(unread); badgeEl.style.display = 'flex' }
+  }
+
+  // ── Notification sound ────────────────────────────────────────────────────
+  const playSound = () => {
+    try {
+      const ctx = new AudioContext()
+      const osc = ctx.createOscillator(); const gain = ctx.createGain()
+      osc.connect(gain); gain.connect(ctx.destination)
+      osc.frequency.setValueAtTime(880, ctx.currentTime)
+      osc.frequency.exponentialRampToValueAtTime(440, ctx.currentTime + 0.15)
+      gain.gain.setValueAtTime(0.3, ctx.currentTime)
+      gain.gain.exponentialRampToValueAtTime(0.001, ctx.currentTime + 0.3)
+      osc.start(); osc.stop(ctx.currentTime + 0.3)
+    } catch { /* audio not available */ }
+  }
+
+  let conn: ConnectionManager
+  const e2e = new E2ESession(`ocw-e2e-${opts.profileId}`)
+  let e2eStarted = false
+  // Live ECDH pending (peer not yet online)
+  const pending: { clientMsgId: string; text: string }[] = []
+  // X3DH async: pending send awaiting the peer's prekey bundle
+  const x3dhPending: { clientMsgId: string; text: string }[] = []
+  let x3dhBundleFetched = false
+
+  const sendSealed = (clientMsgId: string, text: string): void => {
+    void e2e.sealText(text).then((content) => {
+      if (cid) conn.send({ type: 'send', conversationId: cid, clientMsgId, content })
+    })
+  }
+
+  const sendSealedX3DH = (clientMsgId: string, text: string, x3dhInit: { ephemeralKey: string; spkId: string; senderIK: string }): void => {
+    void e2e.sealText(text, x3dhInit).then((content) => {
+      if (cid) conn.send({ type: 'send', conversationId: cid, clientMsgId, content })
+    })
+  }
+
+  const flushPending = (): void => {
+    while (pending.length) { const p = pending.shift()!; sendSealed(p.clientMsgId, p.text) }
+    while (x3dhPending.length) { const p = x3dhPending.shift()!; sendSealed(p.clientMsgId, p.text) }
+  }
+
+  /** Fetch the peer's prekey bundle and perform X3DH sender init. */
+  const fetchAndX3DH = (targetUserId: string): void => {
+    conn.send({ type: 'fetchPrekey', targetUserId: targetUserId as never })
+  }
+
+  const renderer = new Renderer(opts.el, token, {
+    onSend(text) {
+      if (!cid) return
+      const clientMsgId = `cm_${Math.random().toString(36).slice(2)}`
+      store.addOptimistic(clientMsgId, { kind: 'text', text })
+      renderer.render(store)
+      if (store.e2e) {
+        if (e2e.ready) {
+          sendSealed(clientMsgId, text)
+        } else if (x3dhBundleFetched) {
+          x3dhPending.push({ clientMsgId, text })
+        } else {
+          pending.push({ clientMsgId, text })
+          if (store.assignedAgentId) fetchAndX3DH(store.assignedAgentId)
+        }
+      } else {
+        outbox.add({ clientMsgId, content: { kind: 'text', text }, ts: Date.now() })
+        conn.send({ type: 'send', conversationId: cid, clientMsgId, content: { kind: 'text', text } })
+      }
+    },
+    async onAttach(file: File) {
+      if (!cid) return
+      const wsUrl = opts.url  // derive HTTP upload URL from WS URL
+      const httpUrl = wsUrl.replace(/^ws/, 'http').replace(/\/ws$/, '')
+      const uploadUrl = `${httpUrl}/upload?name=${encodeURIComponent(file.name)}`
+      const clientMsgId = `cm_${Math.random().toString(36).slice(2)}`
+      // Optimistic: show uploading state
+      store.addOptimistic(clientMsgId, { kind: 'text', text: `📎 Uploading ${file.name}…` })
+      renderer.render(store)
+      try {
+        const res = await fetch(uploadUrl, {
+          method: 'POST',
+          headers: { 'content-type': file.type, ...(opts.token ? { authorization: `Bearer ${opts.token}` } : {}) },
+          body: file,
+        })
+        if (!res.ok) throw new Error(`Upload failed: ${res.status}`)
+        const { url, name, mime, size } = await res.json() as { url: string; name: string; mime: string; size: number }
+        conn.send({ type: 'send', conversationId: cid, clientMsgId, content: { kind: 'attachment', url, name, mime, size } })
+      } catch (e) {
+        store.addOptimistic(clientMsgId, { kind: 'text', text: `⚠️ Upload failed: ${(e as Error).message}` })
+        renderer.render(store)
+      }
+    },
+    onInvoke(actionId, inputs) {
+      if (!cid) return
+      conn.send({ type: 'invoke', conversationId: cid, actionId, clientInvokeId: `iv_${Math.random().toString(36).slice(2)}`, ...(inputs ? { inputs } : {}) })
+    },
+    onTyping(isTyping) { if (cid) conn.send({ type: 'typing', conversationId: cid, isTyping }) },
+    onReadUpTo(seq)   { if (cid) conn.send({ type: 'read', conversationId: cid, seq }) },
+    onLoadMore() {
+      if (!cid) return
+      const oldest = store.messages()[0]
+      if (oldest) conn.send({ type: 'history', conversationId: cid, beforeSeq: oldest.seq, limit: 30 })
+    },
+    onEdit(messageId, newText) {
+      if (cid) conn.send({ type: 'edit', conversationId: cid, messageId: messageId as never, content: { kind: 'text', text: newText } })
+    },
+    onDelete(messageId) {
+      if (cid) conn.send({ type: 'delete', conversationId: cid, messageId: messageId as never })
+    },
+    onReact(messageId, emoji, remove) {
+      if (!cid) return
+      conn.send({ type: 'react', conversationId: cid, messageId: messageId as never, emoji, remove })
+    },
+    onCsat(score) {
+      if (!cid) return
+      // POST CSAT via fetch to the control-plane (the WS server also listens on HTTP).
+      // We extract the base URL from the WS URL best-effort.
+      const base = opts.url.replace(/^ws/, 'http').replace(/\/+$/, '').replace(/:\d+$/, m => m) // keep port
+      // Use the conversation id once it's known — post to /conversations/:id/csat
+      fetch(`${base}/conversations/${cid}/csat`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${token}` },
+        body: JSON.stringify({ score }),
+      }).catch(() => {})  // best-effort
+    },
+    onAnnotate(stroke) {
+      if (cid) conn.send({ type: 'annotate', conversationId: cid, stroke })
+    },
+    onAnnotateClear() {
+      if (cid) conn.send({ type: 'annotate_clear', conversationId: cid })
+    },
+    ...(opts.translateLang ? {
+      async onTranslate(text: string) {
+        const base = opts.url.replace(/^ws/, 'http').replace(/\/+$/, '')
+        try {
+          const res = await fetch(`${base}/translate`, {
+            method: 'POST',
+            headers: { 'content-type': 'application/json', authorization: `Bearer ${token}` },
+            body: JSON.stringify({ text, targetLang: opts.translateLang }),
+          })
+          if (!res.ok) return null
+          const { translated } = await res.json() as { translated: string | null }
+          return translated
+        } catch { return null }
+      },
+    } : {}),
+    ...(opts.showChatList ? {
+      async onListChats() {
+        const base = httpBaseFromWsUrl(opts.url)
+        try {
+          const res = await fetch(`${base}/conversations/mine?profileId=${encodeURIComponent(opts.profileId)}`, {
+            headers: { authorization: `Bearer ${token}` },
+          })
+          if (!res.ok) return []
+          const data = await res.json() as { conversations?: ChatListEntry[] }
+          return data.conversations ?? []
+        } catch { return [] }
+      },
+      onSwitchChat(entry: ChatListEntry) {
+        currentHandle?.close()
+        opts.el.replaceChildren()  // Renderer appends fresh DOM into the same host element
+        const { subjectId: _drop, ...rest } = opts
+        currentHandle = mount({ ...rest, token, ...(entry.subjectId ? { subjectId: entry.subjectId } : {}) })
+      },
+    } : {}),
+  }, {
+    ...(opts.subject ? { subject: opts.subject } : {}),
+    ...(opts.quickReplies ? { quickReplies: opts.quickReplies } : {}),
+    ...(opts.accent ? { accent: opts.accent } : {}),
+  })
+
+  const openFrame: Extract<ClientFrame, { type: 'open' }> = {
+    type: 'open', profileId: opts.profileId as never,
+    ...(opts.subjectId ? { subjectId: opts.subjectId as never } : {}),
+  }
+
+  conn = new ConnectionManager({
+    url: opts.url, token, open: openFrame,
+    getCursor: () => store.highestSeq(),
+    onStatusChange: (s) => renderer.setConnStatus(s),
+    onFrame(frame) {
+      if (frame.type === 'opened') {
+        const isFirstOpen = cid === undefined
+        cid = frame.conversation.id
+        if (!outboxRestored) {
+          outboxRestored = true
+          // Re-send anything that didn't get acknowledged before a reload/drop.
+          // Each item is also already showing as a 'pending' bubble (restored below).
+          for (const item of outbox.load()) {
+            conn.send({ type: 'send', conversationId: cid, clientMsgId: item.clientMsgId, content: item.content })
+          }
+        }
+        // Restore chat history via REST, independent of the WS sync/history
+        // frames. Shared implementation with the dashboard's agent view —
+        // see history.ts.
+        if (isFirstOpen) {
+          void restoreHistory(opts.url, token, cid, store, renderer)
+        }
+      }
+
+      if (frame.type === 'ack') outbox.remove(frame.clientMsgId)
+
+      // X3DH: handle incoming prekey bundle response
+      if (frame.type === 'prekeyBundle') {
+        if (frame.bundle) {
+          x3dhBundleFetched = true
+          void e2e.x3dhSendTo(frame.bundle).then((x3dhInit) => {
+            // Drain any X3DH-pending messages with the derived key.
+            const toSend = [...pending.splice(0), ...x3dhPending.splice(0)]
+            for (const p of toSend) sendSealedX3DH(p.clientMsgId, p.text, x3dhInit)
+            renderer.render(store)
+          })
+        }
+        // If no bundle, peer has no prekeys; fall back to live ECDH queue
+        return
+      }
+
+      // X3DH recipient: detect init message in incoming encrypted messages
+      if (frame.type === 'message' && store.e2e) {
+        const x3dh = extractX3DHInit(frame.message.content)
+        if (x3dh && !e2e.ready) {
+          void e2e.x3dhReceiveFrom(x3dh.x3dhIK, x3dh.x3dhEK, x3dh.x3dhSPK).then(async () => {
+            // Now decrypt the message that carried the init
+            await e2e.openFrame(frame)
+            store.apply(frame)
+            renderer.render(store)
+          })
+          return
+        }
+      }
+
+      if (frame.type === 'peerkey') {
+        void e2e.onPeerKey(frame.key).then(() => { flushPending(); renderer.render(store) })
+        return
+      }
+      void (async () => {
+        if (store.e2e) await e2e.openFrame(frame)
+        store.apply(frame)
+        // Trigger badge + sound for new messages from others
+        if (frame.type === 'message' && frame.message.senderId !== (token as never) && !frame.message.internal) {
+          addUnread()
+          playSound()
+        }
+        // Once we learn the room is E2E, run the key handshake exactly once.
+        if (store.e2e && cid && !e2eStarted) {
+          e2eStarted = true
+          // Upload our prekey bundle for async E2E support.
+          const prekeyPayload = await e2e.initX3DH()
+          conn.send({ type: 'uploadPrekeys', ...prekeyPayload })
+          // Also do live ECDH handshake in case peer is already online.
+          const liveKey = await e2e.begin()
+          conn.send({ type: 'pubkey', conversationId: cid, key: liveKey })
+        }
+        renderer.render(store)
+      })()
+    },
+  })
+  conn.connect()
+  // Show restored 'pending' bubbles (if any) immediately, before the socket opens.
+  renderer.render(store)
+
+  currentHandle = { close: () => { conn.close(); launcherEl?.remove() } }
+  return currentHandle
+}
+
+export { ChatStore } from './store.js'
+export { ConnectionManager } from './connection.js'
+export { Renderer, type ChatListEntry } from './renderer.js'
+export { asConversationId }
+export { E2ESession, extractX3DHInit, type X3DHBundle } from './e2e.js'
+export { PersistentOutbox, type OutboxItem } from './outbox.js'
+export { restoreHistory, httpBaseFromWsUrl } from './history.js'
+

package/src/outbox.ts

@@ -0,0 +1,58 @@
+import type { MessageContent } from './protocol/index.js'
+
+export interface OutboxItem {
+  clientMsgId: string
+  content:     MessageContent
+  ts:          number
+}
+
+const MAX_ITEMS = 200          // cap so a long outage can't grow storage unboundedly
+const MAX_AGE_MS = 7 * 86_400_000  // drop anything older than 7 days on load
+
+/** Persists not-yet-acknowledged outgoing messages to localStorage, keyed by
+ *  guest token, so a page reload during a connectivity drop doesn't silently
+ *  lose what the user typed (the "WhatsApp" guarantee: your message is queued
+ *  until it's confirmed sent, even across app restarts). */
+export class PersistentOutbox {
+  private readonly key: string
+
+  constructor(token: string) {
+    this.key = `ocw_outbox_${token}`
+  }
+
+  /** All pending items, oldest first, with stale (>7d) entries dropped. */
+  load(): OutboxItem[] {
+    try {
+      const raw = localStorage.getItem(this.key)
+      if (!raw) return []
+      const items = JSON.parse(raw) as OutboxItem[]
+      const cutoff = Date.now() - MAX_AGE_MS
+      const fresh = items.filter(i => i.ts >= cutoff)
+      if (fresh.length !== items.length) this.save(fresh)
+      return fresh
+    } catch {
+      return []
+    }
+  }
+
+  add(item: OutboxItem): void {
+    try {
+      const items = this.load()
+      items.push(item)
+      // Evict oldest when full — matches the in-memory ConnectionManager outbox policy.
+      this.save(items.length > MAX_ITEMS ? items.slice(items.length - MAX_ITEMS) : items)
+    } catch { /* localStorage unavailable (private mode, quota) — best-effort only */ }
+  }
+
+  /** Remove an item once it's been acknowledged by the server. */
+  remove(clientMsgId: string): void {
+    try {
+      const items = this.load().filter(i => i.clientMsgId !== clientMsgId)
+      this.save(items)
+    } catch { /* best-effort */ }
+  }
+
+  private save(items: OutboxItem[]): void {
+    try { localStorage.setItem(this.key, JSON.stringify(items)) } catch { /* quota exceeded — drop silently */ }
+  }
+}