clay-server 5.2.0-beta.5 → 5.2.0-beta.7

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

@@ -0,0 +1,237 @@
+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; }
+    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'); });
+  updateMateContext(surface, mate, contextualFrame(), { projectTitle: store.get('homeShellVisible') ? 'Home' : projectContext && (projectContext.title || projectContext.project || projectContext.slug), conversationTitle: contextSession && contextSession.title, projectSlug: store.get('homeShellVisible') ? null : store.get('currentSlug'), sessionId: store.get('homeShellVisible') ? null : store.get('activeSessionId'), screen: store.get('homeShellVisible') ? 'Home' : store.get('dmMode') ? 'Direct message' : 'Project', 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 (contextualClayMode() === 'popover' && host() && !host().contains(event.target) && !(trigger() && trigger().contains(event.target)) && !event.target.closest('#contextual-mate-hint, .icon-strip-project-mate, .icon-strip-brand')) dismissContextualClay(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;
+    }
+    if (current.mode === 'popover' && (value.currentSlug !== previous.currentSlug || value.homeShellVisible !== previous.homeShellVisible || value.dmMode !== previous.dmMode)) 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,115 @@
+import { store } from './store.js';
+import { getWs } from './ws-ref.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('homeShellVisible'), 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 available = !canonical && !privateWorkspace && current && current.ready && store.get('connected') && !store.get('homeShellVisible') && !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, 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()) {
+      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; }
+}

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

@@ -0,0 +1,40 @@
+import { store } from './store.js';
+import { contextualMate, contextualTrigger } from './contextual-mate-identity.js';
+import { getHomeMateName } from './home-mate-selection.js';
+
+export function renderContextualMateHint() {
+  var state = store.get('contextualClay') || {};
+  var mate = contextualMate(state.mateId);
+  var active = state.mode === 'popover' && mate;
+  var narrow = window.matchMedia('(max-width: 768px)').matches;
+  var moved = document.querySelector('.contextual-mate-mobile-trigger');
+  if (moved && (!active || !narrow || moved.dataset.mateId !== mate.id)) {
+    moved.classList.remove('contextual-mate-mobile-trigger');
+    document.getElementById('icon-strip-projects').appendChild(moved);
+  }
+  var anchor = active && contextualTrigger(mate.id);
+  if (anchor && narrow && mate.builtinKey !== 'clay') {
+    anchor.classList.add('contextual-mate-mobile-trigger'); if (anchor.parentNode !== document.body) document.body.appendChild(anchor);
+  }
+  document.body.classList.toggle('contextual-mate-hint-mobile', !!active && narrow);
+  document.body.classList.toggle('contextual-mate-ordinary-mobile', !!active && narrow && mate.builtinKey !== 'clay');
+  document.querySelectorAll('[aria-describedby="contextual-mate-hint"]').forEach(function (item) { if (item !== anchor) item.removeAttribute('aria-describedby'); });
+  var hint = document.getElementById('contextual-mate-hint');
+  if (!hint || !active || !anchor || !anchor.getClientRects().length) { if (hint) hint.hidden = true; return null; }
+  anchor.setAttribute('aria-describedby', hint.id);
+  var name = getHomeMateName(mate);
+  hint.textContent = (window.matchMedia('(pointer: coarse)').matches ? 'Tap' : 'Click') + ' again to open ' + name;
+  hint.title = hint.textContent;
+  hint.setAttribute('aria-label', 'Open ' + name + ' workspace');
+  hint.hidden = false;
+  var rect = anchor.getBoundingClientRect();
+  hint.style.maxWidth = (narrow ? window.innerWidth - 64 : Math.min(260, window.innerWidth - rect.right - 24)) + 'px';
+  hint.style.left = (narrow ? 50 : rect.right + 8) + 'px';
+  hint.style.top = (narrow ? 8 : Math.max(8, Math.min(window.innerHeight - 38, rect.top + (rect.height - 28) / 2))) + 'px';
+  return hint.getBoundingClientRect();
+}
+export function initContextualMateHint(activate) {
+  var hint = document.createElement('button'); hint.type = 'button'; hint.id = 'contextual-mate-hint'; hint.hidden = true;
+  hint.addEventListener('click', function () { activate((store.get('contextualClay') || {}).mateId); });
+  document.body.appendChild(hint);
+}

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

@@ -0,0 +1,23 @@
+import { store } from './store.js';
+
+export function contextualMate(id) {
+  var mate = (store.get('cachedMatesList') || []).find(function (item) { return item && item.id === id; });
+  if (!mate || mate.archived || mate.contentAccess === false || mate.accessible === false) return null;
+  var owner = store.get('myUserId');
+  if (owner && mate.createdBy && mate.createdBy !== owner) return null;
+  var project = (store.get('projectsHubList') || []).find(function (item) { return item.slug === 'mate-' + id; });
+  if (project && project.contentAccess === false) return null;
+  return mate;
+}
+export function contextualMateStamp(mate) { return JSON.stringify([mate.id, mate.createdBy || null, mate.createdAt || null, mate.builtinKey || null]); }
+export function contextualFrame(id, sessionId) {
+  var mateId = id || (store.get('contextualClay') || {}).mateId;
+  var current = store.get('contextualClay') || {};
+  if (!sessionId && current.mateId === mateId && current.startingAsk) return null;
+  var selected = sessionId || (current.mateId === mateId && current.sessionId) || (store.get('contextualSessionSelection') || {})[mateId];
+  return Array.from(document.querySelectorAll('#contextual-clay iframe')).find(function (frame) { return frame.dataset.mateId === mateId && (!selected || String(selected) === frame.dataset.sessionId); }) || null;
+}
+export function contextualTrigger(id) {
+  var mate = contextualMate(id || (store.get('contextualClay') || {}).mateId);
+  return mate && mate.builtinKey !== 'clay' ? document.querySelector('.icon-strip-project-mate[data-mate-id="' + CSS.escape(mate.id) + '"]') : document.querySelector('.icon-strip-brand');
+}