clay-server 5.1.1-beta.1 → 5.2.0-beta.10

package/lib/public/modules/contextual-clay-workspace.js

@@ -0,0 +1,169 @@
+import { contextualFrame, contextualMate } from './contextual-mate-identity.js';
+import { store } from './store.js';
+import { openMateWorkspace, returnFromClay } from './project-mate-navigation.js';
+import { takeComposerDraft, restoreComposerDraft, autoResize } from './input.js';
+import { showToast } from './utils.js';
+import { iconHtml, refreshIcons } from './icons.js';
+import { getHomeMateName } from './home-mate-selection.js';
+
+function bridge(mateId, sessionId) {
+  var surface = document.getElementById('contextual-clay');
+  var frame = contextualFrame(mateId, sessionId);
+  var connection = surface && frame && frame.conversation;
+  if (!connection || !contextualMate(frame.dataset.mateId) || connection.source !== frame.contentWindow) return null;
+  var identity = connection.identity();
+  return identity.ownerId === store.get('myUserId') && identity.mateId === frame.dataset.mateId ? connection : null;
+}
+function lockNative(value) {
+  ['messages', 'input-wrapper'].forEach(function (id) { var element = document.getElementById(id); if (element) element.inert = value; });
+}
+// A direct/native Mate entry also lends its composer to one pane at a time.
+export function beginContextualNativeOrigin(mate) {
+  if (store.get('currentSlug') !== 'mate-' + mate.id) return true;
+  var existing = contextualFrame(mate.id);
+  if (existing && existing.dataset.sessionId && Number(existing.dataset.sessionId) !== store.get('activeSessionId')) return true;
+  if (existing && existing.conversation && existing.conversation.identity().sessionId !== store.get('activeSessionId')) return true;
+  try {
+    var draft = takeComposerDraft();
+    store.set({ contextualNativeOrigin: { mateId: mate.id, slug: store.get('currentSlug'), sessionId: store.get('activeSessionId'), draft: draft, stage: 'waiting' } });
+    lockNative(true); return true;
+  } catch (error) { showToast(error.message, 'error'); return false; }
+}
+export function syncContextualNativeOrigin() {
+  var origin = store.get('contextualNativeOrigin'); var connection = origin && bridge(origin.mateId, origin.sessionId);
+  if (!origin || origin.stage !== 'waiting' || !connection || !connection.identity().ready || connection.identity().mateId !== origin.mateId || connection.identity().sessionId !== origin.sessionId) return;
+  store.set({ contextualNativeOrigin: Object.assign({}, origin, { draft: null, stage: 'pane' }) });
+  connection.suspend(false); connection.restore(origin.draft);
+}
+export function abandonContextualNativeOrigin(mateId) {
+  var origin = store.get('contextualNativeOrigin');
+  if (!origin || origin.mateId !== mateId) return;
+  // A removed/revoked identity cannot receive a draft or trap later navigation.
+  store.set({ contextualNativeOrigin: null }); lockNative(false);
+  showToast('This Mate conversation is no longer available.', 'warn');
+}
+export function finishContextualNativeOrigin() {
+  var origin = store.get('contextualNativeOrigin');
+  if (!origin) return true;
+  try {
+    var connection = bridge(origin.mateId, origin.sessionId);
+    var draft = origin.stage === 'waiting' ? origin.draft : connection && connection.take();
+    if (!draft) throw new Error('Wait for this Mate conversation to reconnect.');
+    if (connection) connection.suspend(true);
+    restoreComposerDraft(draft); store.set({ contextualNativeOrigin: null }); lockNative(false); return true;
+  } catch (error) { showToast(error.message, 'error'); return false; }
+}
+export function openContextualWorkspace(clay) {
+  var connection = bridge();
+  var identity = connection && connection.identity();
+  if (!contextualMate(clay.id) || !identity || identity.mateId !== clay.id || !identity.ready) { showToast('Wait for this Mate conversation to reconnect.', 'error'); return; }
+  var origin = store.get('contextualNativeOrigin');
+  if (origin && origin.mateId === clay.id && origin.sessionId === identity.sessionId) {
+    if (!finishContextualNativeOrigin()) return;
+    var existingHandoff = store.get('contextualWorkspace');
+    if (existingHandoff && existingHandoff.slug === origin.slug && existingHandoff.sessionId === origin.sessionId) { store.set({ contextualClay: { mode: 'workspace', mateId: clay.id, sessionId: origin.sessionId } }); return; }
+    var target = store.get('clayReturnTarget');
+    store.set({ contextualWorkspace: { slug: origin.slug, sessionId: origin.sessionId, stage: 'workspace', projectDraft: null, returnSlug: target && target.projectSlug, returnSessionId: target && target.sessionId }, contextualClay: { mode: 'workspace', mateId: clay.id } });
+    return;
+  }
+  if (origin && !finishContextualNativeOrigin()) return;
+  try {
+    var projectDraft = takeComposerDraft();
+    var draft;
+    try { draft = connection.take(); } catch (error) { restoreComposerDraft(projectDraft); throw error; }
+    connection.suspend(true);
+    store.set({ contextualWorkspace: { slug: 'mate-' + clay.id, sessionId: identity.sessionId, draft: draft, projectDraft: projectDraft, stage: 'opening', returnSlug: store.get('currentSlug'), returnSessionId: store.get('activeSessionId'), returnWorkspace: store.get('contextualWorkspace') }, contextualClay: { mode: 'opening', mateId: clay.id } });
+    lockNative(true);
+    openMateWorkspace(clay.id, identity.sessionId);
+  } catch (error) { showToast(error.message, 'error'); }
+}
+
+// Called by the existing return service before it changes the route/session.
+export function finishContextualWorkspace() {
+  var handoff = store.get('contextualWorkspace');
+  if (!handoff || handoff.stage === 'returning') return;
+  var connection = bridge(handoff.slug.slice(5), handoff.sessionId);
+  if (!connection) { store.set({ contextualWorkspace: null, contextualClay: { mode: 'closed' } }); lockNative(false); return true; }
+  try {
+    var draft = handoff.draft;
+    if (handoff.stage === 'workspace' && store.get('currentSlug') === handoff.slug && store.get('activeSessionId') === handoff.sessionId) draft = takeComposerDraft();
+    connection.restore(draft);
+    connection.suspend(false);
+    var presentation = store.get('contextualClay') || {};
+    var keepOverlay = presentation.mode === 'popover' && connection !== bridge();
+    store.set({ contextualWorkspace: Object.assign({}, handoff, { draft: null, stage: 'returning' }), contextualClay: keepOverlay ? presentation : Object.assign({}, presentation, { mode: 'closed' }) });
+    lockNative(true);
+    return true;
+  } catch (error) { showToast(error.message, 'error'); return false; }
+}
+
+export function handleContextualWorkspaceMessage(msg) {
+  var handoff = store.get('contextualWorkspace');
+  if (!handoff || store.get('paneMode')) return;
+  if (msg.type === 'session_switched' && handoff.stage.indexOf('workspace') === 0 && store.get('currentSlug') === handoff.slug) {
+    var saved = handoff.draft;
+    if (store.get('activeSessionId') === handoff.sessionId) saved = takeComposerDraft();
+    var exact = msg.id === handoff.sessionId;
+    store.set({ contextualWorkspace: Object.assign({}, handoff, { draft: saved, stage: exact ? 'opening' : 'workspace-other' }) });
+    if (exact) lockNative(true);
+    return;
+  }
+  if (msg.type !== 'history_done') return;
+  if (handoff.stage === 'opening' && store.get('currentSlug') === handoff.slug && store.get('activeSessionId') === handoff.sessionId) {
+    restoreComposerDraft(handoff.draft);
+    store.set({ contextualWorkspace: Object.assign({}, handoff, { draft: null, stage: 'workspace' }), contextualClay: Object.assign({}, store.get('contextualClay'), { mode: 'workspace' }) });
+    lockNative(false);
+  } else if (handoff.stage === 'returning' && (store.get('currentSlug') !== handoff.slug || store.get('activeSessionId') !== handoff.sessionId)) {
+    if (handoff.projectDraft && store.get('currentSlug') === handoff.returnSlug && store.get('activeSessionId') === handoff.returnSessionId) restoreComposerDraft(handoff.projectDraft);
+    var restored = handoff.returnWorkspace && store.get('currentSlug') === handoff.returnSlug && store.get('activeSessionId') === handoff.returnSessionId ? handoff.returnWorkspace : null;
+    store.set({ contextualWorkspace: restored, contextualClay: restored ? { mode: 'workspace', mateId: restored.slug.slice(5), sessionId: restored.sessionId } : store.get('contextualClay') });
+    lockNative(false);
+  }
+}
+export function renderContextualWorkspaceBack() {
+  var handoff = store.get('contextualWorkspace');
+  document.body.classList.toggle('contextual-clay-native', !!handoff && handoff.stage === 'workspace' && store.get('currentSlug') === handoff.slug);
+  var button = document.getElementById('contextual-workspace-back');
+  if (!button) {
+    button = document.createElement('button'); button.id = 'contextual-workspace-back'; button.type = 'button';
+    button.innerHTML = iconHtml('arrow-left') + '<span>Back to project</span>';
+    button.addEventListener('click', returnFromClay);
+    document.getElementById('header-left').prepend(button);
+    refreshIcons();
+  }
+  var returnMate = handoff && handoff.returnSlug && handoff.returnSlug.indexOf('mate-') === 0 && contextualMate(handoff.returnSlug.slice(5));
+  button.querySelector('span').textContent = returnMate ? 'Back to ' + getHomeMateName(returnMate) : 'Back to project';
+  button.hidden = !handoff || handoff.stage.indexOf('workspace') !== 0 || store.get('currentSlug') !== handoff.slug;
+}
+
+export function prepareContextualWorkspaceDeparture(slug) {
+  var origin = store.get('contextualNativeOrigin');
+  if (origin && slug !== origin.slug) {
+    if ((store.get('contextualClay') || {}).mode === 'popover') {
+      var connection = bridge(origin.mateId, origin.sessionId);
+      try {
+        if (origin.stage !== 'pane' || !connection || !connection.identity().ready) throw new Error('Wait for this Mate conversation to reconnect.');
+        // The pane keeps its composer when its former native parent changes.
+        connection.checkDraft();
+        store.set({ contextualNativeOrigin: null }); lockNative(false);
+      } catch (error) { showToast(error.message, 'error'); return false; }
+    } else if (!finishContextualNativeOrigin()) return false;
+  }
+  var handoff = store.get('contextualWorkspace');
+  if (handoff && handoff.stage.indexOf('workspace') === 0 && slug !== handoff.slug) return finishContextualWorkspace();
+}
+export function initContextualWorkspace() {
+  var width = 0;
+  new ResizeObserver(function (entries) {
+    var next = entries[0].contentRect.width;
+    if (next === width || !next || !store.get('contextualWorkspace')) return;
+    width = next; autoResize();
+  }).observe(document.getElementById('input-textarea-wrap'));
+  store.subscribe(function (value, previous) {
+    var handoff = value.contextualWorkspace;
+    if (!handoff || handoff.stage !== 'workspace' || !previous.connected || value.connected || value.currentSlug !== handoff.slug) return;
+    var draft = takeComposerDraft();
+    store.set({ contextualWorkspace: Object.assign({}, handoff, { draft: draft, stage: 'opening' }), pendingProjectSessionNavigation: { projectSlug: handoff.slug, sessionId: handoff.sessionId } });
+    lockNative(true);
+  });
+}

package/lib/public/modules/contextual-clay.js

@@ -0,0 +1,250 @@
+import { attachContextualSessionCitations } from './contextual-session-citations.js';
+import { attachContextualConversations } from './contextual-mate-sessions.js';
+import { getCachedSessions } from './sidebar-sessions.js';
+import { updateMateContext, recordMateContextSubmission } from './contextual-mate-context.js';
+import { contextualMate, contextualMateStamp, contextualFrame, contextualTrigger } from './contextual-mate-identity.js';
+import { initContextualMateHint } from './contextual-mate-hint.js';
+import { getHomeMateName } from './home-mate-selection.js';
+import { attachContextualGeometry, initContextualGeometry, positionContextualClay } from './contextual-clay-geometry.js';
+import { abandonContextualNativeOrigin, beginContextualNativeOrigin, syncContextualNativeOrigin, finishContextualNativeOrigin, openContextualWorkspace, renderContextualWorkspaceBack, initContextualWorkspace } from './contextual-clay-workspace.js';
+import { mateAvatarUrl } from './avatar.js';
+import { iconHtml, refreshIcons } from './icons.js';
+import { activateContextualMate, returnFromClay } from './project-mate-navigation.js';
+import { initContextualSession } from './contextual-clay-session.js';
+import { initClayControlActivity, clearClayControlActivity } from './clay-control-activity.js';
+// The compact pane stays mounted; native navigation transfers draft ownership.
+import { store } from './store.js';
+
+function state() { return store.get('contextualClay') || { mode: 'closed' }; }
+export function contextualClayMode() { return state().mode; }
+function host() { return document.getElementById('contextual-clay'); }
+function trigger() { return contextualTrigger(); }
+export function enterComposer() {
+  var surface = host();
+  if (!surface || surface.dataset.focusEntry !== 'true') return;
+  var frame = contextualFrame();
+  if (!frame || frame.inert || !frame.conversation || !frame.conversation.identity().ready) return;
+  var input = frame.contentDocument && frame.contentDocument.getElementById('input');
+  if (contextualClayMode() !== 'popover' || document.activeElement !== trigger()) { delete surface.dataset.focusEntry; return; }
+  if (input && !input.closest('[inert]')) { delete surface.dataset.focusEntry; input.focus({ preventScroll: true }); }
+}
+function escapePopover(event) {
+  // Run after native inner menus have had their own Escape handler.
+  queueMicrotask(function () {
+    if (event.defaultPrevented || contextualClayMode() !== 'popover') return;
+    var context = host().querySelector('details[open]');
+    if (context) { context.open = false; context.querySelector('summary').focus(); return; }
+    var focused = document.activeElement;
+    if (!host().contains(focused) && focused !== trigger()) return;
+    event.preventDefault(); dismissContextualClay(true);
+  });
+}
+
+export function dismissContextualClay(restoreFocus) {
+  if (!finishContextualNativeOrigin()) return;
+  if (contextualClayMode() === 'opening') { returnFromClay(); return; }
+  var surface = host();
+  var ownedFocus = surface && (surface.contains(document.activeElement) || document.activeElement === surface);
+  var target = store.get('clayReturnTarget');
+  var missing = target && target.projectSlug === store.get('currentSlug') && !(store.get('projectsHubList') || []).some(function (project) { return project.slug === target.projectSlug && project.contentAccess !== false; });
+  store.set({ contextualClay: Object.assign({}, state(), { mode: 'closed' }) });
+  if (missing) returnFromClay();
+  // The return context survives a temporary popover dismissal.
+  if (restoreFocus && ownedFocus && trigger()) trigger().focus({ preventScroll: true });
+}
+
+
+function render() {
+  var surface = host();
+  var mode = contextualClayMode();
+  renderContextualWorkspaceBack();
+  if (!surface) return;
+  surface.hidden = mode === 'closed' || mode === 'workspace';
+  surface.dataset.mode = mode;
+  positionContextualClay();
+  surface.querySelector('[data-clay-expand]').hidden = mode !== 'popover';
+  surface.querySelector('[data-clay-close]').hidden = mode !== 'popover' && mode !== 'opening';
+  var mate = contextualMate(state().mateId);
+  if (mate) {
+    var name = getHomeMateName(mate);
+    surface.setAttribute('aria-label', name + ' conversation');
+    surface.querySelector('strong').textContent = name;
+    var header = surface.querySelector('header');
+    var mobile = window.matchMedia('(max-width: 768px)').matches;
+    header.tabIndex = mobile ? -1 : 0;
+    header.setAttribute('aria-label', mobile ? name + ' conversation' : 'Move ' + name + ' conversation. Use arrow keys; hold Shift for larger steps.');
+    header.title = mobile ? name : 'Drag to move · Arrow keys when focused';
+    surface.querySelectorAll('[data-clay-resize]').forEach(function (handle) { handle.setAttribute('aria-label', 'Resize ' + name + ' conversation. Use arrow keys; hold Shift for larger steps.'); });
+    surface.querySelector('.contextual-clay-avatar').src = mateAvatarUrl(mate, 28);
+    var expand = surface.querySelector('[data-clay-expand]');
+    expand.querySelector('span').textContent = 'Open ' + name;
+    expand.setAttribute('aria-label', 'Open ' + name); expand.title = 'Open ' + name + ' workspace';
+    surface.querySelector('[data-clay-close]').setAttribute('aria-label', 'Close ' + name + ' conversation');
+
+  }
+  var projectContext = (store.get('projectsHubList') || []).find(function (item) { return item.slug === store.get('currentSlug'); });
+  var contextSession = getCachedSessions().find(function (item) { return item.id === store.get('activeSessionId'); });
+  var screen = store.get('homeShellVisible') || store.get('projectsHubVisible') ? 'Home' : store.get('dmMode') ? 'Direct message' : 'Project';
+  var projectView = screen === 'Project';
+  var parentReady = store.get('activeProjectSlug') === store.get('currentSlug') && store.get('sessionActivatedProjectSlug') === store.get('currentSlug') && !store.get('replayingHistory');
+  updateMateContext(surface, mate, contextualFrame(), {
+    projectTitle: projectView ? projectContext && (projectContext.title || projectContext.project || projectContext.slug) : store.get('projectsHubVisible') ? 'Projects' : screen,
+    conversationTitle: projectView && parentReady && contextSession ? contextSession.title : null,
+    projectSlug: projectView && parentReady ? store.get('currentSlug') : null,
+    sessionId: projectView && parentReady ? store.get('activeSessionId') : null,
+    screen: screen, ownerId: store.get('myUserId') || null
+  });
+  if (trigger()) trigger().setAttribute('aria-expanded', String(mode === 'popover'));
+  var selectedFrame = contextualFrame();
+  var connection = selectedFrame && selectedFrame.conversation;
+  surface.querySelector('[data-clay-loading]').hidden = !!(connection && connection.identity().ready) || surface.dataset.askPending === 'true';
+  surface.querySelectorAll('iframe').forEach(function (frame) { frame.hidden = frame !== selectedFrame; });
+}
+
+function createFrame(mate, sessionId) {
+  var surface = host();
+  var frame = document.createElement('iframe');
+  frame.title = getHomeMateName(mate) + ' conversation';
+  frame.dataset.mateId = mate.id;
+  frame.dataset.ownerId = store.get('myUserId') || '';
+  frame.dataset.identityStamp = contextualMateStamp(mate);
+  frame.dataset.canonical = String(mate.builtinKey === 'clay');
+  frame.hidden = true;
+  if (sessionId) frame.dataset.sessionId = String(sessionId);
+  var origin = store.get('contextualNativeOrigin');
+  frame.src = '/p/' + encodeURIComponent('mate-' + mate.id) + '/?pane=1&contextual=1' + (sessionId ? '&session=' + sessionId : origin && origin.mateId === mate.id ? '&session=' + origin.sessionId : '');
+  frame.addEventListener('load', function () {
+
+    try {
+      if (frame.contentWindow.location.pathname !== '/p/' + encodeURIComponent('mate-' + mate.id) + '/') return;
+      frame.contentDocument.addEventListener('click', function (event) {
+        if (frame === contextualFrame() && event.target.closest('#generation-stop, #autonomous-run-stop, #send-btn.stop')) clearClayControlActivity();
+      }, true);
+    } catch (error) { /* Authentication owns its document. */ }
+    if (frame === contextualFrame()) enterComposer();
+  });
+  surface.querySelector('.contextual-clay-body').appendChild(frame);
+  return frame;
+}
+function ensureSurface() {
+  if (!host()) {
+    var surface = document.createElement('section');
+    surface.id = 'contextual-clay'; surface.setAttribute('role', 'dialog');
+    surface.innerHTML = '<header><img class="contextual-clay-avatar" alt=""><div class="contextual-clay-identity"><strong></strong><div class="contextual-context-line"><span data-clay-context></span><details class="contextual-clay-context"><summary aria-label="What this Mate can see" title="What this Mate can see">' + iconHtml('circle-help') + '</summary><p></p></details></div></div><div class="contextual-clay-actions"><button type="button" data-clay-expand>' + iconHtml('arrow-up-right') + '<span></span></button><button type="button" data-clay-close title="Close">' + iconHtml('x') + '</button></div></header><p class="contextual-capabilities" role="note" aria-label="Conversation capabilities"></p><div class="contextual-clay-body"><p data-clay-loading role="status">Opening conversation…</p></div>';
+    surface.addEventListener('contextual-clay-keydown', function (event) {
+      var detail = event.detail; var frame = contextualFrame();
+      if (!detail || !frame || detail.source !== frame.contentWindow) return;
+      if (detail.keyboardEvent.key === 'Escape' && !detail.keyboardEvent.defaultPrevented && contextualClayMode() === 'popover') escapePopover(detail.keyboardEvent);
+    });
+    surface.addEventListener('contextual-clay-ready', function () {
+      var frame = contextualFrame(), current = state();
+      var identity = frame && frame.conversation && frame.conversation.identity();
+      if (identity && identity.ready && identity.ownerId === store.get('myUserId') && identity.mateId === current.mateId && !current.sessionId && !current.startingAsk) {
+        var selections = Object.assign({}, store.get('contextualSessionSelection')); selections[current.mateId] = identity.sessionId;
+        store.set({ contextualSessionSelection: selections, contextualClay: Object.assign({}, current, { sessionId: identity.sessionId }) });
+      }
+      syncContextualNativeOrigin(); render();
+    });
+    surface.addEventListener('contextual-clay-availability', render);
+    surface.addEventListener('contextual-context-submitted', function (event) { recordMateContextSubmission(surface, event); });
+    document.body.appendChild(surface); attachContextualConversations(surface); attachContextualSessionCitations(surface); attachContextualGeometry(surface); refreshIcons();
+    surface.querySelector('[data-clay-close]').addEventListener('click', function () { dismissContextualClay(true); });
+    surface.querySelector('[data-clay-expand]').addEventListener('click', function () { var mate = contextualMate(state().mateId); if (mate) openContextualWorkspace(mate); });
+  }
+}
+
+export function showContextualAsk(mate, requestId, sessionId) {
+  if (!mate || !contextualMate(mate.id) || store.get('paneMode') || !finishContextualNativeOrigin()) return false;
+  ensureSurface();
+  if (sessionId && !contextualFrame(mate.id, sessionId)) createFrame(mate, sessionId);
+  var selections = Object.assign({}, store.get('contextualSessionSelection'));
+  if (sessionId) selections[mate.id] = sessionId;
+  store.set({ contextualSessionSelection: selections, contextualClay: { mode: 'popover', mateId: mate.id, sessionId: sessionId || null, startingAsk: sessionId ? null : requestId } });
+  host().querySelector('[data-clay-loading]').hidden = !!sessionId;
+  if (sessionId && contextualFrame()) contextualFrame().hidden = false;
+  return true;
+}
+
+export function selectContextualConversation(mate, sessionId, sessionOriginId) {
+  var existing = contextualFrame(mate.id, sessionId);
+  if (existing && existing.conversation && existing.conversation.identity().sessionOriginId !== sessionOriginId) return false;
+  var previous = state(), selections = store.get('contextualSessionSelection');
+  if (!showContextualAsk(mate, 'conversation-selection', sessionId)) return false;
+  var frame = contextualFrame(mate.id, sessionId);
+  if (!frame) return false;
+  frame.dataset.expectedSessionOrigin = sessionOriginId;
+  if (!beginContextualNativeOrigin(mate)) { store.set({ contextualClay: previous, contextualSessionSelection: selections }); return false; }
+  if (frame.conversation) frame.conversation.suspend(false);
+  syncContextualNativeOrigin();
+  return true;
+}
+
+export function cycleContextualClay(mate) {
+  if (store.get('paneMode') || !mate || !contextualMate(mate.id)) return;
+  var current = state();
+  if (current.mode === 'opening') return;
+  if (current.mode === 'closed') store.set({ contextualPrepared: null });
+  if (current.mode === 'popover' && current.mateId === mate.id) { openContextualWorkspace(mate); return; }
+  if (store.get('contextualNativeOrigin') && current.mateId !== mate.id && !finishContextualNativeOrigin()) return;
+  if (!store.get('contextualNativeOrigin') && !beginContextualNativeOrigin(mate)) return;
+  ensureSurface();
+  var frame = contextualFrame(mate.id) || createFrame(mate);
+  store.set({ contextualClay: { mode: 'popover', mateId: mate.id, sessionId: frame.dataset.sessionId ? Number(frame.dataset.sessionId) : null } });
+  if (frame.conversation) frame.conversation.suspend(false);
+  host().dataset.focusEntry = 'true'; syncContextualNativeOrigin(); enterComposer();
+}
+
+export function initContextualClay() {
+  if (store.get('paneMode')) {
+    initContextualSession();
+    return;
+  }
+  initContextualMateHint(activateContextualMate);
+  initContextualGeometry();
+  initClayControlActivity();
+  initContextualWorkspace();
+  document.addEventListener('pointerdown', function (event) {
+    if (host() && !host().contains(event.target)) host().querySelectorAll('details[open]').forEach(function (menu) { menu.open = false; });
+  });
+  document.addEventListener('keydown', function (event) {
+    if (event.key === 'Escape' && !event.defaultPrevented && contextualClayMode() === 'popover') {
+      escapePopover(event);
+    }
+  });
+  // Keep the same trigger accessible when the desktop rail is hidden.
+  var entry = document.querySelector('.icon-strip-brand');
+  var rail = entry && entry.parentNode;
+  var next = entry && entry.nextSibling;
+  var mobile = window.matchMedia('(max-width: 768px)');
+  function placeTrigger() {
+    if (!entry) return;
+    document.body.classList.toggle('contextual-clay-mobile', mobile.matches);
+    entry.classList.toggle('contextual-clay-mobile-trigger', mobile.matches);
+    if (mobile.matches) document.body.prepend(entry);
+    else rail.insertBefore(entry, next && next.parentNode === rail ? next : rail.firstChild);
+    render();
+  }
+  mobile.addEventListener('change', placeTrigger);
+  window.addEventListener('resize', function () { if (host()) positionContextualClay(); });
+  placeTrigger();
+  store.subscribe(function (value, previous) {
+    var current = state();
+    if (host()) host().querySelectorAll('iframe').forEach(function (frame) {
+      var mate = contextualMate(frame.dataset.mateId);
+      if (frame.dataset.discarding === 'true') return;
+      if (frame.dataset.ownerId !== (value.myUserId || '') || !mate || frame.dataset.identityStamp !== contextualMateStamp(mate)) { frame.dataset.discarding = 'true'; frame.remove(); abandonContextualNativeOrigin(frame.dataset.mateId); }
+      else frame.title = getHomeMateName(mate) + ' conversation';
+    });
+    if (current.mateId && !current.startingAsk && !contextualFrame(current.mateId)) {
+      store.set({ contextualClay: { mode: 'closed', mateId: null } }); render(); return;
+    }
+    if (value.contextualMatePending && !value.contextualWorkspace && !value.pendingProjectSessionNavigation) {
+      var pending = value.contextualMatePending;
+      store.set({ contextualMatePending: null }); activateContextualMate(pending); return;
+    }
+    // Ordinary navigation refreshes context without replacing the conversation.
+    // Direct navigation into a native Mate workspace ends the floating surface.
+    if (current.mode === 'popover' && value.currentSlug !== previous.currentSlug && (value.currentSlug || '').indexOf('mate-') === 0) dismissContextualClay(false);
+    render();
+  });
+}

package/lib/public/modules/contextual-composer.js

@@ -0,0 +1,91 @@
+import { store } from './store.js';
+import { iconHtml, refreshIcons } from './icons.js';
+
+// Reparent the live controls: their permissions, upload and model handlers stay
+// with the production composer. Only contextual panes use this presentation.
+export function initContextualComposer() {
+  var row = document.getElementById('input-row');
+  var tools = document.getElementById('attach-wrap');
+  var config = document.getElementById('config-chip-wrap');
+  var model = document.getElementById('config-chip');
+  var modelPopover = document.getElementById('config-popover');
+  var button = document.createElement('button');
+  button.id = 'contextual-attach-btn'; button.type = 'button';
+  button.setAttribute('aria-label', 'Add attachments and context');
+  button.setAttribute('aria-haspopup', 'dialog');
+  button.setAttribute('aria-controls', 'contextual-attach-popover');
+  button.innerHTML = iconHtml('plus');
+  var menu = document.createElement('div');
+  menu.id = 'contextual-attach-popover'; menu.hidden = true;
+  menu.setAttribute('role', 'dialog'); menu.setAttribute('aria-label', 'Attachments and context');
+  menu.appendChild(tools); row.append(button, config, menu);
+  ['attach-file-btn', 'attach-image-btn'].forEach(function (id) {
+    var control = document.getElementById(id);
+    var label = document.createElement('span');
+    label.textContent = id === 'attach-file-btn' ? 'File' : 'Image'; control.appendChild(label);
+    control.addEventListener('click', function () { close(true); });
+  });
+  var contextLabel = document.createElement('span'); contextLabel.textContent = 'Context sources';
+  document.getElementById('context-sources-add').appendChild(contextLabel);
+  model.setAttribute('aria-label', 'Model and session settings');
+  model.setAttribute('aria-haspopup', 'dialog'); model.setAttribute('aria-controls', 'config-popover');
+  model.setAttribute('aria-expanded', 'false');
+  modelPopover.setAttribute('role', 'dialog'); modelPopover.setAttribute('aria-label', 'Model and session settings');
+  function position(popover, anchor) {
+    var rect = anchor.getBoundingClientRect();
+    popover.style.width = Math.min(280, window.innerWidth - 16) + 'px';
+    popover.style.left = Math.max(8, Math.min(rect.left, window.innerWidth - Math.min(280, window.innerWidth - 16) - 8)) + 'px';
+    popover.style.bottom = Math.max(8, window.innerHeight - rect.top + 6) + 'px';
+    popover.style.maxHeight = Math.max(40, rect.top - 14) + 'px';
+  }
+  function close(restoreFocus) {
+    store.set({ contextualAttachmentMenuOpen: false });
+    if (restoreFocus) button.focus({ preventScroll: true });
+  }
+  function actions() { return Array.from(menu.querySelectorAll('button:not(:disabled)')).filter(function (item) { return item.getClientRects().length; }); }
+  button.addEventListener('click', function () {
+    var open = !store.get('contextualAttachmentMenuOpen');
+    modelPopover.classList.add('hidden'); model.classList.remove('active');
+    store.set({ contextualAttachmentMenuOpen: open });
+    if (open && actions()[0]) actions()[0].focus({ preventScroll: true });
+  });
+  document.addEventListener('pointerdown', function (event) {
+    if (!menu.contains(event.target) && !button.contains(event.target) && store.get('contextualAttachmentMenuOpen')) close(false);
+  });
+  document.addEventListener('keydown', function (event) {
+    if (event.key === 'Escape' && (!menu.hidden || !modelPopover.classList.contains('hidden'))) {
+      event.preventDefault(); event.stopImmediatePropagation();
+      var sources = document.getElementById('context-sources-picker');
+      if (!menu.hidden && !sources.classList.contains('hidden')) { sources.classList.add('hidden'); document.getElementById('context-sources-add').focus(); }
+      else if (!menu.hidden) close(true);
+      else { modelPopover.classList.add('hidden'); model.classList.remove('active'); model.focus({ preventScroll: true }); }
+      return;
+    }
+    if (menu.hidden || !menu.contains(event.target) || !/^(ArrowDown|ArrowUp|Home|End)$/.test(event.key)) return;
+    var items = actions(), index = items.indexOf(document.activeElement);
+    if (!items.length) return;
+    event.preventDefault();
+    items[event.key === 'Home' ? 0 : event.key === 'End' ? items.length - 1 : (index + (event.key === 'ArrowUp' ? items.length - 1 : 1)) % items.length].focus();
+  }, true);
+  menu.addEventListener('focusout', function (event) {
+    if (menu.contains(event.relatedTarget) || event.relatedTarget === button) return;
+    setTimeout(function () { if (!menu.contains(document.activeElement) && document.activeElement !== button && !menu.hidden) close(false); }, 0);
+  });
+  model.addEventListener('click', function () { close(false); });
+  function placeMenus() { if (!menu.hidden) position(menu, button); if (!modelPopover.classList.contains('hidden')) position(modelPopover, model); }
+  new MutationObserver(function () {
+    model.setAttribute('aria-expanded', String(!modelPopover.classList.contains('hidden')));
+    placeMenus();
+  }).observe(modelPopover, { attributes: true, attributeFilter: ['class'] });
+  new ResizeObserver(placeMenus).observe(row);
+  window.addEventListener('resize', placeMenus);
+  store.subscribe(function (value) {
+    var open = !!value.contextualAttachmentMenuOpen && value.contextualSessionReady && !value.contextualWriterSuspended;
+    menu.hidden = !open; button.setAttribute('aria-expanded', String(open));
+    button.disabled = !value.contextualSessionReady || !!value.contextualWriterSuspended;
+    if (button.disabled) { modelPopover.classList.add('hidden'); model.classList.remove('active'); }
+    placeMenus();
+  });
+  store.set({ contextualAttachmentMenuOpen: false });
+  refreshIcons();
+}

package/lib/public/modules/contextual-mate-context.js

@@ -0,0 +1,117 @@
+import { store } from './store.js';
+import { getWs } from './ws-ref.js';
+import { contextualFrame } from './contextual-mate-identity.js';
+
+function identity(frame) {
+  try { return frame && frame.conversation && frame.conversation.identity(); } catch (error) { return null; }
+}
+function contextKey(frame, canonical) {
+  var current = identity(frame);
+  return JSON.stringify([store.get('currentSlug'), store.get('activeSessionId'), store.get('sessionOriginId'), store.get('activeProjectSlug'), store.get('sessionActivatedProjectSlug'), store.get('replayingHistory'), (store.get('contextualClay') || {}).mode, store.get('homeShellVisible'), store.get('projectsHubVisible'), store.get('dmMode'), store.get('rightWorkbenchOwner'), store.get('homeSubSurface'), store.get('rightWorkbenchRevision'), store.get('myUserId'), store.get('connected'), current && current.mateId, current && current.sessionId, current && (canonical ? current.connected : current.ready), canonical && current && current.sessionOriginId]);
+}
+export function updateMateContext(surface, mate, frame, snapshot) {
+  var current = identity(frame), ws = getWs(), key = contextKey(frame, mate && mate.builtinKey === 'clay'), prepared = store.get('contextualPrepared');
+  var canonical = mate && mate.builtinKey === 'clay';
+  var capabilities = surface.querySelector('.contextual-capabilities');
+  capabilities.hidden = !canonical;
+  capabilities.setAttribute('aria-label', 'Clay capabilities');
+  capabilities.textContent = "I can control Clay Studio for you—manage projects, coordinate work, set up schedules, and navigate your workspace. Just tell me what you’d like done.";
+  var privateWorkspace = (store.get('currentSlug') || '').indexOf('mate-') === 0;
+  var parentReady = store.get('activeProjectSlug') === store.get('currentSlug') && store.get('sessionActivatedProjectSlug') === store.get('currentSlug') && !store.get('replayingHistory');
+  var available = (store.get('contextualClay') || {}).mode === 'popover' && parentReady && !canonical && !privateWorkspace && current && current.ready && store.get('connected') && !store.get('homeShellVisible') && !store.get('projectsHubVisible') && !store.get('dmMode') && !store.get('rightWorkbenchOwner') && ws && ws.readyState === 1;
+  var changed = !prepared || prepared.key !== key || prepared.socket !== ws;
+  if (changed) {
+    var requestId = 'context-' + crypto.randomUUID();
+    prepared = { key: key, requestId: requestId, socket: ws, mateId: current && current.mateId, canonical: !!canonical, status: available ? 'preparing' : 'unavailable' };
+  }
+  // Stamp the reference before publishing a new preparation: store subscribers
+  // may render synchronously, and the composer must never see the prior view ID.
+  snapshot = Object.assign({}, snapshot, { viewId: prepared.requestId });
+  surface.dataset.screenReference = JSON.stringify(snapshot);
+  if (changed) {
+    store.set({ contextualPrepared: prepared });
+    if (ws && ws.readyState === 1) ws.send(JSON.stringify({ type: 'mate_context_prepare', requestId: requestId, available: !!available, mateId: current && current.mateId, sessionId: current && current.sessionId }));
+  }
+  var shared = ((store.get('contextualSubmitted') || {})[mate && mate.id]);
+  var ready = prepared.status === 'ready' && prepared.expiresAt > Date.now();
+  var label = surface.querySelector('[data-clay-context]');
+  var detail = surface.querySelector('.contextual-clay-context p');
+  var summary = ready ? prepared.summary.project + ' / ' + prepared.summary.conversation : null;
+  var projectName = (ready && prepared.summary.project) || snapshot.projectTitle || snapshot.screen || 'Current view';
+  if (canonical) {
+    var currentSummary = (snapshot.projectTitle || snapshot.screen || 'Current view') + (snapshot.conversationTitle ? ' / ' + snapshot.conversationTitle : '');
+    var disconnected = !store.get('connected') || current && current.connected === false;
+    var sameSnapshot = shared && shared.viewId === prepared.requestId && shared.summary.project + (snapshot.conversationTitle ? ' / ' + shared.summary.conversation : '') === currentSummary;
+    var contextStatus = disconnected ? 'Disconnected' : current && current.available === false ? 'Unavailable' : !current || !current.ready ? 'Preparing' : sameSnapshot ? 'Shared' : shared ? 'New view' : 'Next message';
+    detail.textContent = "I can help manage your projects, coordinate work with Drivers, and use Studio’s tools. I’ll ask you to review actions when needed.\n"
+      + 'Current view: ' + currentSummary + '. ' + (disconnected ? 'Reconnect before sharing a new snapshot. ' : !current || !current.ready ? 'Wait for this conversation before sharing a new snapshot. ' : sameSnapshot ? 'This metadata snapshot was shared with your last message. Your next message captures the current view again. ' : 'Your next message includes this metadata snapshot. ')
+      + 'Clay receives project and conversation metadata, not continuous screen capture. Its authenticated product tools inspect supported objects separately; changes require their existing review.';
+  } else {
+    contextStatus = !store.get('connected') || current && current.connected === false ? 'Disconnected' : current && current.available === false ? 'Unavailable' : current && !current.ready || prepared.status === 'preparing' ? 'Preparing' : ready ? (shared && shared.viewId === prepared.requestId ? 'Shared' : shared ? 'New view' : 'Next message') : 'Unavailable';
+    detail.textContent = ready ? (shared && shared.viewId === prepared.requestId ? 'Shared with your last message: ' : 'With your next message: ') + summary + '. This Mate can read up to 20 text turns from this selected conversation and request to open it in this window after your review. Tool results, attachments and hidden entries are excluded.' : 'Current view: ' + projectName + '. This view has no supported conversation context. Open an accessible project conversation to share it with your next message.';
+    detail.textContent += '\nNo continuous screen capture. Issues, documents, other tabs, files and settings are unavailable through this context.';
+  }
+  if (prepared.status === 'expired' && !canonical) { contextStatus = 'Expired'; detail.textContent = 'This five-minute context has expired. Close and reopen this Mate to prepare a fresh snapshot. No previous navigation request will replay.'; }
+  if (shared) detail.textContent += '\nLast submitted: ' + shared.summary.project + ' / ' + shared.summary.conversation + ((canonical ? sameSnapshot : shared.viewId === prepared.requestId) ? '.' : canonical ? '. The view or connection has changed; that snapshot is stale.' : '. Your view has changed; that context is stale.');
+  var projectLabel = label.querySelector('[data-context-project]');
+  if (!projectLabel) { projectLabel = document.createElement('span'); projectLabel.dataset.contextProject = ''; var statusLabel = document.createElement('span'); statusLabel.dataset.contextStatus = ''; label.replaceChildren(projectLabel, statusLabel); }
+  projectLabel.textContent = projectName;
+  label.querySelector('[data-context-status]').textContent = ' · ' + contextStatus;
+  label.title = label.textContent;
+  surface.contextReference = function (source, session) {
+    var live = store.get('contextualPrepared');
+    if (!frame || frame.hidden || frame.contentWindow !== source || !session || !current || session.mateId !== current.mateId || session.sessionId !== current.sessionId || !session.ready || !live || live.key !== contextKey(frame, canonical) || live.socket !== getWs() || live.status !== 'ready' || live.expiresAt <= Date.now()) return null;
+    return live.contextRef;
+  };
+}
+export function handleMateContextMessage(msg) {
+  if (msg.type === 'mate_context_prepared') {
+    var pending = store.get('contextualPrepared');
+    if (pending && pending.requestId === msg.requestId && pending.socket === getWs() && pending.key === contextKey(contextualFrame(), pending.canonical)) {
+      store.set({ contextualPrepared: Object.assign({}, pending, msg, { status: msg.contextRef ? 'ready' : 'unavailable' }) });
+      if (msg.contextRef) setTimeout(function () {
+        var current = store.get('contextualPrepared');
+        if (current && current.contextRef === msg.contextRef) store.set({ contextualPrepared: Object.assign({}, current, { status: 'expired' }) });
+      }, Math.max(0, msg.expiresAt - Date.now()));
+    }
+    return true;
+  }
+  if ((msg.type === 'message_ack' || msg.type === 'user_message') && window.parent !== window && window.frameElement && window.frameElement.dataset.canonical === 'true') {
+    var recorded = msg.type === 'message_ack' ? msg.message : msg;
+    var outbound = (store.get('contextualSnapshotSubmissions') || []).find(function (item) { return item.clientMessageId === msg.clientMessageId; });
+    if (!outbound || outbound.confirmed || outbound.accountId !== (store.get('myUserId') || '_default') || !recorded || recorded.clientMessageId !== outbound.clientMessageId || !recorded.contextualSnapshot || msg.type === 'message_ack' && (msg.projectSlug !== outbound.projectSlug || String(msg.sessionId) !== String(outbound.sessionId)) || recorded.projectSlug !== outbound.projectSlug || String(recorded.sessionId) !== String(outbound.sessionId) || recorded.sessionOriginId !== outbound.sessionOriginId || recorded.from && recorded.from !== outbound.accountId || JSON.stringify(recorded.contextualSnapshot) !== JSON.stringify(outbound.snapshot)) return false;
+    var snapshot = recorded.contextualSnapshot;
+    store.set({ contextualSnapshotSubmissions: store.get('contextualSnapshotSubmissions').map(function (item) { return item === outbound ? Object.assign({}, item, { confirmed: true }) : item; }) });
+    try {
+      var host = window.parent.document.getElementById('contextual-clay');
+      if (host) host.dispatchEvent(new window.parent.CustomEvent('contextual-context-submitted', { detail: { source: window, message: { status: 'submitted', canonical: true, clientMessageId: msg.clientMessageId, viewId: snapshot.viewId, summary: { project: snapshot.projectTitle || snapshot.projectSlug || 'Home', conversation: snapshot.conversationTitle || snapshot.screen } } } }));
+    } catch (error) { /* A disconnected authentication view cannot share metadata. */ }
+    return false;
+  }
+  if (msg.type !== 'mate_context_shared') return false;
+  try {
+    var surface = window.parent.document.getElementById('contextual-clay');
+    if (surface && window.frameElement && surface.contains(window.frameElement)) surface.dispatchEvent(new window.parent.CustomEvent('contextual-context-submitted', { detail: { source: window, message: msg } }));
+  } catch (error) { /* A disconnected authentication view cannot share context. */ }
+  return true;
+}
+export function recordMateContextSubmission(surface, event) {
+  var frame = Array.from(surface.querySelectorAll('iframe')).find(function (item) { return item.contentWindow === event.detail.source; });
+  var pending = store.get('contextualPrepared'), msg = event.detail.message;
+  if (!frame || frame.dataset.ownerId !== (store.get('myUserId') || '') || (!msg.canonical && frame.hidden) || !pending) return;
+  if (msg.status === 'unavailable') {
+    if (pending.mateId === frame.dataset.mateId) store.set({ contextualPrepared: Object.assign({}, pending, { status: 'unavailable' }) });
+    return;
+  }
+  if (msg.status !== 'submitted' || !msg.summary || (msg.canonical ? frame.dataset.canonical !== 'true' || typeof msg.viewId !== 'string' : msg.contextRef !== pending.contextRef)) return;
+  var submitted = Object.assign({}, store.get('contextualSubmitted'));
+  submitted[frame.dataset.mateId] = { key: msg.canonical ? null : pending.key, viewId: msg.canonical ? msg.viewId : pending.requestId, summary: msg.summary };
+  store.set({ contextualSubmitted: submitted });
+}
+export function contextualAccessReference() {
+  if (window.parent === window || !store.get('paneMode')) return null;
+  try {
+    var surface = window.parent.document.getElementById('contextual-clay');
+    return surface && surface.contextReference && surface.contextReference(window, { mateId: window.frameElement.dataset.mateId, sessionId: store.get('paneSessionId'), ready: store.get('contextualSessionReady') && store.get('connected') });
+  } catch (error) { return null; }
+}