@caretcms/core 0.3.0 → 0.4.0

package/static/cms/editor/section-controls/utils.js

@@ -1,33 +1,40 @@
 import { SPACING_Y_VALUES } from './constants.js';
 
+/** @param {string} key @returns {string} */
 export function humanizeSectionKey(key) {
   const short = key.startsWith('home.') ? key.slice('home.'.length) : key;
   return short.replace(/_/g, ' ').replace(/\b\w/g, (c) => c.toUpperCase());
 }
 
+/** @param {unknown} value @returns {string | undefined} */
 export function normalizeSpacingY(value) {
   if (typeof value !== 'string') return undefined;
   return SPACING_Y_VALUES.includes(value) && value !== 'default' ? value : undefined;
 }
 
+/** @param {unknown} value @returns {string} */
 export function spacingToken(value) {
   return normalizeSpacingY(value) || 'default';
 }
 
+/** @param {unknown} value @returns {number} */
 export function spacingIndex(value) {
   const idx = SPACING_Y_VALUES.indexOf(spacingToken(value));
   return idx === -1 ? 0 : idx;
 }
 
+/** @param {unknown} value @returns {string} */
 export function spacingButtonLabel(value) {
   const token = spacingToken(value);
   return token === 'default' ? 'Space' : `Space:${token}`;
 }
 
+/** @param {unknown} value @returns {value is Record<string, unknown>} */
 export function isRecord(value) {
   return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
 
+/** @param {string} key @returns {string} */
 export function generateSectionId(key) {
   return `sec-${key.replace(/\./g, '-')}-${Date.now().toString(36)}-${Math.random()
     .toString(36)

package/static/cms/editor/section-controls.css

@@ -25,7 +25,6 @@
 .cms-section-editable.cms-section-disabled-preview .cms-section-chip {
   opacity: 1;
   transform: translateY(0);
-  pointer-events: auto;
 }
 
 .cms-highlight-all .cms-section-editable {
@@ -57,7 +56,6 @@
 .cms-section-controls:focus-within {
   opacity: 1;
   transform: translateY(0);
-  pointer-events: auto;
 }
 
 .cms-section-chip {
@@ -112,6 +110,14 @@
   padding: 5px 7px;
   cursor: pointer;
   transition: all 0.16s ease;
+  pointer-events: none;
+}
+
+.cms-section-editable:hover .cms-section-btn,
+.cms-section-editable.cms-section-active .cms-section-btn,
+.cms-section-controls:focus-within .cms-section-btn,
+.cms-section-editable.cms-section-disabled-preview .cms-section-btn {
+  pointer-events: auto;
 }
 
 .cms-section-btn:hover {
@@ -173,7 +179,6 @@ body.cms-section-dragging .cms-section-controls {
 .cms-section-editable.cms-section-active .cms-section-boundary-actions,
 body.cms-spacing-dragging .cms-section-boundary-actions {
   opacity: 1;
-  pointer-events: auto;
 }
 
 .cms-section-insert-handle {
@@ -189,6 +194,7 @@ body.cms-spacing-dragging .cms-section-boundary-actions {
   cursor: pointer;
   box-shadow: 0 8px 18px rgba(0, 0, 0, 0.26);
   transition: border-color 0.16s ease, transform 0.16s ease, background 0.16s ease;
+  pointer-events: none;
 }
 
 .cms-section-insert-plus {
@@ -224,6 +230,15 @@ body.cms-spacing-dragging .cms-section-boundary-actions {
   cursor: ns-resize;
   box-shadow: 0 6px 18px rgba(0, 0, 0, 0.28);
   transition: border-color 0.16s ease, color 0.16s ease, background 0.16s ease;
+  pointer-events: none;
+}
+
+.cms-section-editable:hover .cms-section-insert-handle,
+.cms-section-editable.cms-section-active .cms-section-insert-handle,
+.cms-section-editable:hover .cms-section-gap-handle,
+.cms-section-editable.cms-section-active .cms-section-gap-handle,
+body.cms-spacing-dragging .cms-section-gap-handle {
+  pointer-events: auto;
 }
 
 .cms-section-gap-grip {

package/static/cms/editor/security.js

@@ -1,15 +1,24 @@
 import { CLOUD, getCloudSessionToken, isCloudMode } from './config.js';
 
+/**
+ * @param {string} action
+ * @returns {Promise<string | null>}
+ */
 async function getTurnstileToken(action) {
-  if (typeof window.cmsGetTurnstileToken !== 'function') return null;
+  const getToken = /** @type {Window & { cmsGetTurnstileToken?: (action: string) => unknown }} */ (
+    window
+  ).cmsGetTurnstileToken;
+  if (typeof getToken !== 'function') return null;
   try {
-    return await window.cmsGetTurnstileToken(action);
+    const token = await getToken(action);
+    return typeof token === 'string' && token.trim() ? token.trim() : null;
   } catch {
     return null;
   }
 }
 
 export async function mutateHeaders() {
+  /** @type {Record<string, string>} */
   const headers = { 'Content-Type': 'application/json', 'x-caret-request': '1' };
   if (isCloudMode()) {
     if (CLOUD?.publicToken) headers['x-caret-token'] = CLOUD.publicToken;
@@ -24,6 +33,7 @@ export async function mutateHeaders() {
 }
 
 export function readHeaders() {
+  /** @type {Record<string, string>} */
   const headers = {};
   if (isCloudMode()) {
     if (CLOUD?.publicToken) headers['x-caret-token'] = CLOUD.publicToken;
@@ -34,6 +44,7 @@ export function readHeaders() {
 }
 
 export async function uploadHeaders() {
+  /** @type {Record<string, string>} */
   const headers = { 'x-caret-request': '1' };
   if (isCloudMode()) {
     if (CLOUD?.publicToken) headers['x-caret-token'] = CLOUD.publicToken;

package/static/cms/editor/stega-hydrate.js

@@ -12,6 +12,7 @@
  * Decode logic mirrors runtime/stega.ts (the editor bundle is hand-authored JS,
  * separate from the TS runtime, so the few lines are intentionally duplicated).
  */
+import { parseCaretAttr } from './helpers.js';
 
 const TAG_BASE = 0xe0000;
 const TAG_MAX = 0xe007f;
@@ -19,12 +20,14 @@ const START = String.fromCodePoint(TAG_BASE + 0x00);
 const END = String.fromCodePoint(TAG_BASE + 0x01);
 const TAG_RE = /[\u{E0000}-\u{E007F}]/gu;
 
+/** @param {string} b64 @returns {string} */
 function fromBase64(b64) {
   const binary = atob(b64);
   const bytes = Uint8Array.from(binary, (c) => c.charCodeAt(0));
   return new TextDecoder().decode(bytes);
 }
 
+/** @param {string} value @returns {unknown} */
 export function stegaDecode(value) {
   const start = value.indexOf(START);
   if (start === -1) return undefined;
@@ -43,6 +46,7 @@ export function stegaDecode(value) {
   }
 }
 
+/** @param {string} value @returns {string} */
 export function stegaClean(value) {
   return value.replace(TAG_RE, '');
 }
@@ -51,28 +55,37 @@ export function stegaClean(value) {
  * Find every stega-tagged text node under `root`, decode its key, strip the
  * invisible characters, and tag the containing element with `data-caret`.
  * Returns the number of elements newly promoted.
+ * @param {Node | null} [root]
+ * @returns {number}
  */
 export function hydrateStega(root) {
   const scope = root || document.body;
   if (!scope) return 0;
 
   const walker = document.createTreeWalker(scope, NodeFilter.SHOW_TEXT);
+  /** @type {Text[]} */
   const tagged = [];
   let node = walker.nextNode();
   while (node) {
-    if (node.nodeValue && node.nodeValue.indexOf(START) !== -1) tagged.push(node);
+    if (node instanceof Text && node.nodeValue && node.nodeValue.indexOf(START) !== -1) {
+      tagged.push(node);
+    }
     node = walker.nextNode();
   }
 
   let promoted = 0;
   for (const textNode of tagged) {
-    const key = stegaDecode(textNode.nodeValue);
+    const value = textNode.nodeValue || '';
+    const key = stegaDecode(value);
     // Always strip the invisible characters so they never affect layout/copy.
-    textNode.nodeValue = stegaClean(textNode.nodeValue);
-    if (typeof key !== 'string' || key.indexOf('::') === -1) continue;
+    textNode.nodeValue = stegaClean(value);
+    if (typeof key !== 'string') continue;
+    const binding = parseCaretAttr(key);
+    if (!binding?.collection || !binding.id) continue;
 
     const el = textNode.parentElement;
     if (!el || el.hasAttribute('data-caret')) continue; // explicit attr wins
+    if (el.closest('script, style, template, noscript')) continue;
     el.setAttribute('data-caret', key);
     promoted++;
   }

package/static/cms/editor/sync.js

@@ -3,14 +3,136 @@ import { parseCaretAttr, resolveBinding } from './helpers.js';
 import { STUDIO_PATH } from './config.js';
 
 const SYNC_CHANNEL = 'caretcms:content';
+const PENDING_SELECTION_KEY = 'caretcms:pending-preview-selection';
+
+/** @typedef {{ dirtyEls: Set<Element> }} InlineEditorState */
+/**
+ * @typedef {object} SelectionMessage
+ * @property {'cms:field-selected'} type
+ * @property {string} collection
+ * @property {string} id
+ * @property {string} field
+ * @property {string} [previewPath]
+ * @property {boolean} [embedded]
+ * @property {string} [source]
+ */
+/**
+ * @typedef {object} EntryReadyMessage
+ * @property {'cms:entry-ready'} type
+ * @property {string} collection
+ * @property {string} id
+ * @property {boolean} [embedded]
+ */
+/**
+ * @typedef {object} ChangeMessage
+ * @property {'cms:preview' | 'cms:saved' | 'cms:created' | 'cms:deleted'} type
+ * @property {string} collection
+ * @property {string} id
+ * @property {Record<string, unknown> | null} [data]
+ * @property {string} [studioPath]
+ * @property {boolean} [embedded]
+ */
+/** @typedef {SelectionMessage | EntryReadyMessage | ChangeMessage} SyncMessage */
+/**
+ * @typedef {object} PendingSelection
+ * @property {string} collection
+ * @property {string} id
+ * @property {string} field
+ * @property {number} savedAt
+ */
+
+/**
+ * @param {unknown} value
+ * @returns {value is Record<string, unknown>}
+ */
+function isRecord(value) {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+/** @param {unknown} value @returns {value is string} */
+function isNonEmptyString(value) {
+  return typeof value === 'string' && value.length > 0;
+}
+
+/**
+ * Normalize messages before they reach selectors, navigation, or DOM updates.
+ * @param {unknown} value
+ * @returns {SyncMessage | null}
+ */
+export function normalizeSyncMessage(value) {
+  if (!isRecord(value) || typeof value.type !== 'string') return null;
+  if (!isNonEmptyString(value.collection) || !isNonEmptyString(value.id)) return null;
+
+  const common = {
+    collection: value.collection,
+    id: value.id,
+    ...(value.embedded === true ? { embedded: true } : {}),
+  };
+  if (value.type === 'cms:field-selected') {
+    if (!isNonEmptyString(value.field)) return null;
+    return {
+      ...common,
+      type: value.type,
+      field: value.field,
+      ...(typeof value.previewPath === 'string' ? { previewPath: value.previewPath } : {}),
+      ...(typeof value.source === 'string' ? { source: value.source } : {}),
+    };
+  }
+  if (value.type === 'cms:entry-ready') return { ...common, type: value.type };
+  if (!['cms:preview', 'cms:saved', 'cms:created', 'cms:deleted'].includes(value.type)) return null;
+  if (value.data !== undefined && value.data !== null && !isRecord(value.data)) return null;
+  return {
+    ...common,
+    type: /** @type {ChangeMessage['type']} */ (value.type),
+    ...(value.data !== undefined ? { data: value.data } : {}),
+    ...(typeof value.studioPath === 'string' ? { studioPath: value.studioPath } : {}),
+  };
+}
 
+/**
+ * @param {unknown} value
+ * @returns {PendingSelection | null}
+ */
+export function normalizePendingSelection(value) {
+  if (!isRecord(value)) return null;
+  if (
+    !isNonEmptyString(value.collection)
+    || !isNonEmptyString(value.id)
+    || !isNonEmptyString(value.field)
+    || typeof value.savedAt !== 'number'
+    || !Number.isFinite(value.savedAt)
+  ) return null;
+  return {
+    collection: value.collection,
+    id: value.id,
+    field: value.field,
+    savedAt: value.savedAt,
+  };
+}
+
+/**
+ * @param {object} options
+ * @param {HTMLIFrameElement | null} options.studioIframe
+ * @param {InlineEditorState} options.state
+ * @param {(message: string, kind: 'success' | 'error') => void} options.showToast
+ * @param {(text: string) => string} options.clientLinkify
+ */
 export function mountStudioSync({ studioIframe, state, showToast, clientLinkify }) {
   let refreshTimer = 0;
+  /** @type {Element | null} */
   let selectedInlineEl = null;
   let linkedSelectionTimer = 0;
+  /** @type {SelectionMessage | null} */
   let pendingStudioSelection = null;
+  /** @type {SelectionMessage | null} */
   let activeStudioSelection = null;
 
+  /**
+   * @param {string} collection
+   * @param {string} id
+   * @param {string} field
+   * @returns {Element[]}
+   */
   function matchingElements(collection, id, field) {
     const fullKey = `${collection}::${id}::${field}`;
     const matches = Array.from(document.querySelectorAll(`[data-caret="${CSS.escape(fullKey)}"]`));
@@ -21,10 +143,15 @@ export function mountStudioSync({ studioIframe, state, showToast, clientLinkify
     return matches;
   }
 
+  /**
+   * @param {string} collection
+   * @param {string} id
+   * @param {string} field
+   * @param {boolean} shouldScroll
+   */
   function selectInlineField(collection, id, field, shouldScroll) {
-    if (typeof collection !== 'string' || typeof id !== 'string' || typeof field !== 'string') return;
     const target = matchingElements(collection, id, field)[0];
-    if (!target) return;
+    if (!target) return false;
 
     window.clearTimeout(linkedSelectionTimer);
     if (selectedInlineEl && selectedInlineEl !== target) {
@@ -43,8 +170,45 @@ export function mountStudioSync({ studioIframe, state, showToast, clientLinkify
       target.classList.remove('cms-linked-selection');
       selectedInlineEl = null;
     }, 1500);
+    return true;
+  }
+
+  /** @param {unknown} path */
+  function previewTarget(path) {
+    if (typeof path !== 'string' || !path.startsWith('/') || path.startsWith('//')) return null;
+    try {
+      const target = new URL(path, window.location.origin);
+      return target.origin === window.location.origin ? target : null;
+    } catch {
+      return null;
+    }
   }
 
+  /** @param {SelectionMessage} message */
+  function selectOrNavigate(message) {
+    if (selectInlineField(message.collection, message.id, message.field, true)) return;
+
+    const target = previewTarget(message.previewPath);
+    if (!target || target.href === window.location.href) return;
+    if (state.dirtyEls.size > 0) {
+      showToast('Finish or cancel your inline edit before opening another page', 'error');
+      return;
+    }
+
+    try {
+      sessionStorage.setItem(PENDING_SELECTION_KEY, JSON.stringify({
+        collection: message.collection,
+        id: message.id,
+        field: message.field,
+        savedAt: Date.now(),
+      }));
+    } catch {
+      // Navigation still works without the post-load highlight handoff.
+    }
+    window.location.assign(target.href);
+  }
+
+  /** @param {SelectionMessage} message */
   function publishSelection(message) {
     if (!('BroadcastChannel' in window)) return;
     try {
@@ -56,10 +220,13 @@ export function mountStudioSync({ studioIframe, state, showToast, clientLinkify
     }
   }
 
+  /** @param {SelectionMessage} message */
   function studioEntryPath(message) {
+    if (!STUDIO_PATH) return null;
     return `${STUDIO_PATH}/${encodeURIComponent(message.collection)}/${encodeURIComponent(message.id)}`;
   }
 
+  /** @param {SelectionMessage} message */
   function postEmbeddedSelection(message) {
     if (!studioIframe?.contentWindow) return;
     try {
@@ -69,9 +236,11 @@ export function mountStudioSync({ studioIframe, state, showToast, clientLinkify
     }
   }
 
+  /** @param {SelectionMessage} message */
   function deliverEmbeddedSelection(message) {
     if (!studioIframe?.contentWindow) return;
     const targetPath = studioEntryPath(message);
+    if (!targetPath) return;
 
     // A normal mouse interaction can emit pointerdown, focusin, and click.
     // Keep the latest field without restarting the same iframe navigation for
@@ -107,11 +276,13 @@ export function mountStudioSync({ studioIframe, state, showToast, clientLinkify
     window.requestAnimationFrame(() => postEmbeddedSelection(message));
   });
 
+  /** @param {Element} el */
   function selectStudioField(el) {
     const resolved = resolveBinding(el, parseCaretAttr(el.getAttribute('data-caret') || ''));
     if (!resolved) return;
 
     selectInlineField(resolved.collection, resolved.id, resolved.field, false);
+    /** @type {SelectionMessage} */
     const message = {
       type: 'cms:field-selected',
       collection: resolved.collection,
@@ -140,8 +311,9 @@ export function mountStudioSync({ studioIframe, state, showToast, clientLinkify
     if (el) selectStudioField(el);
   });
 
+  /** @param {SyncMessage} msg */
   function rememberStudioPath(msg) {
-    if (typeof msg.studioPath !== 'string') return;
+    if (!('studioPath' in msg) || typeof msg.studioPath !== 'string') return;
     try {
       sessionStorage.setItem('cms-panel-path', msg.studioPath);
     } catch {
@@ -149,6 +321,7 @@ export function mountStudioSync({ studioIframe, state, showToast, clientLinkify
     }
   }
 
+  /** @param {SyncMessage} msg */
   function scheduleEmbeddedRefresh(msg) {
     rememberStudioPath(msg);
 
@@ -162,12 +335,18 @@ export function mountStudioSync({ studioIframe, state, showToast, clientLinkify
     refreshTimer = window.setTimeout(() => window.location.reload(), 280);
   }
 
+  /** @param {ChangeMessage} msg */
   function applySavedMessage(msg) {
     const { collection, id, data } = msg;
     if (!data || typeof data !== 'object') return 0;
 
     let updated = 0;
 
+    /**
+     * @param {string} selector
+     * @param {string} path
+     * @returns {Element[]}
+     */
     function boundElements(selector, path) {
       const matches = Array.from(document.querySelectorAll(`[data-caret="${CSS.escape(selector)}"]`));
       document.querySelectorAll(`[data-caret="${CSS.escape(path)}"]`).forEach((el) => {
@@ -177,6 +356,10 @@ export function mountStudioSync({ studioIframe, state, showToast, clientLinkify
       return matches;
     }
 
+    /**
+     * @param {Record<string, unknown>} obj
+     * @param {string} prefix
+     */
     function walkData(obj, prefix) {
       for (const [key, value] of Object.entries(obj)) {
         const path = prefix ? `${prefix}.${key}` : key;
@@ -210,7 +393,7 @@ export function mountStudioSync({ studioIframe, state, showToast, clientLinkify
               updated++;
             }
           });
-        } else if (typeof value === 'object' && value !== null) {
+        } else if (isRecord(value)) {
           walkData(value, path);
         }
       }
@@ -223,8 +406,8 @@ export function mountStudioSync({ studioIframe, state, showToast, clientLinkify
   window.addEventListener('message', (e) => {
     // Only accept messages from our iframe
     if (!studioIframe || e.source !== studioIframe.contentWindow) return;
-    const msg = e.data;
-    if (!msg || typeof msg.type !== 'string') return;
+    const msg = normalizeSyncMessage(e.data);
+    if (!msg) return;
 
     if (
       msg.type === 'cms:entry-ready'
@@ -242,7 +425,7 @@ export function mountStudioSync({ studioIframe, state, showToast, clientLinkify
     }
 
     if (msg.type === 'cms:field-selected') {
-      selectInlineField(msg.collection, msg.id, msg.field, true);
+      selectOrNavigate(msg);
       return;
     }
 
@@ -265,11 +448,11 @@ export function mountStudioSync({ studioIframe, state, showToast, clientLinkify
     try {
       const channel = new BroadcastChannel(SYNC_CHANNEL);
       channel.addEventListener('message', (event) => {
-        const msg = event.data;
-        if (!msg || typeof msg.type !== 'string' || msg.embedded === true) return;
+        const msg = normalizeSyncMessage(event.data);
+        if (!msg || msg.embedded === true) return;
 
         if (msg.type === 'cms:field-selected') {
-          selectInlineField(msg.collection, msg.id, msg.field, true);
+          selectOrNavigate(msg);
           return;
         }
         if (!['cms:saved', 'cms:created', 'cms:deleted'].includes(msg.type)) return;
@@ -290,4 +473,19 @@ export function mountStudioSync({ studioIframe, state, showToast, clientLinkify
       // remains available in browsers without BroadcastChannel.
     }
   }
+
+  try {
+    const rawPending = sessionStorage.getItem(PENDING_SELECTION_KEY);
+    if (rawPending) {
+      sessionStorage.removeItem(PENDING_SELECTION_KEY);
+      const pending = normalizePendingSelection(JSON.parse(rawPending));
+      if (pending && Date.now() - pending.savedAt < 30_000) {
+        window.requestAnimationFrame(() => {
+          selectInlineField(pending.collection, pending.id, pending.field, true);
+        });
+      }
+    }
+  } catch {
+    // Pending selection recovery is a progressive enhancement.
+  }
 }

package/static/cms/editor/text-edit.js

@@ -2,6 +2,22 @@ import { createTextLinkInteractions } from './text-link-interactions.js';
 import { resolveBinding } from './helpers.js';
 import { sanitizeHtml } from './sanitize.js';
 
+/** @typedef {HTMLElement & { _caretSkipSave?: boolean }} EditableElement */
+/** @typedef {{ collection: string, id: string, field: string }} ResolvedCaretBinding */
+/** @typedef {{ collection: string | null, id: string | null, field: string }} ParsedCaretBinding */
+/** @typedef {{ dirtyEls: Set<Element>, linkPopupEl: HTMLElement | null }} TextEditorState */
+/** @typedef {{ ok: true, revision?: number } | { ok: false, reason: 'conflict' | 'unauthorized' | 'error', latestValue?: unknown }} SaveResult */
+/**
+ * @typedef {((message: string, kind: 'success' | 'error') => unknown) & {
+ *   conflict: (options: {
+ *     message: string,
+ *     onKeepMine: () => void | Promise<void>,
+ *     onLoadLatest: () => void,
+ *   }) => unknown,
+ * }} ConflictToast
+ */
+
+/** @type {WeakMap<HTMLElement, string>} */
 const snapshots = new WeakMap();
 let keydownBound = false;
 
@@ -19,6 +35,15 @@ const PLAINTEXT_ONLY_SUPPORTED = (() => {
   }
 })();
 
+/**
+ * @param {object} options
+ * @param {TextEditorState} options.state
+ * @param {(attr: string) => ParsedCaretBinding | null} options.parseCaretAttr
+ * @param {(text: string) => string} options.clientLinkify
+ * @param {(collection: string, id: string, field: string, value: string) => Promise<SaveResult>} options.saveField
+ * @param {(element: Element, success: boolean) => void} options.flash
+ * @param {ConflictToast} options.showToast
+ */
 export function mountTextEditors({
   state,
   parseCaretAttr,
@@ -27,6 +52,7 @@ export function mountTextEditors({
   flash,
   showToast,
 }) {
+  /** @param {HTMLElement} target @param {string} value */
   const applyTextValue = (target, value) => {
     if (target.hasAttribute('data-caret-rich')) {
       target.innerHTML = sanitizeHtml(value);
@@ -37,6 +63,7 @@ export function mountTextEditors({
       target.textContent = value;
     }
   };
+  /** @param {string} attr @param {string} value */
   const syncBoundText = (attr, value) => {
     document.querySelectorAll('[data-caret]').forEach((node) => {
       if (!(node instanceof HTMLElement)) return;
@@ -58,11 +85,13 @@ export function mountTextEditors({
   }
 
   document.querySelectorAll('[data-caret]').forEach((el) => {
-    if (el instanceof HTMLImageElement) return;
+    if (!(el instanceof HTMLElement) || el instanceof HTMLImageElement) return;
+    const editableEl = /** @type {EditableElement} */ (el);
     if (el.dataset.caretTextMounted === 'true') return;
     el.dataset.caretTextMounted = 'true';
 
     const attr = el.getAttribute('data-caret');
+    if (!attr) return;
     const isRich = el.hasAttribute('data-caret-rich');
     const isLinkable = !isRich && el.hasAttribute('data-caret-raw');
 
@@ -121,6 +150,11 @@ export function mountTextEditors({
     // (the save queue refreshed the cached revision on the 409, so the retry
     // targets the current revision and overwrites); "Load latest" replaces the
     // field with the server value. The element stays dirty until resolved.
+    /**
+     * @param {ResolvedCaretBinding} resolved
+     * @param {string} mine
+     * @param {unknown} latestValue
+     */
     const runConflict = (resolved, mine, latestValue) => {
       state.dirtyEls.add(el);
       el.classList.add('cms-conflict');
@@ -161,8 +195,8 @@ export function mountTextEditors({
       if (state.linkPopupEl === el) return;
 
       // Skip save if Escape was pressed
-      if (el._caretSkipSave) {
-        el._caretSkipSave = false;
+      if (editableEl._caretSkipSave) {
+        editableEl._caretSkipSave = false;
         state.dirtyEls.delete(el);
         if (isRich) {
           el.innerHTML = snapshots.get(el) || '';