@panphora/clayjs 1.5.3 → 1.6.0

package/src/plugins/ai-edit.js

@@ -3,11 +3,10 @@
  *
  * Direct editing stays primary: text units carry editmode:contenteditable, so a
  * click places the caret and a figure keeps its own interactivity. This adds the
- * comment box on demand: a floating chip near the hovered unit, Cmd+K for the unit
- * holding the caret (the selection rides along as a quote), a click on bare section
- * padding, or the fixed bottom-right bubble for the whole document. Units resolve to
- * the nearest h1-h6/p/figure inside a [data-edit-id] section, falling back to the
- * section itself.
+ * comment box on demand: Cmd+J (Ctrl+J elsewhere) or the small chip at the end of a
+ * selection, for the block around it; on pages built from [data-edit-id] sections,
+ * also a hover chip near the unit, a click on bare section padding, and the fixed
+ * bottom-right bubble for the whole document.
  *
  * The request leaves as a named helper request on the wire
  * (`clay.wire.send(payload, { helper: "ai-edit" })`) and comes back as the edited
@@ -15,9 +14,10 @@
  * writes nothing: this page morphs the result in and Keep saves it through
  * `clay.save()`, exactly as before.
  *
- * Dormant unless the host lists a ready `ai-edit` helper. On HTML Clay, or with the
- * desktop toggle off, `clay.wire.helpers()` never lists one and nothing is built at
- * all: the page is then just a page.
+ * Dormant unless the host lists an `ai-edit` helper: then nothing is built and the
+ * page is just a page. Listed as unavailable (the host's toggle is off), the
+ * shortcut opens the panel with a note and no Send, and the state is checked again
+ * each time the panel opens.
  *
  * The bus version previewed the reply as it streamed. The wire carries status lines
  * only — replaceable progress, capped and droppable — so the page shows throttled
@@ -39,14 +39,23 @@ import { HyperMorph } from "../vendor/hyper-morph.vendor.js";
 import { mergeTagRecognizers } from "../sync/merge-tags.js";
 import Mutation from "../lib/mutation.js";
 import { isEditMode } from "../core/is-edit-mode.js";
+import { holdAllSaves, releaseAllSaves } from "../core/save.js";
 import { STRIP_FROM_SAVE } from "../lib/region-policy.js";
 import { enableContentEditable } from "../core/admin-contenteditable.js";
 import onDomReady from "../lib/dom-ready.js";
 import wire from "./wire.js";
+import { set } from "../lib/hostile-css.js";
+import { bevelBox, bevelButton, bevelSurface, bevelText, bevelInput, pageScheme, setShown, RUNTIME_ONLY } from "../ui/bevel-controls.js";
+import { TOKENS, FONT_SANS, FONT_MONO, SHADOW } from "../ui/bevel.js";
 
 const HELPER = "ai-edit";
 const UNIT_SELECTOR = "h1,h2,h3,h4,h5,h6,p,figure";
-const RUNTIME_ONLY = "no-save no-watch no-snapshot";
+// Outside [data-edit-id] sections: the nearest text block that holds the whole
+// selection, else the nearest container that does. A selection across top-level blocks
+// edits the whole page.
+const BLOCK_SELECTOR = "p,h1,h2,h3,h4,h5,h6,li,dt,dd,blockquote,pre,figcaption,td,th";
+const CONTAINER_SELECTOR = "section,article,aside,header,footer,nav,main,div,ul,ol,dl,table,figure,form";
+const NOT_TEXT = "script,style,template,textarea,input,select,button,iframe,svg,math";
 // The request ceiling, kept below the host's 1 MiB envelope so the refusal happens
 // here, where the message can say what to do about it.
 const MAX_PAYLOAD_BYTES = 900 * 1024;
@@ -54,17 +63,30 @@ const TOO_LARGE = "This section is too large for AI editing; select a smaller pa
 
 let requestCounter = 0;
 let session = null; // one edit at a time
-let panel, ring, textarea, quoteEl, statusEl, warningsEl, chip, docBubble;
+let panel, ring, textarea, statusEl, warningsEl, pointer, chip, docBubble;
 let buttons = {};
 let anchorEl = null;    // element the panel is currently anchored to
 let chipTarget = null;  // unit the hover chip currently points at
 let chipHideTimer = null;
+let pendingSelection; // { text, start, end } for the open panel, or undefined
+
+let chipSelection;       // the selection the chip was raised for; undefined for the hover chip
+let selectionTimer = null;
+let anchorRange = null;  // the selection the open panel was raised for
+let returnFocus = null;  // where focus goes back to when the panel closes
+let helperState = null;  // "ready" or "unavailable"
+
+const HIGHLIGHT = 'clay-ai-edit';
+const OFF_MESSAGE = 'AI editing is turned off. Turn it on from the app’s menu.';
 
 // ---------------------------------------------------------------- transport
 
-async function available() {
+// The helper's state as this host lists it: "ready", "unavailable" (listed, but the
+// host's toggle is off), or null when there is no ai-edit helper to talk to.
+async function helperStateNow() {
   const list = await wire.helpers();
-  return list.some(h => h.name === HELPER && h.state === "ready");
+  const helper = list.find(h => h.name === HELPER);
+  return helper && (helper.state === 'ready' || helper.state === 'unavailable') ? helper.state : null;
 }
 
 // ---------------------------------------------------------------- observers (undo/autosave)
@@ -94,18 +116,52 @@ function editLabel(el) {
   const own = el.getAttribute('data-edit-id');
   if (own) return own;
   const section = el.closest('[data-edit-id]');
-  return (section ? section.getAttribute('data-edit-id') + ' \u203a ' : '') + el.tagName.toLowerCase();
+  if (!section) return el.id ? '#' + el.id : el.tagName.toLowerCase();
+  return section.getAttribute('data-edit-id') + ' \u203a ' + el.tagName.toLowerCase();
 }
 
-function quoteFromSelection(scope) {
+function liveRange() {
   const selection = window.getSelection();
-  if (!selection || selection.isCollapsed) return undefined;
-  const text = selection.toString().trim();
-  if (!text) return undefined;
-  let node = selection.getRangeAt(0).commonAncestorContainer;
+  if (!selection || selection.rangeCount === 0 || selection.isCollapsed) return null;
+  return selection.getRangeAt(0);
+}
+
+// The element a selection edits. Section pages keep their unit rules; everywhere
+// else it is the block around the whole selection, so a backward selection and a
+// forward one land on the same element.
+function targetFromRange(range) {
+  let node = range.commonAncestorContainer;
   if (node.nodeType !== 1) node = node.parentElement;
-  if (scope && scope !== document.body && !scope.contains(node)) return undefined;
-  return text.length > 400 ? text.slice(0, 400) + '\u2026' : text;
+  if (!node || !document.body.contains(node)) return null;
+  // A selection across top-level blocks has only the page around it.
+  if (node === document.body) return document.body;
+  if (node.closest('[data-clay-ai-edit]') || node.closest(STRIP_FROM_SAVE) || node.closest(NOT_TEXT)) return null;
+  if (node.closest('[data-edit-id]')) return unitFrom(node);
+  const target = node.closest(BLOCK_SELECTOR) || node.closest(CONTAINER_SELECTOR);
+  return target && target !== document.body ? target : null;
+}
+
+// The selected text, whole, with its character offsets inside the target's text,
+// so a phrase that appears twice is unambiguous.
+function selectionIn(range, target) {
+  if (!range || !target || !target.contains(range.commonAncestorContainer)) return undefined;
+  const text = range.toString();
+  if (!text.trim()) return undefined;
+  const before = document.createRange();
+  before.selectNodeContents(target);
+  before.setEnd(range.startContainer, range.startOffset);
+  const start = before.toString().length;
+  return { text, start, end: start + text.length };
+}
+
+function quoteFromSelection(scope) {
+  const range = liveRange();
+  if (!range) return undefined;
+  if (scope === document.body) {
+    const text = range.toString();
+    return text.trim() ? { text, start: undefined, end: undefined } : undefined;
+  }
+  return selectionIn(range, scope);
 }
 
 function strippedBodyHTML() {
@@ -128,9 +184,11 @@ function morphTo(el, content, scripts) {
 // against the snapshot the model saw, so data the user changed mid-flight survives
 // the reply. Rewinds must restore the snapshot exactly, so they disable merging.
 function sessionMorph(s, content, { rewind = false } = {}) {
+  // handle:false: a reply's scripts never run, so the preview cannot execute code
+  // before Keep, and neither can a rewind.
   const scripts = rewind
-    ? { merge: false }
-    : { mergeBase: s.snapshot, mergeTags: mergeTagRecognizers };
+    ? { merge: false, handle: false }
+    : { mergeBase: s.snapshot, mergeTags: mergeTagRecognizers, handle: false };
   if (s.docMode) {
     if (typeof content === 'string') {
       // Parse to an element ourselves: hyper-morph parses a body string into a
@@ -177,9 +235,11 @@ function newSession(el, comment, quote) {
   // Context refs are @tokens containing a dot or slash (@notes.md, @src/x.js). Bare
   // @words are not refs: a leading one is an engine token (@fable, @codex — routed
   // helper-side), and mid-text ones are prose.
-  const contextRefs = [...comment.matchAll(/@([\w.-]*[/.][\w./-]*)/g)]
-    .map(m => m[1])
-    .filter(ref => ref !== 'page');
+  // The @ has to start a word, so an email address or a URL is prose too.
+  const contextRefs = [...comment.matchAll(/(?<![\w\u00C0-\u024F.@\/:-])@([\w.-]*[/.][\w./-]*)/g)]
+    .map(m => m[1].replace(/\.+$/, '')) // a sentence's full stop is not part of the name
+    .filter(ref => ref !== 'page')
+    .filter(ref => /[/.]/.test(ref));
   const elementHTML = docMode ? strippedBodyHTML() : el.outerHTML;
   const payload = {
     id: 'req-' + Date.now().toString(36) + '-' + (++requestCounter),
@@ -189,10 +249,13 @@ function newSession(el, comment, quote) {
     comment,
     contextRefs
   };
-  if (quote) payload.quote = quote;
+  if (quote) {
+    payload.quote = quote.text;
+    if (Number.isInteger(quote.start)) payload.selection = { start: quote.start, end: quote.end };
+  }
   // Document mode reads the live page itself, and every other @page request reads
   // the file from disk: the plugin saves first, then asks for it by flag.
-  if (!docMode && /@page\b/.test(comment)) payload.page = true;
+  if (!docMode && /(?<![\w\u00C0-\u024F.@\/:-])@page(?![\w\/-]|\.\w)/.test(comment)) payload.page = true;
   return {
     id: payload.id,
     el,
@@ -223,7 +286,7 @@ async function sendRequest(el, comment, quote) {
   setStatus('sending\u2026');
   showButtons('stop');
   // @page reads the file the host has on disk, so the page has to be on disk first.
-  if (/@page\b/.test(comment) && !session.docMode) await window.clay.save();
+  if (session.payload.page) await window.clay.save();
   if (!session) return; // cancelled while saving
   // The host owns the deadline; this side only renders. A named request defaults to
   // `document: "none"`, so nothing here asks anyone to write the file.
@@ -241,6 +304,63 @@ async function sendRequest(el, comment, quote) {
   else onError(outcome.error || 'the helper reported an error');
 }
 
+// What a reply may not add: anything that runs code. Each part is counted, and the
+// reply is refused when it holds more of any part than the element the model was
+// given, so a page's own scripts and handlers are not a reason to refuse an edit
+// near them, while a copied handler or a changed script is.
+const ACTIVE_ATTR = /^(on|hx-on|x-|@|:|v-on:|v-bind:|data-on[-:])/;
+const ACTIVE_TAGS = new Set(['iframe', 'frame', 'object', 'embed', 'base', 'link']);
+
+// URL parsing removes tab, CR and LF anywhere and controls and spaces at the start,
+// so "java&#9;script:" is still a javascript: URL.
+function isScriptURL(value) {
+  const url = value.replace(/[\t\n\r]/g, '').replace(/^[\u0000- ]+/, '').toLowerCase();
+  return url.startsWith('javascript:') || url.startsWith('vbscript:');
+}
+
+// A script whose type the browser does not run (JSON, a template) is data.
+function runsAsCode(script) {
+  const type = (script.getAttribute('type') || '').trim().toLowerCase();
+  return !type || /javascript|ecmascript/.test(type) || ['module', 'importmap', 'speculationrules'].includes(type);
+}
+
+function attrsOf(el) {
+  return [...el.attributes].map(a => a.name.toLowerCase() + '=' + a.value).sort().join(' ');
+}
+
+function activeParts(root) {
+  const parts = new Map();
+  const add = (part) => parts.set(part, (parts.get(part) || 0) + 1);
+  for (const el of [root, ...root.querySelectorAll('*')]) {
+    const tag = el.tagName.toLowerCase();
+    if (tag === 'script') {
+      if (runsAsCode(el)) add('script ' + attrsOf(el) + '|' + el.textContent.trim());
+    } else if (ACTIVE_TAGS.has(tag) || (tag === 'meta' && el.hasAttribute('http-equiv'))) {
+      add(tag + ' ' + attrsOf(el));
+    } else if ((tag === 'animate' || tag === 'set') && /href/i.test(el.getAttribute('attributeName') || '')) {
+      add(tag + ' ' + attrsOf(el));
+    }
+    for (const attr of el.attributes) {
+      const name = attr.name.toLowerCase();
+      if (ACTIVE_ATTR.test(name)) add(tag + ' ' + name + '=' + attr.value.trim());
+      else if (name === 'srcdoc') add(tag + ' srcdoc=' + attr.value);
+      else if (isScriptURL(attr.value)) add(tag + ' ' + name + '=' + attr.value);
+    }
+  }
+  return parts;
+}
+
+function addsActiveContent(candidate, snapshot, docMode) {
+  const original = docMode
+    ? new DOMParser().parseFromString(snapshot, 'text/html').body
+    : (() => { const t = document.createElement('template'); t.innerHTML = snapshot; return t.content.firstElementChild; })();
+  const before = original ? activeParts(original) : new Map();
+  for (const [part, count] of activeParts(candidate)) if (count > (before.get(part) || 0)) return true;
+  return false;
+}
+
+const ACTIVE_REFUSED = 'The reply adds a script or event handler, so it was not applied. AI editing changes content, not code.';
+
 function onDone(payload) {
   if (!session || session.state !== 'requesting') return;
   session.state = 'deciding';
@@ -259,25 +379,27 @@ function onDone(payload) {
     }
   }
   if (session.reassertId) candidate.setAttribute('data-edit-id', session.reassertId);
-  if (!session.docMode) { // the real body legitimately contains scripts; skip in doc mode
-    if (candidate.querySelector('script')) {
-      warnings.push('reply contains <script> \u2014 review before keeping');
-    }
-    for (const el of [candidate, ...candidate.querySelectorAll('*')]) {
-      if ([...el.attributes].some(a => a.name.toLowerCase().startsWith('on'))) {
-        warnings.push('reply contains inline event handlers \u2014 review before keeping');
-        break;
-      }
-    }
+  if (addsActiveContent(candidate, session.snapshot, session.docMode)) {
+    onError(ACTIVE_REFUSED);
+    return;
   }
 
+  holdAllSaves();
+  session.held = true;
+
   session.finalCandidate = candidate;
-  sessionMorph(session, candidate); // authoritative morph from the full final HTML
+  try {
+    sessionMorph(session, candidate); // authoritative morph from the full final HTML
+  } catch (error) {
+    onError('the reply could not be applied: ' + (error?.message || error));
+    return;
+  }
   positionChrome();
   setStatus(payload.model ? `done (${payload.model})` : 'done');
   showWarnings(warnings);
   showButtons('keep', 'revert');
   textarea.value = '';
+  fitTextarea();
 }
 
 function onError(message) {
@@ -293,18 +415,26 @@ function revertSession() {
   const s = session;
   session = null;
   if (!s) return;
-  if (s.state === 'requesting' || s.state === 'deciding') {
-    sessionMorph(s, s.snapshot, { rewind: true });
+  try {
+    if (s.state === 'requesting' || s.state === 'deciding') {
+      sessionMorph(s, s.snapshot, { rewind: true });
+    }
+  } finally {
+    if (s.paused) resumeObservers();
+    if (s.held) releaseAllSaves();
+    positionChrome();
   }
-  if (s.paused) resumeObservers();
-  positionChrome();
 }
 
 async function keepSession() {
   const s = session;
   session = null;
-  sessionMorph(s, s.snapshot, { rewind: true }); // rewind while observers are still paused
-  if (s.paused) resumeObservers();    // boundary drain discards the rewind
+  try {
+    sessionMorph(s, s.snapshot, { rewind: true }); // rewind while observers are still paused
+  } finally {
+    if (s.paused) resumeObservers();    // boundary drain discards the rewind
+    if (s.held) releaseAllSaves({ replay: false });
+  }
   sessionMorph(s, s.finalCandidate);  // recorded: the whole edit = one undo step
   positionChrome();
   showButtons('send');
@@ -324,8 +454,15 @@ function cancelStream() {
 
 // ---------------------------------------------------------------- chrome
 
-function markRuntimeOnly(el) {
-  el.setAttribute('clay', RUNTIME_ONLY);
+// Everything below is drawn on somebody else's page, so it follows the hostile-CSS
+// contract: runtime-only, no ids or classes, every declaration inline and !important
+// from all:initial, in Bevel material from the generated subset. Show and hide go
+// through setShown and positions through set(), both !important, so no page rule can
+// reveal a hidden part or move a placed one.
+const FLOATING = ['z-index:99999', 'padding:0', 'display:inline-grid', 'place-items:center', 'line-height:1', `box-shadow:${SHADOW}`];
+
+function marked(el, name, value) {
+  el.setAttribute(name, value);
   return el;
 }
 
@@ -333,108 +470,85 @@ function buildChrome() {
   const style = document.createElement('style');
   style.setAttribute('clay', RUNTIME_ONLY);
   style.textContent = `
-    #hyper-edit-panel {
-      position: fixed; z-index: 99999; width: min(30rem, calc(100vw - 2rem));
-      background: #16161d; color: #e8e8f0; border: 1px solid #34343f;
-      border-radius: 10px; box-shadow: 0 12px 40px rgba(0,0,0,.45);
-      font: 13px/1.5 ui-monospace, SFMono-Regular, Menlo, monospace;
-      padding: 10px;
-    }
-    #hyper-edit-panel[hidden] { display: none; }
-    #hyper-edit-panel .hep-quote {
-      color: #9a9ab0; border-left: 2px solid #4a4a5a; padding-left: 8px;
-      margin-bottom: 8px; white-space: nowrap; overflow: hidden; text-overflow: ellipsis;
-    }
-    #hyper-edit-panel textarea {
-      width: 100%; box-sizing: border-box; min-height: 3.2em; resize: vertical;
-      background: #0e0e13; color: inherit; border: 1px solid #34343f;
-      border-radius: 6px; padding: 8px; font: inherit; outline: none;
-    }
-    #hyper-edit-panel textarea:focus { border-color: #6a6a8a; }
-    #hyper-edit-panel .hep-row {
-      display: flex; align-items: center; gap: 8px; margin-top: 8px;
-    }
-    #hyper-edit-panel .hep-status { flex: 1; color: #9a9ab0; min-width: 0; }
-    #hyper-edit-panel .hep-status.warn { color: #e8b04a; }
-    #hyper-edit-panel button {
-      background: #26262f; color: inherit; border: 1px solid #44444f;
-      border-radius: 6px; padding: 4px 12px; font: inherit; cursor: pointer;
-    }
-    #hyper-edit-panel button:hover { background: #32323d; }
-    #hyper-edit-panel .hep-keep { background: #1e3a2a; border-color: #2e5a40; }
-    #hyper-edit-panel .hep-warnings {
-      margin-top: 8px; color: #e8b04a; white-space: pre-line;
-    }
-    #hyper-edit-ring {
-      position: fixed; z-index: 99998; pointer-events: none;
-      border: 1px solid #7a7aff; border-radius: 4px; opacity: .8;
-    }
-    #hyper-edit-ring[hidden] { display: none; }
-    #hyper-edit-chip {
-      position: fixed; z-index: 99999; width: 26px; height: 26px; padding: 0;
-      display: flex; align-items: center; justify-content: center;
-      background: #16161d; color: #e8e8f0; border: 1px solid #44444f;
-      border-radius: 50%; cursor: pointer; font-size: 13px; line-height: 1;
-      box-shadow: 0 4px 14px rgba(0,0,0,.4);
-    }
-    #hyper-edit-chip[hidden] { display: none; }
-    #hyper-edit-chip:hover { background: #32323d; border-color: #6a6a8a; }
-    #hyper-edit-doc-bubble {
-      position: fixed; right: 16px; bottom: 16px; z-index: 99999;
-      width: 44px; height: 44px; padding: 0; border-radius: 50%;
-      display: flex; align-items: center; justify-content: center;
-      background: #16161d; color: #e8e8f0; border: 1px solid #44444f;
-      font-size: 18px; cursor: pointer; box-shadow: 0 6px 20px rgba(0,0,0,.45);
-    }
-    #hyper-edit-doc-bubble:hover { background: #32323d; border-color: #6a6a8a; }
     [editmode\\:contenteditable][contenteditable]:focus {
       outline: 1px solid #4a4a6a; outline-offset: 4px; border-radius: 2px;
     }
+    ::highlight(clay-ai-edit) { background-color: ${TOKENS['brass-soft']} !important; }
   `;
   document.head.appendChild(style);
 
-  ring = markRuntimeOnly(document.createElement('div'));
-  ring.id = 'hyper-edit-ring';
-  ring.hidden = true;
-
-  panel = markRuntimeOnly(document.createElement('div'));
-  panel.id = 'hyper-edit-panel';
-  panel.hidden = true;
-  panel.innerHTML = `
-    <div class="hep-quote" hidden></div>
-    <textarea rows="2" placeholder="Describe the change\u2026 (@file.ext adds context, @fable / @claude picks the agent)"></textarea>
-    <div class="hep-row">
-      <span class="hep-status"></span>
-      <button class="hep-send" type="button">Send</button>
-      <button class="hep-stop" type="button" hidden>Stop</button>
-      <button class="hep-revert" type="button" hidden>Revert</button>
-      <button class="hep-keep" type="button" hidden>Keep</button>
-    </div>
-    <div class="hep-warnings" hidden></div>
-  `;
+  const scheme = `color-scheme:${pageScheme()}`;
+
+  ring = marked(bevelBox('div', [
+    'box-sizing:content-box', 'position:fixed', 'z-index:99998', 'pointer-events:none',
+    `border:2px solid ${TOKENS.brass}`, 'border-radius:0', scheme,
+  ]), 'data-clay-ai-edit', 'ring');
+  setShown(ring, false);
+
+  panel = marked(bevelSurface('div', [
+    'position:fixed', 'z-index:99999', 'width:min(28rem, calc(100vw - 32px))',
+    'padding:12px', 'border-radius:12px', `box-shadow:${SHADOW}`, `font:13px/1.5 ${FONT_SANS}`, scheme,
+  ]), 'data-clay-ai-edit', 'panel');
+  setShown(panel, false);
+  panel.setAttribute('role', 'dialog');
+  panel.setAttribute('aria-label', 'AI edit');
+
+  const part = (el, name) => marked(el, 'data-clay-ai-edit-part', name);
+
+  // The notch on the panel's edge that points at the selected words.
+  pointer = part(bevelBox('div', [
+    'position:absolute', 'width:12px', 'height:12px', 'pointer-events:none',
+    `background:${TOKENS.surface}`, `border-left:1px solid ${TOKENS['line-2']}`, `border-top:1px solid ${TOKENS['line-2']}`,
+  ]), 'pointer');
+  setShown(pointer, false);
+
+  textarea = part(bevelInput('textarea', {
+    rules: ['flex:1', 'min-width:0', 'min-height:40px', 'max-height:9.5em', 'resize:none', 'overflow-y:auto',
+      'padding:8px 12px', `font:15px/1.45 ${FONT_SANS}`],
+  }), 'input');
+  textarea.rows = 1;
+  textarea.placeholder = 'Describe the change';
+  textarea.setAttribute('aria-label', 'Describe the change');
+  textarea.title = 'Enter sends · Shift+Enter adds a line · @fable or @codex picks another agent · @file.ext adds context';
+
+  statusEl = part(bevelText('div', [
+    'display:block', 'margin-top:0', `color:${TOKENS.muted}`, `font:12.5px/1.5 ${FONT_MONO}`,
+  ]), 'status');
+  statusEl.setAttribute('role', 'status');
+  statusEl.setAttribute('aria-live', 'polite');
+
+  const variants = { send: 'primary', stop: 'default', revert: 'quiet', keep: 'primary' };
+  const labels = { send: 'Send', stop: 'Stop', revert: 'Revert', keep: 'Keep' };
+  for (const name of ['send', 'stop', 'revert', 'keep']) {
+    buttons[name] = part(bevelButton(labels[name], { variant: variants[name], extra: ['min-height:40px', 'flex:none'] }), name);
+    setShown(buttons[name], name === 'send', 'inline-flex');
+  }
+
+  const row = bevelBox('div', ['display:flex', 'align-items:flex-start', 'gap:8px']);
+  row.append(textarea, buttons.send, buttons.stop, buttons.revert, buttons.keep);
 
-  chip = markRuntimeOnly(document.createElement('button'));
-  chip.id = 'hyper-edit-chip';
-  chip.type = 'button';
-  chip.title = 'Comment on this (\u2318K)';
-  chip.textContent = '\ud83d\udcac';
-  chip.hidden = true;
+  warningsEl = part(bevelText('div', [
+    'display:block', 'margin-top:8px', `color:${TOKENS.ox}`, 'white-space:pre-line',
+  ]), 'warnings');
+  setShown(warningsEl, false);
 
-  docBubble = markRuntimeOnly(document.createElement('button'));
-  docBubble.id = 'hyper-edit-doc-bubble';
-  docBubble.type = 'button';
+  panel.append(pointer, row, statusEl, warningsEl);
+
+  chip = marked(bevelButton('AI', {
+    small: true,
+    extra: ['position:fixed', 'width:26px', 'height:26px', `font:600 11px/1 ${FONT_SANS}`, ...FLOATING, scheme],
+  }), 'data-clay-ai-edit', 'chip');
+  chip.title = 'Comment on this (\u2318J)';
+  setShown(chip, false, 'inline-grid');
+
+  docBubble = marked(bevelButton('AI', {
+    extra: ['position:fixed', 'width:40px', 'height:40px', `font:600 14px/1 ${FONT_SANS}`, ...FLOATING, scheme],
+  }), 'data-clay-ai-edit', 'bubble');
   docBubble.title = 'Comment on the whole page';
-  docBubble.textContent = '\ud83d\udcac';
+  placeBubble();
 
   document.body.append(ring, panel, chip, docBubble);
-
-  quoteEl = panel.querySelector('.hep-quote');
-  textarea = panel.querySelector('textarea');
-  statusEl = panel.querySelector('.hep-status');
-  warningsEl = panel.querySelector('.hep-warnings');
-  for (const name of ['send', 'stop', 'keep', 'revert']) {
-    buttons[name] = panel.querySelector('.hep-' + name);
-  }
+  syncBubble();
 
   buttons.send.addEventListener('click', submit);
   buttons.stop.addEventListener('click', cancelStream);
@@ -447,18 +561,110 @@ function buildChrome() {
     }
   });
 
+  // One line to start, growing with the request up to the max-height.
+  textarea.addEventListener('input', fitTextarea);
+
+  chip.addEventListener('mousedown', (event) => event.preventDefault()); // keeps the page's selection alive
   chip.addEventListener('click', () => {
     const target = chipTarget;
+    const selection = chipSelection;
     hideChip();
-    if (target && !session) openPanel(target, quoteFromSelection(target));
+    if (target && !session) openPanel(target, selection || quoteFromSelection(target));
   });
   docBubble.addEventListener('click', () => {
     if (session) return;
+    // Like a click outside, a second click keeps a typed comment: it closes an empty panel only.
+    if (!panel.hidden && anchorEl === document.body) {
+      if (textarea.value.trim()) textarea.focus();
+      else closePanel();
+      return;
+    }
     openPanel(document.body, quoteFromSelection(document.body));
   });
 
   window.addEventListener('scroll', () => { positionChrome(); hideChip(); }, { passive: true });
-  window.addEventListener('resize', positionChrome, { passive: true });
+  window.addEventListener('resize', () => { placeBubble(); if (panel && !panel.hidden) fitTextarea(); positionChrome(); }, { passive: true });
+  // The CMS toggle can arrive after this chrome, and a docked sidebar slides it left.
+  const replace = () => { placeBubble(); positionChrome(); };
+  document.addEventListener('hcms:open', () => { replace(); setTimeout(replace, 350); });
+  document.addEventListener('hcms:close', () => { replace(); setTimeout(replace, 350); });
+  new MutationObserver((records) => {
+    syncBubble();
+    const touched = (nodes) => [...nodes].some((n) => n.nodeType === 1 && n.hasAttribute('data-hcms-toggle-host'));
+    if (records.some((r) => touched(r.addedNodes) || touched(r.removedNodes))) replace();
+  }).observe(document.body, { childList: true });
+
+  // A target removed from the page ends its edit, so the save hold and the paused
+  // observers never outlive it.
+  new MutationObserver(() => {
+    if (anchorEl && !anchorEl.isConnected && !panel.hidden) closePanel();
+  }).observe(document.body, { childList: true, subtree: true });
+}
+
+// The panel's height changes as the box grows and the status line fills, so it is
+// placed again after each change.
+function placePanelAgain() {
+  if (anchorEl?.isConnected) positionChrome();
+}
+
+function fitTextarea() {
+  set(textarea, 'height', 'auto');
+  if (textarea.value) set(textarea, 'height', textarea.scrollHeight + 2 + 'px');
+  placePanelAgain();
+}
+
+// The whole-page bubble belongs to pages built from [data-edit-id] sections. A plain
+// page gets the selection chip and the shortcut instead.
+function syncBubble() {
+  const doc = docBubble?.ownerDocument;
+  if (!doc) return;
+  setShown(docBubble, helperState === 'ready' && !!doc.querySelector('[data-edit-id]'), 'inline-grid');
+}
+
+// The selected words stay marked while the person types, through the CSS Custom
+// Highlight API, so the page's DOM never changes.
+function highlight(range) {
+  if (!range || typeof window.Highlight !== 'function' || !window.CSS?.highlights) return;
+  window.CSS.highlights.set(HIGHLIGHT, new window.Highlight(range));
+}
+
+function clearHighlight() {
+  window.CSS?.highlights?.delete(HIGHLIGHT);
+}
+
+function applyHelperState() {
+  const on = helperState === 'ready';
+  textarea.disabled = !on;
+  if (on) {
+    if (statusEl.textContent === OFF_MESSAGE) setStatus('');
+    if (!session) showButtons('send');
+  } else {
+    setStatus(OFF_MESSAGE, 'warn');
+    showButtons();
+  }
+  syncBubble();
+}
+
+// The host's toggle can change while the page is open, so each opening asks again.
+function refreshHelperState() {
+  helperStateNow().then((state) => {
+    helperState = state || 'unavailable';
+    if (!panel.hidden && !session) applyHelperState();
+    else syncBubble();
+  }).catch(() => {});
+}
+
+// The bubble sits in the bottom-right corner, or just left of the CMS's "Edit content"
+// toggle when the page has one, bottoms aligned, so the two never overlap.
+function placeBubble() {
+  if (!docBubble) return;
+  const host = document.querySelector('[data-hcms-toggle-host]');
+  const rect = host && host.getBoundingClientRect();
+  const beside = !!rect && rect.width > 0 && rect.height > 0;
+  docBubble.pin({
+    right: beside ? `${Math.round((document.documentElement.clientWidth || window.innerWidth) - rect.left + 8)}px` : '16px',
+    bottom: beside ? `${Math.round((document.documentElement.clientHeight || window.innerHeight) - rect.bottom)}px` : '16px',
+  });
 }
 
 // ---------------------------------------------------------------- hover chip
@@ -467,17 +673,22 @@ function showChipFor(unit) {
   clearTimeout(chipHideTimer);
   chipHideTimer = null;
   chipTarget = unit;
+  chipSelection = undefined;
   const rect = unit.getBoundingClientRect();
-  chip.hidden = false;
-  chip.style.left = Math.min(rect.right + 8, window.innerWidth - 34) + 'px';
-  chip.style.top = Math.max(8, rect.top) + 'px';
+  chip.pin({
+    left: Math.min(rect.right + 8, window.innerWidth - 34) + 'px',
+    top: Math.max(8, rect.top) + 'px',
+    'color-scheme': pageScheme(),
+  });
+  setShown(chip, true, 'inline-grid');
 }
 
 function hideChip() {
   clearTimeout(chipHideTimer);
   chipHideTimer = null;
-  chip.hidden = true;
+  setShown(chip, false, 'inline-grid');
   chipTarget = null;
+  chipSelection = undefined;
 }
 
 function scheduleChipHide() {
@@ -485,79 +696,163 @@ function scheduleChipHide() {
   chipHideTimer = setTimeout(hideChip, 400);
 }
 
+// The chip at the end of a selection: for people who do not know the shortcut, and
+// for browsers that keep Ctrl+J for themselves.
+function showChipForSelection() {
+  if (session || !panel.hidden || helperState !== 'ready' || pageOwnsFocus()) return;
+  const range = liveRange();
+  const target = range && targetFromRange(range);
+  const selection = target && selectionIn(range, target);
+  if (!selection) {
+    if (chipSelection) hideChip();
+    return;
+  }
+  const rects = typeof range.getClientRects === 'function' ? range.getClientRects() : [];
+  const end = rects.length ? rects[rects.length - 1] : target.getBoundingClientRect();
+  clearTimeout(chipHideTimer);
+  chipHideTimer = null;
+  chipTarget = target;
+  chipSelection = selection;
+  chip.pin({
+    left: Math.min(end.right + 6, window.innerWidth - 34) + 'px',
+    top: Math.max(8, end.top + end.height / 2 - 13) + 'px',
+    'color-scheme': pageScheme(),
+  });
+  setShown(chip, true, 'inline-grid');
+}
+
 function setStatus(text, tone) {
+  set(statusEl, 'margin-top', text ? '8px' : '0');
   statusEl.textContent = text || '';
-  statusEl.classList.toggle('warn', tone === 'warn');
+  if (tone === 'warn') statusEl.setAttribute('data-tone', 'warn');
+  else statusEl.removeAttribute('data-tone');
+  set(statusEl, 'color', tone === 'warn' ? TOKENS.ox : TOKENS.muted);
+  placePanelAgain();
 }
 
 function showButtons(...names) {
   for (const [name, button] of Object.entries(buttons)) {
-    button.hidden = !names.includes(name);
+    setShown(button, names.includes(name), 'inline-flex');
   }
+  fitTextarea();
 }
 
 function showWarnings(warnings) {
-  warningsEl.hidden = !warnings.length;
+  setShown(warningsEl, warnings.length > 0);
   warningsEl.textContent = warnings.map(w => '\u26a0 ' + w).join('\n');
+  placePanelAgain();
 }
 
 function positionChrome() {
   if (!anchorEl || panel.hidden) return;
   if (!anchorEl.isConnected) { closePanel(); return; }
   if (anchorEl === document.body) {
-    // document mode: no ring, panel pinned above the bottom-right bubble
-    ring.hidden = true;
-    panel.style.left = Math.max(16, window.innerWidth - (panel.offsetWidth || 480) - 16) + 'px';
-    panel.style.top = Math.max(16, window.innerHeight - (panel.offsetHeight || 120) - 76) + 'px';
+    // document mode: no ring, panel pinned above the bubble
+    setShown(ring, false);
+    setShown(pointer, false);
+    const bubble = docBubble.getBoundingClientRect();
+    const width = panel.offsetWidth || 480;
+    set(panel, 'left', Math.max(16, Math.min((bubble.right || window.innerWidth - 16) - width, window.innerWidth - width - 16)) + 'px');
+    set(panel, 'top', Math.max(16, (bubble.top || window.innerHeight - 56) - (panel.offsetHeight || 120) - 12) + 'px');
     return;
   }
   const rect = anchorEl.getBoundingClientRect();
-  ring.hidden = false;
-  ring.style.left = rect.left - 4 + 'px';
-  ring.style.top = rect.top - 4 + 'px';
-  ring.style.width = rect.width + 6 + 'px';
-  ring.style.height = rect.height + 6 + 'px';
+  // With selected words the highlight marks them until Send; the ring is for a whole element and for a running edit.
+  setShown(ring, !pendingSelection || !!session);
+  set(ring, 'left', rect.left - 5 + 'px');
+  set(ring, 'top', rect.top - 5 + 'px');
+  set(ring, 'width', rect.width + 6 + 'px');
+  set(ring, 'height', rect.height + 6 + 'px');
+  // Under the selection while it is still in the page, else under the element.
+  const at = anchorRange && anchorRange.startContainer.isConnected && typeof anchorRange.getBoundingClientRect === 'function'
+    ? anchorRange.getBoundingClientRect() : null;
+  const place = at && (at.width || at.height) ? at : rect;
   const panelWidth = panel.offsetWidth || 480;
-  const left = Math.max(16, Math.min(rect.left, window.innerWidth - panelWidth - 16));
-  let top = rect.bottom + 10;
+  const left = Math.max(16, Math.min(place.left, window.innerWidth - panelWidth - 16));
+  let top = place.bottom + 10;
   const panelHeight = panel.offsetHeight || 120;
   if (top + panelHeight > window.innerHeight - 16) {
-    top = Math.max(16, rect.top - panelHeight - 10);
+    top = Math.max(16, place.top - panelHeight - 10);
   }
-  panel.style.left = left + 'px';
-  panel.style.top = top + 'px';
+  set(panel, 'left', left + 'px');
+  set(panel, 'top', top + 'px');
+
+  // The pointer sits above the start of the selection, on the top edge, or on the
+  // bottom edge when the panel had to open above it.
+  const below = top >= place.bottom;
+  const tip = Math.max(14, Math.min(place.left + 10 - left, panelWidth - 28));
+  setShown(pointer, true);
+  set(pointer, 'left', tip + 'px');
+  set(pointer, 'top', below ? '-7px' : (panelHeight - 6) + 'px');
+  set(pointer, 'transform', below ? 'rotate(45deg)' : 'rotate(225deg)');
 }
 
 function openPanel(el, quote) {
+  const range = quote ? liveRange() : null; // read before focus moves into the panel
+  const active = document.activeElement;
+  returnFocus = active && active !== document.body && !panel.contains(active) ? active : null;
   anchorEl = el;
+  anchorRange = range ? range.cloneRange() : null;
   hideChip();
-  panel.hidden = false;
-  quoteEl.hidden = !quote;
-  quoteEl.textContent = quote ? `\u201c${quote}\u201d` : '';
-  panel.dataset.quote = quote || '';
+  set(panel, 'color-scheme', pageScheme());
+  set(ring, 'color-scheme', pageScheme());
+  setShown(panel, true);
+  pendingSelection = quote;
+  const shown = quote ? (quote.text.trim().length > 400 ? quote.text.trim().slice(0, 400) + '\u2026' : quote.text.trim()) : '';
+  panel.dataset.quote = shown;
   setStatus('');
   showWarnings([]);
   showButtons('send');
+  highlight(anchorRange);
+  applyHelperState();
   positionChrome();
   textarea.focus();
+  refreshHelperState();
 }
 
 function closePanel() {
-  if (session) revertSession();
+  if (session) { session.handle?.cancel(); revertSession(); }
+  const back = returnFocus;
+  const hadFocus = panel.contains(document.activeElement);
   anchorEl = null;
-  panel.hidden = true;
-  ring.hidden = true;
+  anchorRange = null;
+  returnFocus = null;
+  pendingSelection = undefined;
+  clearHighlight();
+  setShown(panel, false);
+  setShown(ring, false);
   textarea.value = '';
+  fitTextarea();
+  if (hadFocus && back && back.isConnected) back.focus({ preventScroll: true });
 }
 
 function submit() {
   const comment = textarea.value.trim();
-  if (!comment || !anchorEl || session) return;
-  sendRequest(anchorEl, comment, panel.dataset.quote || undefined);
+  if (!comment || !anchorEl || session || helperState !== 'ready') return;
+  clearHighlight();
+  sendRequest(anchorEl, comment, pendingSelection);
 }
 
 // ---------------------------------------------------------------- interactions
 
+const IS_MAC = /Mac|iPhone|iPad/.test(navigator.platform || navigator.userAgent || '');
+
+// Cmd+J on a Mac, Ctrl+J elsewhere. event.code covers keyboard layouts where the
+// J key types another letter.
+function isShortcut(event) {
+  const modifier = IS_MAC ? event.metaKey && !event.ctrlKey : event.ctrlKey && !event.metaKey;
+  if (!modifier || event.shiftKey || event.altKey || event.repeat || event.isComposing) return false;
+  return event.code === 'KeyJ' || (event.key || '').toLowerCase() === 'j';
+}
+
+// A field the page owns keeps its own Ctrl+J, and so does the panel's own box.
+function pageOwnsFocus() {
+  const el = document.activeElement;
+  if (!el || el === document.body) return false;
+  if (panel && panel.contains(el)) return !panel.hidden;
+  return el.matches('input,textarea,select');
+}
+
 function wireInteractions() {
   // Clicks: text units are contenteditable (caret) and figures keep their own
   // interactivity, so neither is intercepted. Only a click on bare section padding
@@ -581,6 +876,7 @@ function wireInteractions() {
     if (now - lastMove < 80) return;
     lastMove = now;
     if (session || !panel.hidden) { scheduleChipHide(); return; }
+    if (helperState !== 'ready' || chipSelection) return;
     if (chip.contains(event.target)) { clearTimeout(chipHideTimer); chipHideTimer = null; return; }
     const unit = unitFrom(event.target);
     if (unit) showChipFor(unit);
@@ -588,14 +884,22 @@ function wireInteractions() {
   });
 
   document.addEventListener('keydown', (event) => {
-    if ((event.metaKey || event.ctrlKey) && !event.shiftKey && !event.altKey && event.key.toLowerCase() === 'k') {
-      if (session) return;
+    if (isShortcut(event)) {
+      if (!session && anchorEl && !anchorEl.isConnected) closePanel();
+      if (session || pageOwnsFocus()) return;
+      const range = liveRange();
+      let target = range ? targetFromRange(range) : null;
+      if (!target) {
+        // Section pages: a caret inside a unit, or the unit under the hover chip.
+        const selection = window.getSelection();
+        let node = selection && selection.anchorNode;
+        if (node && node.nodeType !== 1) node = node.parentElement;
+        target = (node && unitFrom(node)) || chipTarget;
+      }
+      // Nothing to open: leave the key to the browser.
+      if (!target) return;
       event.preventDefault();
-      const selection = window.getSelection();
-      let node = selection && selection.anchorNode;
-      if (node && node.nodeType !== 1) node = node.parentElement;
-      const target = (node && unitFrom(node)) || chipTarget;
-      if (target) openPanel(target, quoteFromSelection(target));
+      openPanel(target, quoteFromSelection(target));
       return;
     }
     if (event.key !== 'Escape' || panel.hidden) return;
@@ -609,13 +913,19 @@ function wireInteractions() {
       closePanel();
     }
   });
+
+  document.addEventListener('selectionchange', () => {
+    clearTimeout(selectionTimer);
+    selectionTimer = setTimeout(showChipForSelection, 150);
+  });
 }
 
 // ---------------------------------------------------------------- boot
 
 async function init() {
-  if (!isEditMode) return;           // an owner/editor feature, nothing else
-  if (!(await available())) return;  // no ai-edit helper (e.g. HTML Clay, or the toggle off): stay dormant
+  if (!isEditMode || panel) return;  // an owner/editor feature, built once
+  helperState = await helperStateNow();
+  if (!helperState) return;          // no ai-edit helper on this host: stay dormant
   buildChrome();
   wireInteractions();
 }