clay-server 5.2.0-beta.8 → 5.2.0

package/lib/public/modules/input.js

@@ -8,6 +8,7 @@ import { setRewindMode, isRewindMode } from './rewind.js';
 import { renderPicker as renderContextPicker } from './context-sources.js';
 import { checkForMention, showMentionMenu, hideMentionMenu, isMentionMenuVisible, mentionMenuKeydown, setMentionAtIdx, parseMentionFromInput, clearMentionState, stickyReapplyMention, sendMention, sendUserMention, renderMentionUser, renderUserMention, removeMentionChip } from './mention.js';
 import { store } from './store.js';
+import { sessionCallback, paneMessageBinding, samePaneBinding } from './pane-binding.js';
 import { sendAcknowledgedMessage } from './message-delivery.js';
 import { mateAvatarUrl } from './avatar.js';
 import { tuiIsActive, tuiSubmitText } from './session-tui-view.js';
@@ -122,6 +123,9 @@ function showPreThinkingForTurn() {
 
 // --- Send ---
 export function sendMessage() {
+  if (store.get('deferredSessionSwitch') || store.get('panePendingBinding') || store.get('paneSuspended')) return;
+  if (store.get('paneCommittedBinding') && !store.get('paneReady')) return;
+  var actionBinding = paneMessageBinding();
   if (store.get('contextualWriterSuspended')) return;
   if (ctx && requestRecordedSend(ctx.inputEl, sendMessage)) return;
   stopSTT();
@@ -346,6 +350,7 @@ export function sendMessage() {
     store.set({ pendingScheduleAdmissions: admissions, pendingScheduleAdmission: admissions[scheduleRequestId] });
     ctx.ws.send(JSON.stringify({
       type: "schedule_message", requestId: scheduleRequestId,
+      paneBinding: actionBinding || undefined,
       projectSlug: scheduleContext.projectSlug, sessionId: scheduleContext.sessionId, accountId: scheduleContext.accountId,
       text: text || "", images: images, pastes: pastes, resetsAt: resetsAt,
     }));
@@ -354,6 +359,7 @@ export function sendMessage() {
 
   var screenReference = contextualScreenReference();
   var payload = { type: "message", text: text || "" };
+  if (actionBinding) payload.paneBinding = actionBinding;
   if (screenReference) payload.contextualSnapshot = screenReference;
   if (images.length > 0) {
     payload.images = images;
@@ -440,6 +446,7 @@ export function sendTextMessage(text) {
 export function sendShellResultToAgent(msg) {
   if (!ctx || !ctx.connected || !msg || msg.error || !msg.command) return false;
   if (String(msg.sessionId) !== String(store.get("activeSessionId"))) return false;
+  if (store.get('paneCommittedBinding') && !samePaneBinding(msg.paneActivation, store.get('paneCommittedBinding'))) return false;
   var payload = {
     type: "message",
     text: "$ " + msg.command,
@@ -447,7 +454,8 @@ export function sendShellResultToAgent(msg) {
   };
   var selectedVendor = store.get("currentVendor") || null;
   if (selectedVendor) payload.vendor = selectedVendor;
-  ctx.ws.send(JSON.stringify(payload));
+  if (msg.paneActivation) payload.paneBinding = msg.paneActivation;
+  if (ctx.ws.send(JSON.stringify(payload)) === false) return false;
   commitVendorForTurn();
   showPreThinkingForTurn();
   return true;
@@ -543,9 +551,17 @@ function removePendingImage(idx) {
 }
 
 // Move composer ownership between two authenticated views of the same session.
+export function composerDepartureReason() {
+  if (uploadingCount) return 'Wait for attachments to finish uploading before changing views.';
+  if (store.get('speechActive') || ctx && hasRecordedSpeechFor(ctx.inputEl)) return 'Finish or discard the voice recording before changing views.';
+  var retry = store.get('speechRetry');
+  if (retry && ctx && retry.input === ctx.inputEl) return 'Retry or discard the voice recording before changing views.';
+  return '';
+}
 export function takeComposerDraft() {
-  if (uploadingCount) throw new Error('Wait for attachments to finish uploading before opening Clay.');
-  if (store.get('speechActive') || hasRecordedSpeechFor(ctx.inputEl)) throw new Error('Finish or discard the voice recording before changing Clay views.');
+  var reason = composerDepartureReason();
+  if (reason) throw new Error(reason);
+  if (document.dispatchEvent) document.dispatchEvent(new CustomEvent('clay-composer-handoff'));
   var input = ctx.inputEl;
   var draft = { text: input.value, start: input.selectionStart, end: input.selectionEnd, direction: input.selectionDirection, images: pendingImages, pastes: pendingPastes, files: pendingFiles, delay: scheduleDelayMs };
   input.value = '';
@@ -585,14 +601,14 @@ function pastePreview(text) {
 }
 
 function editPendingPaste(idx) {
-  showPasteModal(pendingPastes[idx].text, function (text) {
+  showPasteModal(pendingPastes[idx].text, sessionCallback(function (text) {
     if (!text) {
       removePendingPaste(idx);
       return;
     }
     pendingPastes[idx] = { text: text, preview: pastePreview(text) };
     renderInputPreviews();
-  });
+  }));
 }
 
 function removePendingFile(idx) {
@@ -726,6 +742,7 @@ function uploadFile(file) {
     return;
   }
   uploadingCount++;
+  store.set({ composerUploadingCount: uploadingCount });
   renderInputPreviews();
   var reader = new FileReader();
   reader.onload = function (ev) {
@@ -738,12 +755,14 @@ function uploadFile(file) {
     xhr.setRequestHeader("Content-Type", "application/json");
     xhr.onload = function () {
       uploadingCount--;
+      store.set({ composerUploadingCount: uploadingCount });
       if (xhr.status === 200) {
         try {
           var resp = JSON.parse(xhr.responseText);
           pendingFiles.push({ name: resp.name || uploadName, path: resp.path });
-        } catch (e) {}
+        } catch (e) { showToast('Upload response could not be read: ' + uploadName + '. Your draft is preserved.', 'error'); }
       } else {
+        showToast('Upload failed: ' + uploadName + '. Your draft is preserved.', 'error');
         if (ctx.addSystemMessage) ctx.addSystemMessage("Upload failed: " + uploadName, true);
       }
       renderInputPreviews();
@@ -753,6 +772,8 @@ function uploadFile(file) {
     };
     xhr.onerror = function () {
       uploadingCount--;
+      store.set({ composerUploadingCount: uploadingCount });
+      showToast('Upload failed: ' + uploadName + '. Your draft is preserved.', 'error');
       if (ctx.addSystemMessage) ctx.addSystemMessage("Upload failed: " + uploadName, true);
       renderInputPreviews();
       if (ctx.processing && ctx.setSendBtnMode) {
@@ -761,6 +782,7 @@ function uploadFile(file) {
     };
     xhr.send(JSON.stringify({ name: uploadName, data: b64 }));
   };
+  reader.onerror = function () { uploadingCount--; store.set({ composerUploadingCount: uploadingCount }); renderInputPreviews(); showToast('Attachment could not be read. Your draft is preserved.', 'error'); };
   reader.readAsDataURL(file);
 }
 
@@ -772,7 +794,14 @@ function readImageBlob(blob) {
     uploadFile(blob);
     return;
   }
+  uploadingCount++; store.set({ composerUploadingCount: uploadingCount });
+  var completed = false;
+  function finish() {
+    if (completed) return; completed = true; uploadingCount--;
+    store.set({ composerUploadingCount: uploadingCount }); renderInputPreviews();
+  }
   var reader = new FileReader();
+  reader.onerror = function () { finish(); showToast('Image could not be read. Your draft is preserved.', 'error'); };
   reader.onload = function (ev) {
     var dataUrl = ev.target.result;
     // Check base64 payload size (~3/4 of base64 length)
@@ -781,7 +810,7 @@ function readImageBlob(blob) {
     var estimatedBytes = b64.length * 0.75;
 
     if (estimatedBytes <= MAX_IMAGE_BYTES) {
-      addPendingImage(dataUrl);
+      addPendingImage(dataUrl); finish();
       return;
     }
 
@@ -799,8 +828,9 @@ function readImageBlob(blob) {
       var cx = canvas.getContext("2d");
       cx.drawImage(img, 0, 0, nw, nh);
       var resized = canvas.toDataURL("image/jpeg", RESIZE_QUALITY);
-      addPendingImage(resized);
+      addPendingImage(resized); finish();
     };
+    img.onerror = function () { finish(); showToast('Image could not be loaded. Your draft is preserved.', 'error'); };
     img.src = dataUrl;
   };
   reader.readAsDataURL(blob);
@@ -869,7 +899,9 @@ function sendInputSync() {
     if (dk) ctx.ws.send(JSON.stringify({ type: "dm_typing", dmKey: dk, typing: hasText }));
     return;
   }
-  ctx.ws.send(JSON.stringify({ type: "input_sync", text: ctx.inputEl.value }));
+  var speech = store.get('speechActive');
+  ctx.ws.send(JSON.stringify({ type: "input_sync", text: ctx.inputEl.value,
+    paneBinding: speech && speech.writing ? speech.paneBinding || undefined : undefined }));
 }
 
 export function handleInputSync(text) {
@@ -893,7 +925,7 @@ function createFileInput(accept, capture, multiple) {
   input.style.display = "none";
   document.body.appendChild(input);
 
-  input.addEventListener("change", function () {
+  var selectFiles = sessionCallback(function () {
     if (input.files) {
       for (var i = 0; i < input.files.length; i++) {
         if (input.files[i].type.indexOf("image/") === 0) {
@@ -903,6 +935,9 @@ function createFileInput(accept, capture, multiple) {
         }
       }
     }
+  });
+  input.addEventListener("change", function () {
+    selectFiles();
     document.body.removeChild(input);
   });
 
@@ -991,6 +1026,14 @@ export function initInput(_ctx) {
     }
   }
 
+  document.addEventListener('clay-composer-handoff', function () {
+    if (scheduleInlineInput) {
+      var minutes = parseInt(scheduleInlineInput.value, 10);
+      if (minutes >= 1 && minutes <= 1440) setScheduleDelayMs(minutes * 60000);
+    }
+    collapseScheduleBtn();
+  });
+
   function setScheduleDelay(ms) {
     scheduleDelayMs = ms;
     if (!scheduleBtn) return;
@@ -1020,7 +1063,7 @@ export function initInput(_ctx) {
     scheduleInlineInput.className = "schedule-inline-input";
     scheduleBtn.appendChild(scheduleInlineInput);
 
-    setTimeout(function () { scheduleInlineInput.focus(); }, 0);
+    setTimeout(sessionCallback(function () { if (scheduleInlineInput) scheduleInlineInput.focus(); }), 0);
 
     scheduleInlineInput.addEventListener("click", function (e) { e.stopPropagation(); });
     scheduleInlineInput.addEventListener("keydown", function (e) {
@@ -1039,6 +1082,7 @@ export function initInput(_ctx) {
 
     // Close on outside click
     setTimeout(function () {
+      if (!scheduleInlineInput) return;
       scheduleOutsideHandler = function (ev) {
         if (!scheduleBtn.contains(ev.target)) {
           if (scheduleInlineInput) {

package/lib/public/modules/mate-loading-scene.js

@@ -0,0 +1,17 @@
+// Decorative opening state; conversation readiness remains with its host.
+export function mateLoadingMarkup() {
+  return '<div data-clay-loading class="mate-loading" role="status" aria-live="polite">' +
+    '<div class="mate-loading-scene" aria-hidden="true">' +
+    '<img class="mate-loading-avatar" alt="">' +
+    '<img class="mate-loading-desk" src="/welcome-art/conversation-desk.png" alt="" decoding="async">' +
+    '</div><p class="mate-loading-label"></p>' +
+    '<div class="mate-loading-dots" aria-hidden="true"><span></span><span></span><span></span></div></div>';
+}
+
+export function updateMateLoadingScene(element, name, avatar) {
+  var image = element.querySelector('.mate-loading-avatar');
+  if (image.getAttribute('src') !== avatar) image.setAttribute('src', avatar);
+  var label = element.querySelector('.mate-loading-label');
+  var text = 'Getting ready with ' + name;
+  if (label.textContent !== text) label.textContent = text;
+}

package/lib/public/modules/message-delivery.js

@@ -2,6 +2,7 @@
 
 import { store } from './store.js';
 import { getWs } from './ws-ref.js';
+import { paneMessageBinding } from './pane-binding.js';
 
 var ACK_TIMEOUT_MS = 5000;
 var ACK_RETRY_LIMIT = 3;
@@ -152,7 +153,7 @@ function transmit(entry, automatic) {
   }
   socketRefs[entry.payload.clientMessageId] = socket;
   try {
-    socket.send(JSON.stringify(entry.payload));
+    if (socket.send(JSON.stringify(entry.payload)) === false) { markUnconfirmed(entry); return false; }
     armAckTimer(entry.payload.clientMessageId, socket);
     return true;
   } catch (e) {
@@ -163,6 +164,8 @@ function transmit(entry, automatic) {
 
 export function sendAcknowledgedMessage(payload) {
   var nextPayload = Object.assign({}, payload, { clientMessageId: createClientMessageId() });
+  var binding = paneMessageBinding();
+  if (binding && !nextPayload.paneBinding) nextPayload.paneBinding = binding;
   var entry = {
     projectSlug: store.get('currentSlug'),
     sessionId: store.get('activeSessionId'),
@@ -193,7 +196,12 @@ export function sendAcknowledgedMessage(payload) {
 export function retryPendingMessage(clientMessageId) {
   var entry = pendingEntry(clientMessageId);
   if (!matchesActivatedContext(entry) || hasKnownCliMismatch(entry)) return false;
-  var retryEntry = Object.assign({}, entry, { attempts: 0, status: "pending" });
+  // An explicit Retry in the same durable conversation may use its new live
+  // binding. Automatic retry retains the original action binding and refuses.
+  var payload = Object.assign({}, entry.payload);
+  var binding = paneMessageBinding();
+  if (binding) payload.paneBinding = binding;
+  var retryEntry = Object.assign({}, entry, { payload: payload, attempts: 0, status: "pending" });
   replacePending(pendingMessages().map(function (candidate) {
     return candidate.payload.clientMessageId === clientMessageId ? retryEntry : candidate;
   }));

package/lib/public/modules/model-picker.js

@@ -50,6 +50,8 @@ export function setupModelPicker() {
 
 export function resetModelPickerState() {
   clearRequestTimer();
+  if (configPopover) configPopover.classList.add('hidden');
+  if (configChip) configChip.classList.remove('active');
   store.set({
     modelListVendor: "",
     modelListStatus: "idle",

package/lib/public/modules/pane-activation.js

@@ -0,0 +1,214 @@
+import { store } from './store.js';
+import { getWs } from './ws-ref.js';
+import { getCachedSessions } from './sidebar-sessions.js';
+import { takeComposerDraft, restoreComposerDraft } from './input.js';
+import { resetHistoryReplayBatch } from './history-replay-batch.js';
+import { updateContextPanel } from './app-panels.js';
+import { paneTarget, samePaneBinding, samePaneTarget } from './pane-binding.js';
+
+function enabled() {
+  return store.get('paneMode') && !store.get('paneActivationUnsupported') && !store.get('activeProjectMateId') && !/^\/p\/mate-/.test(location.pathname) && !new URLSearchParams(location.search).has('contextual') && window.parent !== window;
+}
+function block(value) {
+  var app = document.getElementById('app');
+  if (app) app.inert = value;
+  document.documentElement.dataset.paneReady = value ? 'false' : 'true';
+}
+function draftKey() { return String(store.get('myUserId')) + ':' + store.get('sessionOriginId'); }
+function clearDeadline() {
+  if (store.get('paneActivationTimer')) clearTimeout(store.get('paneActivationTimer'));
+  store.set({ paneActivationTimer: null });
+}
+function failed(requestId) {
+  var pending = store.get('panePendingBinding');
+  if (!pending || requestId !== pending.requestId) return;
+  clearDeadline();
+  store.set({ paneReady: false, panePendingBinding: null });
+  block(true);
+  var frame = window.frameElement;
+  if (frame) frame.dispatchEvent(new window.parent.CustomEvent('clay-pane-activation-failed'));
+}
+
+// Claim ordinary initial pins before the legacy session-list handler runs.
+// Authentication, list and group metadata can arrive in either order; the
+// subscription retries when those authoritative prerequisites become ready.
+export function primePaneSession() {
+  if (!enabled() || !window.frameElement || !window.frameElement.clayPane) return false;
+  var id = store.get('paneSessionId');
+  var session = (getCachedSessions() || []).find(function (item) { return item.id === id; });
+  if (!session || session.isMate || (session.runtimeMode || session.mode || 'gui') !== 'gui' || session.tuiSuspended) return false;
+  activatePaneSession(id);
+  return true;
+}
+
+export function activatePaneSession(id, force, expectedTarget) {
+  var state = store.snap(), ws = getWs();
+  if (state.authIdentityLoaded === false) return false;
+  if (state.isMultiUserMode && !state.myUserId) return false;
+  if (!enabled() || !state.connected || !ws || ws.readyState !== 1 || state.splitGroupsProjectSlug !== state.currentSlug) return false;
+  var target = paneTarget(state, getCachedSessions(), id);
+  if (!target) return false;
+  if (expectedTarget && !samePaneTarget(target, expectedTarget)) return false;
+  var sourceFrame = window.frameElement;
+  if (!expectedTarget && sourceFrame && Number(sourceFrame.dataset && sourceFrame.dataset.sessionId) === id && sourceFrame.dataset.sessionOriginId && sourceFrame.dataset.sessionOriginId !== target.sessionOriginId) return false;
+  var old = state.paneCommittedBinding, pending = state.panePendingBinding;
+  if (!force && !state.paneSuspended && samePaneTarget(pending || old, target)) return true;
+  if (!pending && state.sessionOriginId) {
+    var draft;
+    try { draft = takeComposerDraft(); } catch (error) { return false; }
+    var drafts = Object.assign({}, state.paneRichDrafts || {});
+    drafts[draftKey()] = draft;
+    store.set({ paneRichDrafts: drafts });
+  }
+  clearDeadline();
+  resetHistoryReplayBatch();
+  var generation = (store.get('paneActivationGeneration') || 0) + 1;
+  target = Object.assign({}, target, { generation: generation, requestId: 'pane-' + generation + '-' + Math.random().toString(36).slice(2, 12) });
+  var path = new URL(store.get('wsPath'), location.origin);
+  path.searchParams.set('session', String(id));
+  store.set({ paneActivationGeneration: generation, panePendingBinding: target, paneReady: false, paneSuspended: false,
+    paneSessionId: id, panePinPending: false, wsPath: path.pathname + path.search });
+  block(true);
+  store.set({ paneActivationTimer: setTimeout(function () { failed(target.requestId); }, 12000) });
+  ws.send(JSON.stringify({ type: 'switch_session', id: id, paneActivation: target }));
+  return true;
+}
+
+// Runs before replay batching, so an obsolete history_meta cannot open a batch
+// that later consumes destination messages.
+export function filterPaneActivation(message) {
+  if (!enabled()) return false;
+  var pending = store.get('panePendingBinding'), committed = store.get('paneCommittedBinding');
+  if (message.type === 'pane_activation_rejected') { failed(message.requestId); return true; }
+  if (!pending && !committed) return !!message.paneActivation;
+  if (['session_list', 'split_groups', 'session_presence', 'pong', 'account_auth_required', 'project_removed', 'project_access_revoked'].indexOf(message.type) >= 0 && !message.paneActivation) return false;
+  var expected = pending || committed;
+  if (!samePaneBinding(expected, message.paneActivation)) return true;
+  if (message.type === 'pane_activation_started') return true;
+  if (message.type === 'pane_activation_snapshot_done') {
+    if (!pending) return true;
+    var draft = (store.get('paneRichDrafts') || {})[String(store.get('myUserId')) + ':' + expected.sessionOriginId];
+    restoreComposerDraft(draft || { text: '', start: 0, end: 0 });
+    function paint() {
+      if (store.get('panePendingBinding') !== expected || !store.get('connected') || store.get('paneSuspended')) return;
+      var current = paneTarget(store.snap(), getCachedSessions(), expected.sessionId);
+      var messages = document.getElementById('messages');
+      if (!samePaneTarget(current, expected) ||
+        store.get('activeSessionId') !== expected.sessionId || store.get('sessionOriginId') !== expected.sessionOriginId || store.get('replayingHistory') ||
+        !messages || messages.dataset.controlSessionId !== String(expected.sessionId) || messages.dataset.controlSessionOrigin !== expected.sessionOriginId) { failed(expected.requestId); return; }
+      clearDeadline();
+      store.set({ paneCommittedBinding: expected, panePendingBinding: null, paneReady: true });
+      block(false);
+      var frame = window.frameElement;
+      if (frame) frame.dispatchEvent(new window.parent.CustomEvent('clay-pane-ready'));
+      updateContextPanel();
+    }
+    requestAnimationFrame(function () { requestAnimationFrame(paint); });
+    return true;
+  }
+  return false;
+}
+
+export function paneOutgoing(data) {
+  var message;
+  try { message = JSON.parse(data); } catch (error) { return null; }
+  if (['ping', 'pong', 'clay_ui_ready'].indexOf(message.type) >= 0) return data;
+  if (store.get('deferredSessionSwitch') && store.get('deferredSessionSwitch').draining) return null;
+  if (message.type === 'switch_session') {
+    var entry = store.get('pendingSessionEntryNavigation');
+    if (entry && entry.projectSlug === store.get('currentSlug') && String(entry.sessionId) !== String(message.id)) store.set({ pendingSessionEntryNavigation: null });
+    if (enabled() && (store.get('panePendingBinding') || store.get('paneCommittedBinding')) && !message.paneActivation) return null;
+    return data;
+  }
+  if (store.get('deferredSessionSwitch')) {
+    var source = store.get('deferredSessionSwitch');
+    if (source.draining) return null;
+    if (message.type === 'stop') return JSON.stringify(Object.assign({}, message, { sessionId: source.sessionId, sessionOriginId: source.origin }));
+    return null;
+  }
+  if (!enabled()) return data;
+  var binding = store.get('paneCommittedBinding');
+  if (store.get('panePendingBinding') || store.get('paneSuspended') || binding && !store.get('paneReady')) return null;
+  if (!binding) return ['stop', 'user_message', 'permission_response', 'ask_user_response', 'elicitation_response', 'user_dialog_response', 'input_sync'].indexOf(message.type) >= 0 ? null : data;
+  if (message.paneBinding && !samePaneBinding(binding, message.paneBinding)) return null;
+  var gesture = (store.get('paneActionEvents') || []).find(function (entry) { return entry.event.isTrusted && entry.event.eventPhase && samePaneBinding(entry.binding, binding); });
+  var action = store.get('paneCallbackBinding') || gesture && gesture.binding;
+  var read = /^(get_|list_)|(_get|_list|_options)$/.test(message.type) || message.type === 'load_more_history';
+  if (!message.paneBinding && !read && !samePaneBinding(action, binding)) return null;
+  return JSON.stringify(Object.assign({}, message, { paneBinding: message.paneBinding || action || binding }));
+}
+
+export function refreshPaneActivation() {
+  if (!enabled()) return;
+  var binding = store.get('panePendingBinding') || store.get('paneCommittedBinding');
+  if (!binding) return;
+  var current = paneTarget(store.snap(), getCachedSessions(), binding.sessionId);
+  if (samePaneTarget(current, binding)) return;
+  if (store.get('panePendingBinding')) failed(binding.requestId);
+  else { store.set({ paneReady: false }); block(true); }
+}
+
+export function initPaneActivation() {
+  if (!enabled() || !window.frameElement) return;
+  var frame = window.frameElement;
+  var latestId = Number(frame.dataset && (frame.dataset.requestedSessionId || frame.dataset.sessionId));
+  if (Number.isSafeInteger(latestId) && latestId > 0 && frame.dataset.projectSlug === store.get('currentSlug')) {
+    var latestPath = new URL(store.get('wsPath'), location.origin);
+    latestPath.searchParams.set('session', String(latestId));
+    store.set({ paneSessionId: latestId, panePinPending: true, wsPath: latestPath.pathname + latestPath.search });
+  }
+  block(true);
+  frame.clayPane = {
+    source: window, document: document,
+    identity: function () {
+      var binding = store.get('paneCommittedBinding');
+      return binding && { ownerId: binding.viewerId, projectSlug: binding.projectSlug, sessionId: binding.sessionId,
+        binding: binding, ready: store.get('connected') && store.get('paneReady') && !store.get('paneSuspended') };
+    },
+    activate: activatePaneSession,
+    checkDraft: function () { if (!store.get('panePendingBinding')) { var draft = takeComposerDraft(); restoreComposerDraft(draft); } },
+    suspend: function () { store.set({ paneSuspended: true, paneReady: false }); block(true); },
+  };
+  // A pointer that began on the previous conversation cannot become a Stop or
+  // approval click on the replacement conversation after hydration.
+  document.addEventListener('pointerdown', function () { store.set({ panePointerBinding: store.get('paneCommittedBinding') }); }, true);
+  document.addEventListener('click', function (event) {
+    if (store.get('paneSuspended') || !store.get('paneReady') && store.get('panePendingBinding') || event.detail && store.get('panePointerBinding') !== store.get('paneCommittedBinding')) {
+      event.preventDefault(); event.stopImmediatePropagation();
+    }
+  }, true);
+  ['click', 'input', 'change', 'keydown', 'keyup', 'submit', 'blur'].forEach(function (name) {
+    document.addEventListener(name, function (event) {
+      var keys = store.get('paneHeldKeys') || {};
+      var binding = store.get('paneCommittedBinding');
+      var previousKey = keys[event.code || event.key];
+      var staleKey = (name === 'keyup' || name === 'keydown' && event.repeat) && previousKey && !samePaneBinding(previousKey, binding);
+      if (name === 'keydown' && !event.repeat) keys[event.code || event.key] = binding;
+      if (name === 'keyup') delete keys[event.code || event.key];
+      if (staleKey || store.get('panePendingBinding') || store.get('paneSuspended') || !store.get('paneReady')) {
+        event.preventDefault(); event.stopImmediatePropagation(); return;
+      }
+      var events = (store.get('paneActionEvents') || []).filter(function (entry) { return entry.event.eventPhase; });
+      events.push({ event: event, binding: binding });
+      store.set({ paneHeldKeys: keys, paneActionEvents: events });
+    }, true);
+  });
+  store.subscribe(function (state, previous) {
+    if (state.activeSessionMode === 'tui' && previous.activeSessionMode !== 'tui') {
+      delete frame.clayPane; store.set({ paneActivationUnsupported: true }); block(false); return;
+    }
+    if (!state.connected && previous.connected) {
+      clearDeadline();
+      store.set({ paneReady: false, panePendingBinding: null, paneCommittedBinding: null }); block(true);
+    }
+    if (state.connected && (state.splitGroups !== previous.splitGroups || state.splitGroupsProjectSlug !== previous.splitGroupsProjectSlug || state.paneBindingSessions !== previous.paneBindingSessions || state.authIdentityLoaded !== previous.authIdentityLoaded || state.myUserId !== previous.myUserId || state.activeSessionId !== previous.activeSessionId || state.connected !== previous.connected)) {
+      queueMicrotask(function () {
+        refreshPaneActivation();
+        if (!store.get('panePendingBinding') && !store.get('paneSuspended')) {
+          if (store.get('panePinPending')) primePaneSession();
+          else if (store.get('activeSessionId') === store.get('paneSessionId')) activatePaneSession(store.get('paneSessionId'));
+        }
+      });
+    }
+  });
+}

package/lib/public/modules/pane-appearance-bridge.js

@@ -0,0 +1,59 @@
+// Live appearance sync between the app shell and its pane iframes (split
+// Driver/Worker panes and the contextual Mate window). Each iframe runs its own
+// theme module and only reads the persisted preference at load, so the shell
+// pushes the applied appearance down on every change and when a frame loads.
+// Same-origin only, shell to child only; nothing is saved from either side.
+
+import { store } from './store.js';
+import { onThemeChange, getAppearanceSnapshot, applyExternalAppearance } from './theme.js';
+
+var ID = /^[a-zA-Z0-9_-]{1,120}$/;
+
+function paneFrames() {
+  return Array.prototype.filter.call(document.querySelectorAll('iframe'), function (frame) {
+    try { var url = new URL(frame.src, window.location.href); return url.origin === window.location.origin && url.searchParams.get('pane') === '1'; }
+    catch (error) { return false; }
+  });
+}
+
+function push(frame) {
+  var snapshot = getAppearanceSnapshot();
+  try { if (frame.contentWindow) frame.contentWindow.postMessage({ type: 'clay-appearance', snapshot: snapshot }, window.location.origin); } catch (error) {}
+}
+
+function isId(value) { return typeof value === 'string' && ID.test(value); }
+function isIdOrNull(value) { return value === null || isId(value); }
+
+// Exact shape only: strings or null, never coerced values.
+function validSnapshot(value) {
+  var pref = value && typeof value === 'object' ? value.preference : null;
+  if (!pref || typeof pref !== 'object' || !isId(value.themeId)) return false;
+  if (value.userId !== null && (typeof value.userId !== 'string' || !value.userId || value.userId.length > 200)) return false;
+  if (typeof pref.configured !== 'boolean') return false;
+  if (pref.mode !== null && pref.mode !== 'light' && pref.mode !== 'dark') return false;
+  return isIdOrNull(pref.theme) && isIdOrNull(pref.lightTheme) && isIdOrNull(pref.darkTheme);
+}
+
+export function initPaneAppearanceBridge() {
+  if (store.get('paneMode')) {
+    if (window.parent === window) return;
+    window.addEventListener('message', function (event) {
+      if (event.origin !== window.location.origin || event.source !== window.parent) return;
+      var msg = event.data;
+      if (!msg || msg.type !== 'clay-appearance' || !validSnapshot(msg.snapshot)) return;
+      // Once this frame knows its owner the snapshot must name exactly that owner (null is a mismatch).
+      // Before identity is known, or in solo mode without one, any well-formed snapshot applies.
+      var owner = store.get('myUserId') || null;
+      if (owner !== null && msg.snapshot.userId !== owner) return;
+      applyExternalAppearance(msg.snapshot);
+    });
+    return;
+  }
+  onThemeChange(function () { paneFrames().forEach(push); });
+  // Frames that rejected an early snapshot (identity not yet known here) get it again once it is.
+  store.subscribe(function (state, previous) { if (state.myUserId !== previous.myUserId) paneFrames().forEach(push); });
+  // A frame that finished loading may have been seeded before a pending save.
+  document.addEventListener('load', function (event) {
+    if (event.target && event.target.tagName === 'IFRAME' && paneFrames().indexOf(event.target) >= 0) push(event.target);
+  }, true);
+}

package/lib/public/modules/pane-binding.js

@@ -0,0 +1,82 @@
+import { store } from './store.js';
+import { getWs } from './ws-ref.js';
+
+export function captureSessionAction() {
+  var state = store.snap();
+  return { projectSlug: state.currentSlug, ownerId: state.myUserId, sessionId: state.activeSessionId,
+    origin: state.sessionOriginId, socket: getWs(), binding: state.paneCommittedBinding || null,
+    epoch: state.sessionActionEpoch || 0 };
+}
+
+export function sessionActionCurrent(action, draftCompletion) {
+  var state = store.snap();
+  return !!action && action.socket === getWs() && state.connected &&
+    action.projectSlug === state.currentSlug && action.ownerId === state.myUserId &&
+    action.sessionId === state.activeSessionId && action.origin === state.sessionOriginId &&
+    action.epoch === (state.sessionActionEpoch || 0) &&
+    (draftCompletion || !state.deferredSessionSwitch) && !state.panePendingBinding && !state.paneSuspended &&
+    (action.binding ? state.paneReady && samePaneBinding(action.binding, state.paneCommittedBinding) : !state.paneCommittedBinding);
+}
+
+// Capture at callback creation, never when an old callback eventually sends.
+export function sessionCallback(callback, draftCompletion) {
+  var action = captureSessionAction();
+  return function () {
+    if (!sessionActionCurrent(action, draftCompletion)) return;
+    var previous = store.get('paneCallbackBinding');
+    store.set({ paneCallbackBinding: action.binding });
+    try { return callback.apply(this, arguments); }
+    finally { store.set({ paneCallbackBinding: previous }); }
+  };
+}
+
+export function samePaneBinding(a, b) {
+  return !!a && !!b && ['requestId', 'generation', 'projectSlug', 'viewerId', 'ownerId', 'sessionId', 'sessionOriginId', 'role', 'workerGeneration', 'groupStamp', 'parentSessionOriginId'].every(function (key) { return a[key] === b[key]; });
+}
+
+export function samePaneTarget(a, b) {
+  return !!a && !!b && ['projectSlug', 'viewerId', 'ownerId', 'sessionId', 'sessionOriginId', 'role', 'workerGeneration', 'groupStamp', 'parentSessionOriginId'].every(function (key) { return a[key] === b[key]; });
+}
+
+export function paneTarget(state, sessions, id) {
+  var session = (sessions || []).find(function (item) { return item.id === id; });
+  if (!session || session.isMate || !session.sessionOriginId || (session.runtimeMode || session.mode || 'gui') !== 'gui' || session.tuiSuspended) return null;
+  var group = (state.splitGroups || []).find(function (item) { return item.members.indexOf(id) >= 0; });
+  var parent = session.sessionRole === 'worker' && sessions.find(function (item) { return item.id === session.parentSessionId; });
+  if (session.sessionRole === 'worker' && (!parent || !session.parentAvailable || !Number.isSafeInteger(session.workerGeneration) || !parent.sessionOriginId || parent.ownerId !== session.ownerId || !group || !group.pair || group.pair.driverId !== parent.id)) return null;
+  return {
+    projectSlug: state.currentSlug, viewerId: state.myUserId || null, ownerId: session.ownerId || null,
+    sessionId: session.id, sessionOriginId: session.sessionOriginId,
+    role: session.sessionRole === 'worker' ? 'worker' : 'driver', workerGeneration: session.workerGeneration || null,
+    parentSessionOriginId: parent ? parent.sessionOriginId : null,
+    groupStamp: group ? JSON.stringify({ id: group.id, members: group.members, pair: group.pair || null }) : null,
+  };
+}
+
+// Ordinary reusable panes have a live document binding; legacy/canonical frames
+// retain their existing URL and receipt checks in their own bridge paths.
+export function livePaneBinding(frame, message) {
+  if (!frame || !frame.clayPane) return false;
+  var api = frame.clayPane, live = api.identity();
+  var state = store.snap(), split = state.splitPanes;
+  var target = live && paneTarget(state, state.paneBindingSessions || [], live.sessionId);
+  return api.source === frame.contentWindow && api.document === frame.contentDocument && live && live.ready &&
+    samePaneTarget(target, live.binding) &&
+    live.ownerId === (state.myUserId || null) && live.projectSlug === state.currentSlug &&
+    split && split.panes.some(function (pane) { return pane.slug === live.projectSlug && pane.sessionId === live.sessionId; }) &&
+    (!message || samePaneBinding(live.binding, message.paneBinding));
+}
+
+export function paneMessageBinding() {
+  return store.get('paneReady') && !store.get('paneSuspended') ? store.get('paneCommittedBinding') : null;
+}
+
+export function currentPaneReview(container) {
+  if (!container || !container.paneBinding) return true;
+  return container.isConnected !== false && store.get('paneReady') && !store.get('paneSuspended') && samePaneBinding(container.paneBinding, store.get('paneCommittedBinding'));
+}
+
+export function paneCallbackCurrent(binding) {
+  var current = store.get('panePendingBinding') || store.get('paneCommittedBinding');
+  return current ? samePaneBinding(current, binding) : !binding;
+}