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

package/lib/public/modules/clay-control-activity.js

@@ -0,0 +1,214 @@
+// Owner-authenticated presentation only; this module never invokes a product action.
+import { contextualMateStamp } from './contextual-mate-identity.js';
+import { store } from './store.js';
+import { mateAvatarUrl } from './avatar.js';
+import { activityCopy, validActivity } from './clay-control-copy.js';
+import { controlTarget, activityPlacement, visibleTarget } from './clay-control-targets.js';
+
+function forward(message) {
+  if (!store.get('paneMode') || window.parent === window) return false;
+  store.set({ clayControlForwarded: message });
+  window.parent.postMessage({ type: 'clay-control-presentation', message: message }, location.origin);
+  return true;
+}
+export function clearClayControlActivity() {
+  var activity = store.get('clayControlActivity');
+  if (activity) {
+    clearTimeout(activity.timer);
+    cancelAnimationFrame(activity.frame);
+    if (activity.animation) activity.animation.cancel();
+    if (activity.observer) activity.observer.disconnect();
+    if (activity.resize) activity.resize.disconnect();
+  }
+  store.set({ clayControlActivity: null });
+  var element = document.getElementById('clay-control-activity');
+  if (element) element.remove();
+}
+function layout() {
+  var activity = store.get('clayControlActivity'), element = document.getElementById('clay-control-activity');
+  if (!activity || !element) return;
+  var surface = document.getElementById('contextual-clay');
+  var narrow = window.matchMedia('(max-width: 768px)').matches;
+  var workbench = narrow && Array.from(document.querySelectorAll('#file-viewer, #mate-knowledge-workbench, #project-logs-panel, #issues-panel, #scheduled-tasks-panel')).find(function (item) { return visibleTarget(item); });
+  var host = workbench || surface;
+  var inline = narrow && host && !host.hidden && host.getClientRects().length;
+  element.classList.toggle('is-inline', !!inline);
+  if (inline) {
+    if (element.parentNode !== host) {
+      if (host === surface) host.insertBefore(element, surface.querySelector('.contextual-clay-body'));
+      else host.insertBefore(element, host.children[1] || null);
+    }
+    element.classList.remove('has-target', 'is-flipped', 'is-reversed');
+    element.dataset.targeted = 'false'; element.style.visibility = 'visible';
+    element.style.marginTop = '6px';
+    var inlineBox = element.getBoundingClientRect(), offset = 0;
+    Array.from(document.querySelectorAll('.notif-banner.show')).forEach(function (banner) { var rect = banner.getBoundingClientRect(); if (rect.left < inlineBox.right && rect.right > inlineBox.left && rect.bottom > inlineBox.top && rect.top < inlineBox.bottom) offset = Math.max(offset, rect.bottom - inlineBox.top + 8); });
+    if (offset) element.style.marginTop = (6 + offset) + 'px';
+    return;
+  }
+  if (element.parentNode !== document.body) document.body.appendChild(element);
+  element.style.removeProperty("margin-top");
+  var contextual = store.get('contextualClay') || {};
+  var background = activity.fromPane && (contextual.mode !== 'popover' || contextual.mateId !== activity.message.mateId);
+  var row = !background && !window.matchMedia('(pointer: coarse), (max-width: 768px)').matches && controlTarget(activity.message.target);
+  if (activity.targetNode !== row) {
+    if (activity.targetNode) activity.resize.unobserve(activity.targetNode);
+    activity.targetNode = row;
+    if (row) activity.resize.observe(row, { box: 'border-box' });
+  }
+  var obstacles = Array.from(document.querySelectorAll('#input-area, #contextual-clay, .ask-user-container:not(.answered), [role="dialog"], .notif-banner.show, #file-viewer-body, .wireframe-workbench-canvas')).filter(function (item) {
+    return (!row || !item.contains(row) || item.id === 'input-area') && !item.closest('details:not([open]), [hidden], [inert], [aria-hidden="true"]') && item.getClientRects().length && !item.hidden && getComputedStyle(item).visibility !== 'hidden' && Number(getComputedStyle(item).opacity) > 0;
+  }).map(function (item) { return item.getBoundingClientRect(); });
+  var box = element.getBoundingClientRect();
+  var place = activityPlacement(row, box.width, box.height, obstacles);
+  element.style.visibility = place ? 'visible' : 'hidden';
+  if (!place) { if (activity.animation) activity.animation.cancel(); element.dataset.targeted = 'false'; element.classList.remove('has-target', 'is-flipped', 'is-reversed'); element.style.removeProperty('--tip-x'); element.style.removeProperty('--tip-y'); return; }
+  var targeted = place.tipX !== undefined;
+  if (!targeted && activity.animation) { activity.animation.cancel(); activity.animation = null; }
+  element.classList.toggle('has-target', targeted);
+  element.classList.toggle('is-flipped', !!place.flip);
+  element.classList.toggle('is-reversed', !!place.reverse);
+  element.style.left = place.left + 'px'; element.style.top = place.top + 'px';
+  if (targeted) {
+    element.style.setProperty('--tip-x', (place.tipX - place.left) + 'px');
+    element.style.setProperty('--tip-y', (place.tipY - place.top) + 'px');
+  }
+  element.dataset.targeted = String(targeted);
+  if (document.getAnimations().some(function (animation) {
+    var node = animation.effect && animation.effect.target;
+    if (animation.playState !== 'running' || !(node instanceof Element) || element.contains(node) ||
+      !(row && (node === row || node.contains(row)) || node.matches('.notif-banner.show'))) return false;
+    if (!activity.motionSeen) activity.motionSeen = new WeakSet();
+    if (!activity.motionSeen.has(animation)) { activity.motionSeen.add(animation); activity.motionUntil = Date.now() + 5000; }
+    return Date.now() < activity.motionUntil;
+  })) scheduleLayout();
+}
+function scheduleLayout() {
+  var activity = store.get('clayControlActivity');
+  if (!activity || activity.frame) return;
+  activity.frame = requestAnimationFrame(function () { activity.frame = null; layout(); });
+}
+function render(message, mate, copy, fromPane) {
+  var existing = store.get('clayControlActivity');
+  if (existing && existing.message.id === message.id) {
+    existing.message = message;
+    existing.fromPane = !!fromPane;
+    clearTimeout(existing.timer);
+    existing.timer = setTimeout(clearClayControlActivity, message.terminal === false || ['review', 'running'].indexOf(message.phase) >= 0 ? 300000 : 6000);
+    document.querySelector('#clay-control-activity .clay-control-bubble').textContent = copy;
+    scheduleLayout(); return;
+  }
+  var previous = document.getElementById('clay-control-activity');
+  var previousRect = previous && previous.classList.contains('has-target') && previous.getBoundingClientRect();
+  clearClayControlActivity();
+  var element = document.createElement('div'); element.id = 'clay-control-activity';
+  element.setAttribute('role', 'status'); element.setAttribute('aria-live', 'polite'); element.setAttribute('aria-atomic', 'true');
+  var identity = document.createElement('span'); identity.className = 'clay-control-identity';
+  var avatar = document.createElement('img'); avatar.alt = ''; avatar.width = 20; avatar.height = 20;
+  avatar.addEventListener('error', function () { avatar.hidden = true; }, { once: true });
+  avatar.src = mateAvatarUrl(mate, 20);
+  var name = document.createElement('span'); name.className = 'clay-control-name';
+  name.textContent = (mate.profile || {}).displayName || mate.displayName || mate.name || (mate.builtinKey === 'clay' ? 'Clay' : 'Mate');
+  identity.append(avatar, name);
+  var bubble = document.createElement('span'); bubble.className = 'clay-control-bubble'; bubble.textContent = copy;
+  var pointer = document.createElement('span'); pointer.className = 'clay-control-pointer'; pointer.setAttribute('aria-hidden', 'true');
+  element.append(pointer, identity, bubble); document.body.appendChild(element);
+  var observer = new MutationObserver(function (changes) {
+    if (changes.some(function (change) { return !element.contains(change.target); })) scheduleLayout();
+  });
+  observer.observe(document.body, { childList: true, subtree: true, attributes: true, attributeFilter: ['class', 'hidden', 'inert', 'data-session-id', 'data-control-session-origin', 'data-control-revision', 'data-ref', 'data-task-id', 'data-open-issue', 'data-control-runtime', 'data-control-mate-stamp'] });
+  var resize = new ResizeObserver(scheduleLayout); resize.observe(document.body); resize.observe(element);
+  var activity = { message: message, fromPane: !!fromPane, observer: observer, resize: resize, frame: null,
+    timer: setTimeout(clearClayControlActivity, message.terminal === false || ['review', 'running'].indexOf(message.phase) >= 0 ? 300000 : 6000) };
+  store.set({ clayControlActivity: activity }); layout();
+  if (previousRect && element.classList.contains('has-target') && !window.matchMedia('(prefers-reduced-motion: reduce)').matches) {
+    var next = element.getBoundingClientRect(), dx = previousRect.left - next.left, dy = previousRect.top - next.top;
+    if (Math.hypot(dx, dy) <= 600 && (dx || dy)) activity.animation = element.animate([
+      { transform: 'translate(' + dx + 'px, ' + dy + 'px)' }, { transform: 'translate(0, 0)' }
+    ], { duration: 140, easing: 'ease-out' });
+  }
+}
+export function handleClayControlActivity(message) {
+  if (message && message.type === 'clay_control_viewer') { store.set({ clayControlViewerRef: message.viewerRef }); return true; }
+  if (!message || message.type !== 'clay_control_activity') return false;
+  if (!validActivity(message) || message.recipientViewerRef !== store.get('clayControlViewerRef')) return true;
+  if (store.get('paneMode') && (message.sourceSessionOriginId !== store.get('sessionOriginId') || message.sourceSessionId !== store.get('activeSessionId') || message.mateId !== store.get('activeProjectMateId'))) return true;
+  if (!sourceMate(message)) return true;
+  if (forward(message)) return true;
+  acceptActivity(message);
+  return true;
+}
+function sourceMate(message) {
+  return (store.get('cachedMatesList') || []).find(function (mate) {
+    return !mate.archived && !mate.lifecycleDeletion && mate.id === message.mateId && mate.builtinKey === 'clay' && contextualMateStamp(mate) === message.sourceMateStamp;
+  });
+}
+function acceptActivity(message, fromPane) {
+  if ((message.ownerId || null) !== (store.get('myUserId') || null) || !store.get('connected')) return;
+  if (!sourceMate(message)) return;
+  var active = store.get('clayControlActivity');
+  var receipts = store.get('clayControlReceipts') || [];
+  var old = receipts.find(function (entry) { return entry.id === message.id; });
+  var order = store.get('clayControlOrder') || 0;
+  if (message.order < order || old && message.sequence <= old.sequence) return;
+  if (old && old.stopped) return;
+  receipts = receipts.filter(function (entry) { return entry.id !== message.id && Date.now() - entry.time < 300000; }).slice(-99);
+  receipts.push({ id: message.id, sequence: message.sequence, time: Date.now(), stopped: message.phase === 'clear' });
+  store.set({ clayControlOrder: message.order, clayControlReceipts: receipts });
+  if (message.phase === 'clear') { if (active && active.message.id === message.id) clearClayControlActivity(); return; }
+  var mate = (store.get('cachedMatesList') || []).find(function (item) { return !item.archived && !item.lifecycleDeletion && item.id === message.mateId && item.builtinKey === 'clay'; });
+  if (!mate) return;
+  render(message, mate, activityCopy(message), fromPane);
+}
+// Ordinary Mates retain their existing restricted navigation invocation feedback.
+export function showClayNavigationActivity(target, failed) {
+  if (!target || !target.contextualSourceMateId) return;
+  var mate = (store.get('cachedMatesList') || []).find(function (item) { return !item.archived && item.id === target.contextualSourceMateId; });
+  if (!mate) return;
+  render({ id: 'ordinary-navigation', target: Object.assign({ kind: 'session' }, target) }, mate,
+    failed ? 'I could not start that navigation.' : 'I’m opening the reviewed conversation.');
+}
+function stopPresentation() {
+  var active = store.get('clayControlActivity');
+  if (active) {
+    var receipts = (store.get('clayControlReceipts') || []).slice();
+    receipts.push({ id: active.message.id, sequence: Number.MAX_SAFE_INTEGER, stopped: true, time: Date.now() });
+    store.set({ clayControlReceipts: receipts.slice(-100) });
+  }
+  clearClayControlActivity();
+}
+export function initClayControlActivity() {
+  store.subscribe(function (value, previous) {
+    if (!value.connected && previous.connected) store.set({ clayControlOrder: 0, clayControlViewerRef: null });
+    if (!value.clayControlActivity) return;
+    if (!value.connected || value.myUserId !== previous.myUserId || value.currentSlug !== previous.currentSlug || value.activeSessionId !== previous.activeSessionId) { stopPresentation(); return; }
+    if (value.cachedMatesList !== previous.cachedMatesList) {
+      var actor = value.clayControlActivity.message.mateId;
+      if (actor && !sourceMate(value.clayControlActivity.message)) stopPresentation();
+    }
+    scheduleLayout();
+  });
+  ['resize', 'scroll'].forEach(function (name) { window.addEventListener(name, scheduleLayout, true); });
+  ['transitionrun', 'transitionend', 'transitioncancel', 'animationstart', 'animationend', 'animationcancel'].forEach(function (name) { document.addEventListener(name, scheduleLayout, true); });
+  document.addEventListener('visibilitychange', function () { if (document.hidden) stopPresentation(); });
+  document.addEventListener('click', function (event) {
+    if (event.target.closest('#generation-stop, #autonomous-run-stop, #send-btn.stop')) stopPresentation();
+  }, true);
+  window.addEventListener('message', function (event) {
+    if (event.origin !== location.origin || !event.data || event.data.type !== 'clay-control-presentation') return;
+    var host = document.getElementById('contextual-clay'), message = event.data.message;
+    if (!validActivity(message)) return;
+    var frame = host && Array.from(host.querySelectorAll('iframe[data-canonical="true"]')).find(function (item) { return item.contentWindow === event.source; });
+    var bridge = frame && frame.conversation;
+    var identity = bridge && bridge.document === frame.contentDocument && bridge.source === frame.contentWindow && bridge.identity();
+    if (!identity || message.phase !== 'clear' && (!identity.connected || !identity.available) || identity.ownerId !== store.get('myUserId') || identity.mateId !== message.mateId || identity.sessionId !== message.sourceSessionId || identity.sessionOriginId !== message.sourceSessionOriginId || identity.viewerRef !== message.recipientViewerRef || !sourceMate(message)) return;
+    if (new URL(frame.src, location.href).pathname !== '/p/' + encodeURIComponent(message.sourceSlug) + '/') return;
+    acceptActivity(message, true);
+  });
+  document.addEventListener('contextual-ask-stopped', stopPresentation, true);
+}
+
+export function withdrawPaneControlActivity() {
+  var message = store.get('clayControlForwarded');
+  if (message) forward(Object.assign({}, message, { phase: 'clear', sequence: message.sequence + 1 }));
+}

package/lib/public/modules/clay-control-copy.js

@@ -0,0 +1,36 @@
+var domains = { session: 'conversation', project: 'project', mate: 'Mate profile', knowledge: 'Mate Knowledge', records: 'project record', schedule: 'schedule', conversation: 'Mate conversation', workspace: 'workspace', screen: 'screen', assignment: 'Driver work', studio: 'Studio workbench' };
+var actions = {
+  rename: 'rename this conversation so it is easier to find', stop: 'request Stop so this work can settle',
+  model: 'change the model for this conversation', effort: 'adjust reasoning effort for this conversation',
+  permission: 'change the reviewed permission mode', delete: 'remove the reviewed item',
+  fork: 'fork the conversation at the reviewed checkpoint', rewind: 'restore the reviewed conversation checkpoint',
+  vendor: 'select the provider for this conversation', vendor_new_session: 'prepare a new conversation with the reviewed provider',
+  runtime: 'return this conversation to GUI chat', queue_add: 'queue the reviewed message for the Driver',
+  queue_edit: 'update the reviewed queued message', queue_cancel: 'cancel the reviewed queued message',
+  queue_reorder: 'reorder the reviewed message queue', navigate: 'open the reviewed conversation so we can continue there',
+  dismiss_notifications: 'dismiss the reviewed notifications', profile: 'update the reviewed Mate profile',
+  send: 'deliver the reviewed message to this Mate', assign: 'prepare the requested Driver work for your review', follow_up: 'prepare a follow-up for the existing Driver', document: 'open the requested document for editing', sketch: 'present the requested sketch', browser: 'operate the requested shared browser tab'
+};
+export function activityCopy(msg) {
+  var purpose = (['session', 'conversation', 'screen', 'mate', 'assignment', 'studio'].indexOf(msg.domain) >= 0 && Object.hasOwn(actions, msg.action) && actions[msg.action]) || 'apply the reviewed change to this ' + (domains[msg.domain] || 'item');
+  var endings = { review: 'I’m waiting for your review before I ' + purpose + '.', running: 'I’m working to ' + purpose + '.',
+    proposed: 'I saved the task proposal. Use Create task in Scheduled Tasks to create it; execution has not started.',
+    persisted: 'I saved the reviewed change.', completed: 'The service finished the reviewed change.', queued: 'I queued the request. The work has not finished yet.',
+    delivered: 'I sent the navigation request. I cannot yet confirm what is visible.', acknowledged: 'I started opening the conversation. Its visible result is still unconfirmed.',
+    rendered: 'The reviewed conversation is visibly open in the selected window.',
+    cancelled: 'I left the change unapplied.', failed: 'I could not finish this change. Please check the result before trying again.',
+    partial: 'Part of this change took effect, but the operation failed. Please check the result.', unknown: 'I cannot confirm the outcome. Please check before trying again.' };
+  if (msg.domain === 'assignment') { var work = { review: 'I prepared the Driver work. Please review its proposal before it starts.', queued: 'I submitted the approved Driver work for dispatch.', running: 'The Driver is working on the approved request.', completed: 'The Driver finished this request.', cancelled: 'I left this Driver request unapplied.', unknown: 'I cannot confirm the Driver outcome. Please inspect the work before retrying.' }; return work[msg.phase] || endings[msg.phase] || null; }
+  if (msg.domain === 'studio' && msg.phase === 'rendered') return 'The requested workbench content is visibly rendered in this window.';
+  if (msg.domain === 'studio' && msg.phase === 'render_unknown') return 'The service returned, but I could not confirm that the workbench content is visible.';
+  if (msg.domain === 'studio' && msg.phase === 'delivered') return 'I sent the requested content to the workbench. Its visible result is unconfirmed.';
+  if (msg.domain === 'studio' && msg.phase === 'completed') return 'I finished the requested workbench operation.';
+  return endings[msg.phase] || null;
+}
+export function validActivity(msg) {
+  return msg && msg.version === 1 && typeof msg.id === 'string' && /^activity:[\w-]{36}$/.test(msg.id) &&
+    typeof msg.sourceSessionOriginId === 'string' && !!msg.sourceSessionOriginId && typeof msg.sourceMateStamp === 'string' &&
+    typeof msg.recipientViewerRef === 'string' && /^viewer:[\w-]{36}$/.test(msg.recipientViewerRef) && Number.isSafeInteger(msg.sourceQueryGeneration) &&
+    Number.isSafeInteger(msg.order) && msg.order > 0 && Number.isSafeInteger(msg.sequence) && msg.sequence > 0 &&
+    (msg.phase === 'clear' || Object.hasOwn(domains, msg.domain) && !!activityCopy(msg));
+}

package/lib/public/modules/clay-control-detail-targets.js

@@ -0,0 +1,44 @@
+import { visibleTarget } from './clay-control-target-visibility.js';
+import { store } from './store.js';
+
+function node(selector, id, revision, field) {
+  return Array.from(document.querySelectorAll(selector)).find(function (item) {
+    return item.dataset[field] === id && item.dataset.controlRevision === String(revision) && item.dataset.controlRuntime === store.get('controlRuntimeId');
+  });
+}
+// Fixed object adapters verify authoritative client state before locating rendered identities.
+export function detailedControlTarget(target) {
+  if (target.kind === 'notifications') {
+    var notifications = store.get('clayControlNotifications') || [];
+    var nodes = target.items.map(function (item) {
+      if (!notifications.some(function (saved) { return saved.id === item.id && saved.controlRevision === item.revision; })) return null;
+      return Array.from(document.querySelectorAll('.notif-banner[data-notif-id]')).find(function (el) { return el.dataset.notifId === item.id && el.dataset.controlRevision === item.revision; });
+    });
+    return nodes.every(function (item) { return visibleTarget(item); }) ? nodes.length === 1 ? nodes[0] : nodes[0].parentElement : null;
+  }
+  if (target.projectSlug !== store.get('currentSlug') || target.runtimeId !== store.get('controlRuntimeId')) return null;
+  if (target.kind === 'git-set') {
+    var git = store.get('clayControlGitView');
+    if (!git || git.repository !== target.repository || git.runtimeId !== target.runtimeId || git.projectSlug !== target.projectSlug) return null;
+    var rows = target.files.map(function (file) { return git.files.some(function (saved) { return saved.path === file.path && saved.revision === file.revision; }) && node('.git-file-row', file.path, file.revision, 'controlGitPath'); });
+    if (!rows.every(function (item) { return visibleTarget(item); })) return null;
+    return document.querySelector('#git-panel-body');
+  }
+  if (target.kind !== 'knowledge' || !target.objectId) return null;
+  var main = (store.get('mateKnowledgeWorkspaces') || {})[target.projectSlug];
+  if (!main) return null;
+  if (target.object === 'document') {
+    var file = main.files.concat(main.deletedFiles || []).find(function (item) { return !item.common && item.id === target.objectId && item.name === target.name && String(item.revision) === target.revision; });
+    return file && node('.knowledge-file-row', 'local:' + file.id, target.revision, 'openDocument');
+  }
+  if (target.object === 'database') {
+    var database = main.files.find(function (item) { return !item.common && item.id === target.databaseId && String(item.revision) === target.revision; });
+    return database && node('.knowledge-file-row', 'local:' + target.databaseId, target.revision, 'openDocument');
+  }
+  var db = ((store.get('mateKnowledgeDatabaseWorkspaces') || {})[target.projectSlug] || {}).databases;
+  var view = db && db[target.databaseId];
+  if (!view || !view.database || String(view.database.revision) !== target.databaseRevision) return null;
+  if (target.object === 'database') return node('.knowledge-file-row', 'local:' + target.databaseId, target.revision, 'openDocument');
+  var record = (view.records || []).concat(view.recordDetail && view.recordDetail.record || []).find(function (item) { return item.id === target.objectId && String(item.revision) === target.revision; });
+  return record && Array.from(document.querySelectorAll('[data-db-record][data-db-database]')).find(function (item) { return item.dataset.dbRecord === record.id && item.dataset.dbDatabase === target.databaseId && item.dataset.controlRevision === target.revision && item.dataset.controlRuntime === target.runtimeId; });
+}

package/lib/public/modules/clay-control-object-targets.js

@@ -0,0 +1,52 @@
+import { studioControlTarget } from './clay-studio-render.js';
+import { store } from './store.js';
+import { detailedControlTarget } from './clay-control-detail-targets.js';
+import { contextualMateStamp } from './contextual-mate-identity.js';
+
+// Server projections identify the object; fixed adapters only locate its rendered view.
+export function objectControlTarget(target) {
+  if (target.kind === 'surface') return studioControlTarget(target);
+  var detailed = detailedControlTarget(target);
+  if (['knowledge', 'notifications', 'git-set'].indexOf(target.kind) >= 0) return detailed;
+  if (target.kind === 'mate') {
+    var mate = (store.get('cachedMatesList') || []).find(function (item) { return item.id === target.mateId && !item.archived && !item.lifecycleDeletion && contextualMateStamp(item) === target.mateStamp; });
+    if (!mate) return null;
+    return Array.from(document.querySelectorAll('.icon-strip-project-mate[data-mate-id], .icon-strip-brand')).find(function (item) {
+      return item.dataset.mateId === mate.id && item.dataset.controlMateStamp === target.mateStamp || mate.builtinKey === 'clay' && item.classList.contains('icon-strip-brand');
+    });
+  }
+  var project = (store.get('projectsHubList') || []).find(function (item) { return item.slug === target.projectSlug && item.controlRuntimeId === target.runtimeId && item.contentAccess !== false; });
+  if (target.kind === 'project') {
+    if (!project) return null;
+    return Array.from(document.querySelectorAll('#icon-strip-projects .icon-strip-item[href]')).find(function (item) { return item.dataset.controlRuntime === target.runtimeId && new URL(item.href, location.href).pathname === '/p/' + encodeURIComponent(target.projectSlug) + '/'; });
+  }
+  if (target.projectSlug !== store.get('currentSlug') || target.runtimeId !== store.get('controlRuntimeId')) return null;
+  if (target.kind === 'record') {
+    var selector = target.area === 'issues' ? '.issue-row[data-open-issue], .issue-detail[data-control-ref]' : '.project-log-row[data-ref]';
+    return Array.from(document.querySelectorAll(selector)).find(function (item) {
+      return (item.dataset.openIssue || item.dataset.controlRef || item.dataset.ref) === target.ref && item.dataset.controlRevision === target.revision && item.dataset.controlRuntime === target.runtimeId;
+    });
+  }
+  if (target.kind === 'file') {
+    var file = store.get('clayControlFileView');
+    if (!file || file.path !== target.path || file.revision !== target.revision || file.projectSlug !== target.projectSlug || file.runtimeId !== target.runtimeId) return null;
+    return document.querySelector('#file-viewer .file-viewer-header');
+  }
+  if (target.kind === 'git') {
+    var git = store.get('clayControlGitView');
+    if (!git || git.projectSlug !== target.projectSlug || git.runtimeId !== target.runtimeId || git.repository !== target.repository || !git.files.some(function (item) { return item.path === target.path && item.revision === target.revision; })) return null;
+    return Array.from(document.querySelectorAll('.git-file-row[data-control-git-path]')).find(function (item) { return item.dataset.controlGitPath === target.path && item.dataset.controlRevision === target.revision && item.dataset.controlRuntime === target.runtimeId; });
+  }
+  if (target.kind === 'terminal') {
+    var terminal = (store.get('clayControlTerminalViews') || []).find(function (item) { return item.id === target.id && item.identity === target.identity && item.revision === target.revision && item.runtimeId === target.runtimeId; });
+    if (!terminal) return null;
+    return Array.from(document.querySelectorAll('.terminal-tab[data-control-terminal-id]')).find(function (item) { return item.dataset.controlTerminalId === String(target.id) && item.dataset.controlRuntime === target.runtimeId; });
+  }
+  if (target.kind === 'schedule') {
+    if (target.sessionId !== store.get('activeSessionId') || target.sessionOriginId !== store.get('sessionOriginId')) return null;
+    var queue = store.get('pendingMessageQueue');
+    var logical = queue && (queue.items || []).some(function (item) { return item.schedule && item.schedule.logicalScheduleId === target.id && item.schedule.logicalRevision === target.revision; });
+    return Array.from(document.querySelectorAll('.scheduled-task-row[data-task-id], .pending-message-chip[data-control-schedule-id]')).find(function (item) { return (item.dataset.taskId === target.id || logical && item.dataset.controlScheduleId === target.id) && item.dataset.controlRevision === target.revision && item.dataset.controlRuntime === target.runtimeId; });
+  }
+  return null;
+}

package/lib/public/modules/clay-control-target-visibility.js

@@ -0,0 +1,12 @@
+export function visibleTarget(element) {
+  if (!element || !element.isConnected || element.closest('[hidden], [inert], [aria-hidden="true"]')) return false;
+  var rect = element.getBoundingClientRect(), style = getComputedStyle(element);
+  if (style.visibility !== 'visible' || Number(style.opacity) === 0 || !rect.width || !rect.height || rect.left < 0 || rect.top < 0 || rect.right > innerWidth || rect.bottom > innerHeight) return false;
+  for (var parent = element.parentElement; parent; parent = parent.parentElement) {
+    if (Number(getComputedStyle(parent).opacity) === 0) return false;
+  }
+  return [rect.left + 2, rect.left + rect.width / 2, rect.right - 2].every(function (x) {
+    var hit = document.elementFromPoint(x, rect.top + rect.height / 2);
+    return hit && element.contains(hit);
+  });
+}

package/lib/public/modules/clay-control-targets.js

@@ -0,0 +1,44 @@
+import { visibleTarget } from './clay-control-target-visibility.js';
+export { visibleTarget };
+import { objectControlTarget } from './clay-control-object-targets.js';
+import { store } from './store.js';
+
+// Stable product adapters only. Activity data never supplies a CSS selector.
+export function controlTarget(target) {
+  if (!target) return null;
+  if (target.kind !== 'session') { var object = objectControlTarget(target); return visibleTarget(object) ? object : null; }
+  if (target.projectSlug !== store.get('currentSlug')) return null;
+  if (target.kind === 'session' && Number.isSafeInteger(target.sessionId) && typeof target.sessionOriginId === 'string' && target.sessionOriginId) {
+    return Array.from(document.querySelectorAll('.session-item[data-session-id]')).find(function (row) {
+      return Number(row.dataset.sessionId) === target.sessionId && row.dataset.controlSessionOrigin === target.sessionOriginId && visibleTarget(row);
+    }) || null;
+  }
+  return null;
+}
+
+function overlaps(a, b) { return a.left < b.right && a.right > b.left && a.top < b.bottom && a.bottom > b.top; }
+export function activityPlacement(row, width, height, obstacles) {
+  var margin = 12, rect = row && row.getBoundingClientRect();
+  var candidates = [];
+  if (rect) {
+    // Keep the cursor shaft seated in the identity pill in either vertical direction.
+    candidates.push({ left: rect.right + 8, top: rect.top + rect.height / 2 + 20, tipX: rect.right - 2, tipY: rect.top + rect.height / 2 });
+    candidates.push({ left: rect.right + 8, top: rect.top + rect.height / 2 - 34, tipX: rect.right - 2, tipY: rect.top + rect.height / 2, flip: true });
+    candidates.push({ left: rect.left - width - 8, top: rect.top + rect.height / 2 + 20, tipX: rect.left + 2, tipY: rect.top + rect.height / 2, reverse: true });
+  }
+  candidates.push({ left: innerWidth - width - margin, top: 64 });
+  candidates.push({ left: margin, top: 64 });
+  candidates.push({ left: innerWidth - width - margin, top: innerHeight - height - 80 });
+  candidates.push({ left: (innerWidth - width) / 2, top: 64 });
+  obstacles.slice(0, 12).forEach(function (obstacle) {
+    candidates.push({ left: innerWidth - width - margin, top: obstacle.bottom + 8 });
+    candidates.push({ left: margin, top: obstacle.bottom + 8 });
+    candidates.push({ left: (innerWidth - width) / 2, top: obstacle.bottom + 8 });
+  });
+  return candidates.find(function (candidate) {
+    var box = { left: candidate.left, right: candidate.left + width, top: candidate.top, bottom: candidate.top + height };
+    if (box.left < margin || box.right > innerWidth - margin || box.top < margin || box.bottom > innerHeight - margin) return false;
+    if (rect && overlaps(box, rect)) return false;
+    return !obstacles.some(function (obstacle) { return overlaps(box, obstacle); });
+  }) || null;
+}

package/lib/public/modules/clay-log-links.js

@@ -1,10 +1,33 @@
 import { enhanceClayIssueLinks, isExactClayIssueReference } from './clay-issue-links.js';
 import { enhanceGithubLinks } from './github-links.js';
+import { escapeHtml } from './utils.js';
 
 export function renderClayRecordLink(href, text) {
+  if (isExactClaySessionReference(href)) return renderClaySessionLink(href.trim(), text);
   if (!isExactClayLogReference(href) && !isExactClayIssueReference(href)) return null;
   return '<a href="#" data-clay-record-ref="' + href.trim() + '">' + text + '</a>';
 }
+
+export function isExactClaySessionReference(text) {
+  return parseClaySessionReference(text) !== null;
+}
+
+export function renderClaySessionLink(ref, text) {
+  var parsed = parseClaySessionReference(ref);
+  if (!parsed) return null;
+  var label = text ? String(text).trim() : "";
+  var safeLabel = escapeHtml(label).replace(/"/g, "&quot;");
+  var entryAttr = parsed.entryIndex === null ? "" : ' data-session-entry-index="' + parsed.entryIndex + '"';
+  return '<button type="button" class="clayos-session-link clayos-record-link" data-session-ref="' + parsed.ref + '"' + entryAttr + ' aria-label="Open session' + (safeLabel ? " from " + safeLabel : "") + '"><span>Session</span>' + (safeLabel ? '<small>' + safeLabel + '</small>' : '') + '</button>';
+}
+
+export function parseClaySessionReference(text) {
+  var match = /^((?:session:[A-Za-z0-9_-]{24}))(?:#entry-([0-9]+))?$/.exec((text || "").trim());
+  if (!match) return null;
+  var entryIndex = match[2] === undefined ? null : Number(match[2]);
+  if (entryIndex !== null && (!Number.isSafeInteger(entryIndex) || entryIndex < 0)) return null;
+  return { ref: match[1], entryIndex: entryIndex };
+}
 export function parseClayLogReferences(text) {
   var pattern = /\[clayos\/(log:[A-Za-z0-9_-]{24})(?:\s+[\u2014-]\s+([^\]\n]{1,80}))?\]|(^|[^A-Za-z0-9_/:])(log:[A-Za-z0-9_-]{24})(?![A-Za-z0-9_-])/g;
   var results = [];

package/lib/public/modules/clay-navigation-render.js

@@ -0,0 +1,52 @@
+import { store } from './store.js';
+import { getWs } from './ws-ref.js';
+
+function visible(element) {
+  if (!element || !element.isConnected || element.closest('[hidden], [inert], [aria-hidden="true"]')) return false;
+  var box = element.getBoundingClientRect(), style = getComputedStyle(element);
+  if (style.visibility !== 'visible' || Number(style.opacity) === 0 || box.width <= 0 || box.height <= 0) return false;
+  for (var parent = element.parentElement; parent; parent = parent.parentElement) if (getComputedStyle(parent).visibility !== 'visible' || Number(getComputedStyle(parent).opacity) === 0) return false;
+  var left = Math.max(0, box.left), right = Math.min(innerWidth, box.right), top = Math.max(0, box.top), bottom = Math.min(innerHeight, box.bottom);
+  return right > left && bottom > top && [0.2, 0.5, 0.8].some(function (x) {
+    return [0.2, 0.5, 0.8].some(function (y) { var hit = document.elementFromPoint(left + (right - left) * x, top + (bottom - top) * y); return hit && element.contains(hit); });
+  });
+}
+// Bounded evidence from the exact authenticated document, never navigation receipt.
+export function observeNavigationRendering(message, socket) {
+  var previous = store.get('clayNavigationRendering');
+  if (previous) previous.finish(false);
+  var target = message.target, owner = store.get('myUserId'), settled = false, stable = 0, frame, timer;
+  function finish(rendered) {
+    if (settled) return;
+    settled = true; cancelAnimationFrame(frame); clearTimeout(timer); unsubscribe();
+    document.removeEventListener('visibilitychange', hidden); document.removeEventListener('click', stop, true);
+    if (store.get('clayNavigationRendering') === attempt) store.set({ clayNavigationRendering: null });
+    if (getWs() === socket && socket.readyState === 1) socket.send(JSON.stringify({ type: 'clay_navigation_rendered', deliveryId: message.deliveryId,
+      renderToken: message.renderToken, visible: rendered, projectSlug: target.projectSlug, sessionId: target.sessionId,
+      sessionOriginId: target.sessionOriginId, surface: 'conversation', entryIndex: target.entryIndex }));
+  }
+  var attempt = { finish: finish };
+  store.set({ clayNavigationRendering: attempt });
+  function hidden() { if (document.hidden) finish(false); }
+  var unsubscribe = store.subscribe(function (value, old) {
+    if (!value.connected || value.myUserId !== owner || getWs() !== socket || value.currentSlug !== old.currentSlug && value.currentSlug !== target.projectSlug || value.activeSessionId !== old.activeSessionId && value.currentSlug === target.projectSlug && value.activeSessionId !== target.sessionId) finish(false);
+  });
+  function stop(event) { if (event.target.closest('#generation-stop, #autonomous-run-stop, #send-btn.stop')) finish(false); }
+  document.addEventListener('click', stop, true);
+  document.addEventListener('visibilitychange', hidden);
+  timer = setTimeout(function () { finish(false); }, Math.max(0, Math.min(5000, message.renderDeadline - Date.now())));
+  function inspect() {
+    if (settled) return;
+    if (document.hidden || getWs() !== socket || !store.get('connected') || store.get('myUserId') !== owner) { finish(false); return; }
+    var transcript = document.getElementById('messages');
+    var exact = store.get('currentSlug') === target.projectSlug && store.get('activeSessionId') === target.sessionId && store.get('sessionOriginId') === target.sessionOriginId &&
+      !store.get('paneMode') && !store.get('dmMode') && !store.get('homeShellVisible') && !store.get('replayingHistory') && transcript &&
+      transcript.dataset.controlSessionId === String(target.sessionId) && transcript.dataset.controlSessionOrigin === target.sessionOriginId && visible(transcript);
+    if (exact && target.entryIndex !== undefined) exact = transcript.dataset.controlHistoryRevision === target.historyRevision && Array.from(transcript.querySelectorAll('[data-history-index], [data-history-indexes]')).some(function (item) {
+      return (item.dataset.historyIndex === String(target.entryIndex) || (item.dataset.historyIndexes || '').split(',').indexOf(String(target.entryIndex)) >= 0) && visible(item);
+    });
+    stable = exact ? stable + 1 : 0;
+    if (stable >= 2) finish(true); else frame = requestAnimationFrame(inspect);
+  }
+  frame = requestAnimationFrame(inspect);
+}

package/lib/public/modules/clay-owner-navigation.js

@@ -0,0 +1,33 @@
+import { observeNavigationRendering } from './clay-navigation-render.js';
+import { showClayNavigationActivity, clearClayControlActivity } from './clay-control-activity.js';
+import { store } from './store.js';
+import { getWs } from './ws-ref.js';
+import { navigateToSession } from './command-palette.js';
+function context() {
+  return JSON.stringify([store.get('currentSlug'), store.get('activeSessionId'), store.get('dmMode'), store.get('homeShellVisible'), store.get('homeChatMateId'), store.get('homeChatSessionId'), store.get('homeSubSurface'), (store.get('contextualClay') || {}).mode]);
+}
+export function handleOwnerNavigation(msg) {
+  if (msg.type !== 'clay_navigation_offer' && msg.type !== 'clay_navigation_apply') return false;
+  var ws = getWs();
+  if (!ws || ws.readyState !== 1) return true;
+  if (msg.type === 'clay_navigation_offer') {
+    if (document.hidden || store.get('paneMode')) return true;
+    store.set({ clayNavigationOffer: { id: msg.deliveryId, context: context(), socket: ws } });
+    ws.send(JSON.stringify({ type: 'clay_navigation_claim', deliveryId: msg.deliveryId }));
+    return true;
+  }
+  var offer = store.get('clayNavigationOffer');
+  store.set({ clayNavigationOffer: null });
+  var accepted = offer && offer.id === msg.deliveryId && offer.socket === ws && offer.context === context() && !document.hidden && !store.get('paneMode');
+  var status = 'refused';
+  if (accepted && msg.target && typeof msg.target.projectSlug === 'string' && Number.isSafeInteger(msg.target.sessionId)) {
+    try {
+      showClayNavigationActivity(msg.target, false); navigateToSession(msg.target, null, msg.target.entryIndex); status = 'accepted';
+    } catch (error) { showClayNavigationActivity(msg.target, true); status = 'failed'; }
+  }
+  if (status === 'refused') clearClayControlActivity();
+  // This acknowledges navigator invocation only. Rendering may finish after reconnect.
+  if (ws.readyState === 1) ws.send(JSON.stringify({ type: 'clay_navigation_ack', deliveryId: msg.deliveryId, status: status }));
+  if (status === 'accepted') observeNavigationRendering(msg, ws);
+  return true;
+}

package/lib/public/modules/clay-session-links.js

@@ -0,0 +1,31 @@
+import { parseClaySessionReference, renderClaySessionLink } from './clay-log-links.js';
+
+// The prefix is a display compatibility label, never a navigation target.
+var citationPattern = /\[([A-Za-z0-9][A-Za-z0-9_-]{0,79})\/(session:[A-Za-z0-9_-]{24}(?:#entry-[0-9]+)?)(?:\s+[\u2014-]\s+([^\]\n]{1,80}))?\]/g;
+function matches(text) {
+  var pattern = new RegExp(citationPattern.source, 'g'), results = [], match;
+  while ((match = pattern.exec(text))) if (parseClaySessionReference(match[2])) results.push({ start: match.index, end: pattern.lastIndex, prefix: match[1], ref: match[2], label: match[3] || '' });
+  return results;
+}
+function button(match) {
+  var template = document.createElement('template');
+  template.innerHTML = renderClaySessionLink(match.ref, match.label);
+  return template.content.firstElementChild;
+}
+export function enhanceSessionCitations(root) {
+  // Historical assistants sometimes wrapped a whole project-labelled citation
+  // in inline code. Only that complete legacy token is a compatibility citation.
+  // Canonical code samples, mixed inline code and all fenced code stay literal.
+  if (root.closest('.msg-assistant')) root.querySelectorAll('code').forEach(function (code) {
+    if (code.closest('pre, a, button')) return;
+    var text = code.textContent || '', found = matches(text);
+    if (found.length === 1 && found[0].prefix !== 'clayos' && found[0].start === 0 && found[0].end === text.length) code.replaceWith(button(found[0]));
+  });
+  var walker = document.createTreeWalker(root, NodeFilter.SHOW_TEXT), nodes = [], node;
+  while ((node = walker.nextNode())) if (node.parentElement && !node.parentElement.closest('code, pre, a, button') && matches(node.nodeValue || '').length) nodes.push(node);
+  nodes.forEach(function (node) {
+    var text = node.nodeValue || '', fragment = document.createDocumentFragment(), offset = 0;
+    matches(text).forEach(function (match) { fragment.appendChild(document.createTextNode(text.slice(offset, match.start))); fragment.appendChild(button(match)); offset = match.end; });
+    fragment.appendChild(document.createTextNode(text.slice(offset))); node.replaceWith(fragment);
+  });
+}

package/lib/public/modules/clay-studio-bridge.js

@@ -0,0 +1,20 @@
+import { adoptDocumentSource, presentedDocument, initDocumentSource } from './clay-studio-document.js';
+import { acceptStudioForward, trustedStudioFrame, initStudioReceipts } from './clay-studio-render.js';
+import { presentMarkdownEdit, handleFileChanged } from './filebrowser.js';
+import { openWireframe } from './wireframe-workbench.js';
+
+export function initStudioBridge() {
+  initStudioReceipts(); initDocumentSource();
+  window.addEventListener('message', function (event) {
+    var data = event.data;
+    if (event.origin === location.origin && data && data.type === 'clay-studio-document-update' && data.message) {
+      var view = presentedDocument(data.message.path);
+      if (view && view.source === event.source && view.descriptor.token === data.token) handleFileChanged(data.message, view);
+      return;
+    }
+    if (!data || ['clay-pane-present-markdown', 'clay-pane-present-wireframe'].indexOf(data.type) < 0 || !data.message || !data.message.controlPresentation) return;
+    if (!trustedStudioFrame(event, data) || !acceptStudioForward(event, data)) return;
+    if (data.type === 'clay-pane-present-markdown') { adoptDocumentSource(event, data, trustedStudioFrame(event, data)); presentMarkdownEdit(data.message); }
+    else openWireframe(data.message);
+  });
+}