@caretcms/core 0.3.0 → 0.4.0

package/static/cms/editor/md-block-edit.js

@@ -1,3 +1,4 @@
+import { mountParagraphGroups, paragraphHtml, pasteParagraphText } from './md-paragraphs.js';
 /**
  * Inline editing for markdown body blocks (`data-caret-md`).
  *
@@ -20,6 +21,15 @@ import { sanitizeHtml } from './sanitize.js';
 import { buildCmsUrl } from './config.js';
 import { mutateHeaders } from './security.js';
 
+/** @typedef {HTMLElement & { _caretSkipSave?: boolean }} MdEditableElement */
+/** @typedef {{ collection: string, id: string, blockPath: string }} MdBinding */
+/** @typedef {{ blockPath: string, src: string, html: string }} ParagraphSource */
+/** @typedef {{ sources: ParagraphSource[], paragraphs: string[] }} ParagraphGroup */
+/** @typedef {{ dirtyEls: Set<Element>, linkPopupEl: HTMLElement | null }} MdEditorState */
+/** @typedef {{ ok: true, skipped?: boolean } | { ok: false, reason: 'unauthorized' | 'stale' | 'error' }} MdSaveResult */
+/** @typedef {{ block: 'heading', level: number } | { block: 'paragraph', nested: boolean }} MdBlockContext */
+
+/** @type {WeakMap<HTMLElement, string>} */
 const snapshots = new WeakMap();
 
 // All md-block saves are chained through one queue (same pattern as
@@ -27,9 +37,12 @@ const snapshots = new WeakMap();
 // the network and land out of order — both return ok, and the older content
 // silently wins. A per-element generation counter additionally drops a queued
 // save that a newer blur has superseded.
+/** @type {Promise<unknown>} */
 let saveChain = Promise.resolve();
+/** @type {WeakMap<HTMLElement, number>} */
 const generations = new WeakMap();
 
+/** @param {() => Promise<MdSaveResult> | MdSaveResult} task @returns {Promise<MdSaveResult>} */
 function enqueueSave(task) {
   const run = saveChain.then(task, task);
   saveChain = run.then(
@@ -40,14 +53,52 @@ function enqueueSave(task) {
 }
 
 /** Parse `collection::id::body::blockPath`, or null. */
+/** @param {string | null} raw @returns {MdBinding | null} */
 function parseMdBinding(raw) {
   const parts = (raw || '').split('::');
   if (parts.length !== 4 || parts[2] !== 'body') return null;
+  if (!/^[a-z][a-z0-9_-]*$/.test(parts[0]) || !/^[a-z0-9][a-z0-9_-]*$/.test(parts[1])) return null;
   if (!/^\d+(\.\d+)*$/.test(parts[3])) return null;
   return { collection: parts[0], id: parts[1], blockPath: parts[3] };
 }
 
+/**
+ * Parse the server-authored structural paragraph source list. Attribute data
+ * is still a browser input boundary: extensions or page scripts can alter it,
+ * so malformed data must leave the group read-only instead of crashing mount
+ * or being echoed into a mutation.
+ * @param {string | null} raw
+ * @returns {ParagraphSource[] | null}
+ */
+export function parseParagraphSources(raw) {
+  if (!raw) return null;
+  try {
+    const value = JSON.parse(raw);
+    if (!Array.isArray(value) || value.length < 1 || value.length > 128) return null;
+    /** @type {ParagraphSource[]} */
+    const sources = [];
+    for (const source of value) {
+      if (typeof source !== 'object' || source === null ||
+          typeof source.blockPath !== 'string' || !/^\d+$/.test(source.blockPath) ||
+          typeof source.src !== 'string' || !/^\d+:\d+:[0-9a-f]{8}$/.test(source.src) ||
+          typeof source.html !== 'string') return null;
+      const [start, end] = source.src.split(':').map(Number);
+      if (!Number.isSafeInteger(start) || !Number.isSafeInteger(end) || start >= end) return null;
+      const previous = sources[sources.length - 1];
+      if (previous) {
+        const previousEnd = Number(previous.src.split(':')[1]);
+        if (Number(source.blockPath) !== Number(previous.blockPath) + 1 || start <= previousEnd) return null;
+      }
+      sources.push({ blockPath: source.blockPath, src: source.src, html: source.html });
+    }
+    return sources;
+  } catch {
+    return null;
+  }
+}
+
 /** Serialization context from the DOM — mirrors the server's derivation. */
+/** @param {HTMLElement} el @returns {MdBlockContext} */
 function blockContextOf(el) {
   const heading = /^h([1-6])$/.exec(el.tagName.toLowerCase());
   if (heading) return { block: 'heading', level: Number(heading[1]) };
@@ -55,26 +106,46 @@ function blockContextOf(el) {
   return { block: 'paragraph', nested };
 }
 
-async function saveMdBlock(binding, src, html) {
-  const res = await fetch(buildCmsUrl('/mutate'), {
-    method: 'POST',
-    headers: await mutateHeaders(),
-    body: JSON.stringify({
-      type: 'md_block',
-      collection: binding.collection,
-      id: binding.id,
-      blockPath: binding.blockPath,
-      src,
-      html,
-    }),
-  });
-  if (res.status === 401) return { ok: false, reason: 'unauthorized' };
-  if (res.status === 409) return { ok: false, reason: 'stale' };
-  if (!res.ok) return { ok: false, reason: 'error' };
-  return { ok: true };
+/**
+ * @param {MdBinding} binding
+ * @param {string} src
+ * @param {string} html
+ * @param {ParagraphGroup | undefined} group
+ * @returns {Promise<MdSaveResult>}
+ */
+async function saveMdBlock(binding, src, html, group) {
+  try {
+    const res = await fetch(buildCmsUrl('/mutate'), {
+      method: 'POST',
+      headers: await mutateHeaders(),
+      body: JSON.stringify({
+        type: 'md_block',
+        collection: binding.collection,
+        id: binding.id,
+        blockPath: binding.blockPath,
+        src,
+        html,
+        ...group,
+      }),
+    });
+    if (res.status === 401) return { ok: false, reason: 'unauthorized' };
+    if (res.status === 409) return { ok: false, reason: 'stale' };
+    if (!res.ok) return { ok: false, reason: 'error' };
+    return { ok: true };
+  } catch {
+    return { ok: false, reason: 'error' };
+  }
 }
 
+/**
+ * @param {object} options
+ * @param {MdEditorState} options.state
+ * @param {(element: Element, success: boolean) => void} options.flash
+ * @param {(message: string, kind: 'success' | 'error') => unknown} options.showToast
+ * @param {() => void} options.onUnauthorized
+ */
 export function mountMdBlockEditors({ state, flash, showToast, onUnauthorized }) {
+  mountParagraphGroups();
   document.querySelectorAll('[data-caret-md]').forEach((el) => {
     if (!(el instanceof HTMLElement)) return;
     if (el.dataset.caretMdMounted === 'true') return;
@@ -82,15 +153,26 @@ export function mountMdBlockEditors({ state, flash, showToast, onUnauthorized })
     const binding = parseMdBinding(el.getAttribute('data-caret-md'));
     const src = el.getAttribute('data-caret-md-src') || '';
     if (!binding || !src) return;
-    el.dataset.caretMdMounted = 'true';
-
     const ctx = blockContextOf(el);
+    const sourcesRaw = el.getAttribute('data-caret-md-sources');
+    const sources = sourcesRaw === null ? null : parseParagraphSources(sourcesRaw);
+    // A structural group with missing or malformed source metadata cannot be
+    // saved safely as one block. Keep it visible but do not make it editable.
+    if (sourcesRaw !== null && sources === null) return;
+    if (sources && (sources[0].blockPath !== binding.blockPath || sources[0].src !== src)) return;
+    el.dataset.caretMdMounted = 'true';
+    if (sources) {
+      el.classList.add('cms-md-paragraphs');
+      el.addEventListener('paste', pasteParagraphText);
+      // A drop can import arbitrary block structure outside the paste path.
+      el.addEventListener('drop', event => event.preventDefault());
+    }
 
     el.setAttribute('contenteditable', 'true');
     el.classList.add('cms-editable', 'cms-md-block');
 
     el.addEventListener('keydown', (event) => {
-      if (event.key !== 'Enter') return;
+      if (sources || event.key !== 'Enter') return;
       if (event.shiftKey && ctx.block === 'paragraph' && !ctx.nested) {
         return; // hard break in a top-level paragraph — allowed
       }
@@ -98,11 +180,20 @@ export function mountMdBlockEditors({ state, flash, showToast, onUnauthorized })
       showToast(
         event.shiftKey
           ? 'Line breaks are not supported in this block'
-          : 'Adding new blocks is coming in a future version',
+          : 'Paragraph changes are not supported in this block',
         'error',
       );
     });
 
+    el.addEventListener('beforeinput', (rawEvent) => {
+      const event = /** @type {InputEvent} */ (rawEvent);
+      if (!sources && (event.inputType === 'insertParagraph' ||
+          (event.inputType === 'insertLineBreak' && (ctx.block !== 'paragraph' || ctx.nested)))) {
+        event.preventDefault();
+        showToast('Paragraph changes are not supported in this block', 'error');
+      }
+    });
+
     el.addEventListener('focus', () => {
       snapshots.set(el, el.innerHTML);
     });
@@ -113,23 +204,34 @@ export function mountMdBlockEditors({ state, flash, showToast, onUnauthorized })
     });
 
     el.addEventListener('blur', async () => {
-      if (el._caretSkipSave) {
-        el._caretSkipSave = false;
+      if (state.linkPopupEl === el) return;
+
+      const editableEl = /** @type {MdEditableElement} */ (el);
+      if (editableEl._caretSkipSave) {
+        editableEl._caretSkipSave = false;
         state.dirtyEls.delete(el);
         el.innerHTML = snapshots.get(el) || '';
         return;
       }
 
       const snapshot = snapshots.get(el) ?? '';
-      const clean = sanitizeHtml(el.innerHTML);
-      el.innerHTML = clean; // normalize what the user sees to what will save
-      if (clean === snapshot) return;
+      const submitted = el.innerHTML;
+      const paragraphs = sources ? paragraphHtml(el) : null;
+      const clean = paragraphs ? paragraphs.map(p => `<p>${p || '<br>'}</p>`).join('') : sanitizeHtml(submitted);
+      if (!sources) el.innerHTML = clean;
+      if (submitted === snapshot && !state.dirtyEls.has(el)) return;
 
       // Pre-flight the serialization locally so unrepresentable content fails
       // with an immediate message instead of a server round-trip. The server
       // re-derives independently — this is UX, not the trust boundary.
       try {
-        serializeBlock(domToSNodes(el), ctx);
+        if (paragraphs) {
+          for (const html of paragraphs) {
+            const paragraph = document.createElement('p');
+            paragraph.innerHTML = html;
+            serializeBlock(domToSNodes(paragraph), { block: 'paragraph', nested: false });
+          }
+        } else serializeBlock(domToSNodes(el), ctx);
       } catch (error) {
         if (error instanceof SerializeError) {
           showToast('This formatting cannot be saved in a markdown block', 'error');
@@ -147,29 +249,30 @@ export function mountMdBlockEditors({ state, flash, showToast, onUnauthorized })
         // A newer blur queued behind us supersedes this content — skip so the
         // older payload can't overwrite the newer draft.
         if (generations.get(el) !== generation) return { ok: true, skipped: true };
-        return saveMdBlock(binding, src, clean);
+        const group = sources && paragraphs ? { sources, paragraphs } : undefined;
+        return saveMdBlock(binding, src, sources ? '' : clean, group);
       });
       el.classList.remove('cms-saving');
-      if (result.skipped) return;
+      if (('skipped' in result && result.skipped) || generations.get(el) !== generation) return;
       flash(el, result.ok);
 
       if (result.ok) {
-        state.dirtyEls.delete(el);
-        snapshots.set(el, clean);
+        if (el.innerHTML === (sources ? submitted : clean)) {
+          state.dirtyEls.delete(el);
+          snapshots.set(el, el.innerHTML);
+        }
         showToast('Draft saved — publish to update the file', 'success');
         // Signal the toolbar so server-delivery mode reveals its Publish/Discard
         // controls (hidden until a body draft is pending).
         window.dispatchEvent(new CustomEvent('cms:draftSaved'));
       } else if (result.reason === 'stale') {
-        state.dirtyEls.delete(el);
-        el.innerHTML = snapshot;
-        showToast('This content changed since the page loaded. Reload to edit it.', 'error');
+        state.dirtyEls.add(el);
+        showToast('This content changed. Copy your edits, then reload before saving.', 'error');
       } else if (result.reason === 'unauthorized') {
         onUnauthorized();
       } else {
-        state.dirtyEls.delete(el);
-        el.innerHTML = snapshot;
-        showToast('Failed to save. Changes reverted.', 'error');
+        state.dirtyEls.add(el);
+        showToast('Failed to save. Your edits are kept here; focus and leave the block to retry.', 'error');
       }
     });
   });

package/static/cms/editor/md-paragraphs.js

@@ -0,0 +1,98 @@
+/** Native contenteditable provides paragraph split/merge, selection deletion,
+ * IME and undo. Each host owns only consecutive stamped top-level paragraphs. */
+import { sanitizeHtml } from './sanitize.js';
+
+/** @typedef {{ binding: string, prefix: string, blockPath: string, src: string }} ParagraphBinding */
+/** @typedef {{ blockPath: string, src: string, html: string }} ParagraphSource */
+
+/** @param {Element | null} element @returns {element is HTMLElement} */
+function isParagraphCandidate(element) {
+  return element instanceof HTMLElement && element.matches('p[data-caret-md-paragraph="true"]') &&
+    [...element.querySelectorAll('*')].every(child => /^(B|STRONG|I|EM|A|BR|CODE)$/.test(child.tagName));
+}
+
+/** @param {HTMLElement} element @returns {ParagraphBinding | null} */
+function readParagraphBinding(element) {
+  const binding = element.getAttribute('data-caret-md');
+  const src = element.getAttribute('data-caret-md-src');
+  if (!binding || !src) return null;
+  const parts = binding.split('::');
+  if (parts.length !== 4 || parts[2] !== 'body' || !/^\d+$/.test(parts[3])) return null;
+  if (!/^[a-z][a-z0-9_-]*$/.test(parts[0]) || !/^[a-z0-9][a-z0-9_-]*$/.test(parts[1])) return null;
+  if (!/^\d+:\d+:[0-9a-f]{8}$/.test(src)) return null;
+  const [start, end] = src.split(':').map(Number);
+  if (!Number.isSafeInteger(start) || !Number.isSafeInteger(end) || start >= end) return null;
+  return { binding, prefix: parts.slice(0, 3).join('::'), blockPath: parts[3], src };
+}
+
+export function mountParagraphGroups() {
+  document.querySelectorAll('p[data-caret-md-paragraph="true"]').forEach(first => {
+    if (!isParagraphCandidate(first) || !first.isConnected || first.closest('li, blockquote, [data-caret-md-sources]')) return;
+    const firstBinding = readParagraphBinding(first);
+    if (!firstBinding) return;
+    const firstIndex = Number(firstBinding.blockPath);
+    /** @type {ParagraphSource[]} */
+    const sources = [];
+    /** @type {HTMLElement[]} */
+    const paragraphs = [];
+    /** @type {HTMLElement | null} */
+    let next = first;
+    let size = 0;
+    while (isParagraphCandidate(next)) {
+      const binding = readParagraphBinding(next);
+      if (!binding || binding.prefix !== firstBinding.prefix || Number(binding.blockPath) !== firstIndex + sources.length) break;
+      const html = next.getAttribute('data-caret-md-original') ?? next.innerHTML;
+      if (sources.length >= 128 || size + html.length * 2 > 48 * 1024) break;
+      size += html.length * 2;
+      sources.push({ blockPath: binding.blockPath, src: binding.src, html });
+      paragraphs.push(next);
+      // Only whitespace between adjacent elements may be crossed.
+      /** @type {ChildNode | null} */
+      let sibling = next.nextSibling;
+      while (sibling?.nodeType === Node.TEXT_NODE && !(sibling.textContent ?? '').trim()) sibling = sibling.nextSibling;
+      next = sibling instanceof HTMLElement ? sibling : null;
+    }
+    if (!sources.length) return;
+    const host = document.createElement('div');
+    host.setAttribute('data-caret-md', firstBinding.binding);
+    host.setAttribute('data-caret-md-src', sources[0].src);
+    host.setAttribute('data-caret-md-sources', JSON.stringify(sources));
+    first.before(host);
+    for (const paragraph of paragraphs) {
+      for (const attr of [...paragraph.attributes]) if (attr.name.startsWith('data-caret-md')) paragraph.removeAttribute(attr.name);
+      host.append(paragraph);
+    }
+  });
+}
+
+/** Normalize browser p/div wrappers; inline content goes through the existing
+ * sanitizer and serializer, independently for each paragraph. */
+/** @param {HTMLElement} root @returns {string[]} */
+export function paragraphHtml(root) {
+  /** @type {string[]} */
+  const result = [];
+  let inline = document.createElement('div');
+  const flush = () => {
+    if (inline.childNodes.length) { result.push(sanitizeHtml(inline.innerHTML)); inline = document.createElement('div'); }
+  };
+  for (const node of root.childNodes) {
+    if (node instanceof HTMLElement && /^(P|DIV)$/.test(node.tagName)) {
+      flush();
+      if (node.querySelector('p, div')) result.push(...paragraphHtml(node));
+      else result.push(sanitizeHtml(node.innerHTML));
+    } else inline.append(node.cloneNode(true));
+  }
+  flush();
+  return result.map(html => /^<br\s*\/?\s*>$/i.test(html) ? '' : html);
+}
+
+/** @param {ClipboardEvent} event */
+export function pasteParagraphText(event) {
+  if (!event.clipboardData) return;
+  event.preventDefault();
+  const text = event.clipboardData.getData('text/plain');
+  const html = text.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;')
+    .replace(/\r\n?/g, '\n').split(/\n\s*\n/).map((p) => `<p>${p.replace(/\n/g, '<br>') || '<br>'}</p>`).join('');
+  // Editing command keeps paste in the browser's undo stack.
+  document.execCommand('insertHTML', false, html);
+}

package/static/cms/editor/md-serialize.js

@@ -40,7 +40,7 @@ function escapeText(value) {
  * @returns {string}
  */
 function escapeLineStart(md) {
-  const ws = /^\s*/.exec(md)[0];
+  const ws = /^\s*/.exec(md)?.[0] ?? '';
   const rest = md.slice(ws.length);
 
   const ordered = /^(\d{1,9})([.)])(\s|$)/.exec(rest);

package/static/cms/editor/panel.js

@@ -1,5 +1,24 @@
 import { STUDIO_PATH } from './config.js';
 
+/** @param {string} key @returns {string | null} */
+function readSessionValue(key) {
+  try {
+    return sessionStorage.getItem(key);
+  } catch {
+    return null;
+  }
+}
+
+/** @param {string} key @param {string} value */
+function writeSessionValue(key, value) {
+  try {
+    sessionStorage.setItem(key, value);
+  } catch {
+    // Session storage is optional.
+  }
+}
+
+/** @param {{ studioButton: Element | null }} options */
 export function mountStudioPanel({ studioButton }) {
   if (!STUDIO_PATH) {
     studioButton?.setAttribute('hidden', 'hidden');
@@ -13,6 +32,10 @@ export function mountStudioPanel({ studioButton }) {
   panel.setAttribute('role', 'dialog');
   panel.setAttribute('aria-label', 'Content Studio');
   panel.setAttribute('aria-hidden', 'true');
+  panel.id = 'cms-studio-panel';
+  studioButton?.setAttribute('aria-controls', panel.id);
+  studioButton?.setAttribute('aria-haspopup', 'dialog');
+  studioButton?.setAttribute('aria-expanded', 'false');
 
   // Loading skeleton shown until the iframe reports load — the iframe is blank
   // until then, which reads as "broken".
@@ -25,23 +48,22 @@ export function mountStudioPanel({ studioButton }) {
 
   const iframe = document.createElement('iframe');
   let rememberedPath = '';
-  try {
-    const storedPath = sessionStorage.getItem('cms-panel-path') || '';
-    if (storedPath === STUDIO_PATH || storedPath.startsWith(`${STUDIO_PATH}/`)) {
-      rememberedPath = storedPath;
-    }
-  } catch {
-    // Session storage is optional; the Studio root remains a safe fallback.
+  const storedPath = readSessionValue('cms-panel-path') || '';
+  if (storedPath === STUDIO_PATH || storedPath.startsWith(`${STUDIO_PATH}/`)) {
+    rememberedPath = storedPath;
   }
   iframe.src = rememberedPath || STUDIO_PATH;
   iframe.title = 'Content Studio';
   iframe.addEventListener('load', () => {
     loading.setAttribute('hidden', 'hidden');
     try {
-      const currentPath = `${iframe.contentWindow.location.pathname}${iframe.contentWindow.location.search}`;
+      const iframeWindow = iframe.contentWindow;
+      if (!iframeWindow) return;
+      const currentPath = `${iframeWindow.location.pathname}${iframeWindow.location.search}`;
       if (currentPath === STUDIO_PATH || currentPath.startsWith(`${STUDIO_PATH}/`)) {
-        sessionStorage.setItem('cms-panel-path', currentPath);
+        writeSessionValue('cms-panel-path', currentPath);
       }
+      iframeWindow.document.addEventListener('keydown', handleEscape);
     } catch {
       // The configured Studio may be cross-origin, in which case its route is
       // intentionally unavailable to the parent page.
@@ -51,8 +73,10 @@ export function mountStudioPanel({ studioButton }) {
   document.body.appendChild(panel);
 
   // Remember what had focus so we can restore it on close.
+  /** @type {HTMLElement | null} */
   let lastFocused = null;
 
+  /** @param {boolean} [animate] */
   function openPanel(animate = true) {
     lastFocused = document.activeElement instanceof HTMLElement ? document.activeElement : null;
     if (!animate) {
@@ -64,7 +88,7 @@ export function mountStudioPanel({ studioButton }) {
     document.body.classList.add('cms-panel-open');
     studioButton?.classList.add('active');
     studioButton?.setAttribute('aria-expanded', 'true');
-    sessionStorage.setItem('cms-panel-open', '1');
+    writeSessionValue('cms-panel-open', '1');
     // Move focus into the drawer so keyboard users aren't left behind the
     // covering panel. The iframe is focusable and hands focus to its own content.
     if (animate) {
@@ -88,7 +112,7 @@ export function mountStudioPanel({ studioButton }) {
     document.body.classList.remove('cms-panel-open');
     studioButton?.classList.remove('active');
     studioButton?.setAttribute('aria-expanded', 'false');
-    sessionStorage.setItem('cms-panel-open', '0');
+    writeSessionValue('cms-panel-open', '0');
     // Return focus to the trigger (or wherever it was) so it isn't lost.
     const restore = lastFocused || studioButton;
     if (restore instanceof HTMLElement) {
@@ -110,18 +134,22 @@ export function mountStudioPanel({ studioButton }) {
   studioButton?.addEventListener('click', togglePanel);
 
   // Restore panel state from sessionStorage (without animation)
-  if (sessionStorage.getItem('cms-panel-open') === '1') {
+  if (readSessionValue('cms-panel-open') === '1') {
     openPanel(false);
   }
 
-  // Escape key closes panel (only when no CMS element is focused)
-  document.addEventListener('keydown', (e) => {
+  /** @param {KeyboardEvent} e */
+  function handleEscape(e) {
     if (e.key !== 'Escape' || !panel.classList.contains('open')) return;
     const focused = document.activeElement;
     if (!focused || !focused.matches('[data-caret]')) {
       closePanel();
     }
-  });
+  }
+
+  // Listen in both the page and same-origin Studio document. Keyboard events
+  // do not cross an iframe boundary after focus moves into the Studio.
+  document.addEventListener('keydown', handleEscape);
 
   return { iframe, closePanel };
 }

package/static/cms/editor/preview-mode.js

@@ -0,0 +1,44 @@
+const PREVIEW_COOKIE = 'caret_preview';
+
+/**
+ * @typedef {object} PreviewModeOptions
+ * @property {() => boolean} isStaticDelivery
+ * @property {() => boolean} isPolicyDraftMode
+ * @property {Pick<Document, 'cookie'>} documentRef
+ * @property {() => void} reload
+ */
+
+/**
+ * Keep the preview cookie aligned with the active delivery mode.
+ *
+ * @param {PreviewModeOptions} options
+ */
+export function createPreviewModeController(options) {
+  const { isStaticDelivery, isPolicyDraftMode, documentRef, reload } = options;
+
+  function previewActive() {
+    return documentRef.cookie
+      .split('; ')
+      .some(cookie => cookie === `${PREVIEW_COOKIE}=1`);
+  }
+
+  /** Static delivery always drafts, so enable preview before mounting the editor. */
+  function ensureStaticPreviewMode() {
+    if (!isStaticDelivery() || previewActive()) return false;
+    documentRef.cookie = `${PREVIEW_COOKIE}=1; path=/; SameSite=Lax`;
+    reload();
+    return true;
+  }
+
+  function normalizePreviewForDelivery() {
+    if (isPolicyDraftMode()) return false;
+    if (isStaticDelivery()) return ensureStaticPreviewMode();
+    if (!previewActive()) return false;
+
+    documentRef.cookie = `${PREVIEW_COOKIE}=; path=/; Max-Age=0; SameSite=Lax`;
+    reload();
+    return true;
+  }
+
+  return { ensureStaticPreviewMode, normalizePreviewForDelivery };
+}

package/static/cms/editor/publish-result.js

@@ -0,0 +1,100 @@
+/** @typedef {'idle' | 'saving' | 'error'} ToolbarStatusState */
+/** @typedef {'success' | 'error'} ToastKind */
+/**
+ * @typedef {object} PublishPresentation
+ * @property {boolean} completed
+ * @property {boolean} reload
+ * @property {boolean} retryAvailable
+ * @property {{ state: ToolbarStatusState, text: string } | null} status
+ * @property {{ kind: ToastKind, message: string }} toast
+ */
+
+/** @param {unknown} value */
+function record(value) {
+  return value && typeof value === 'object' && !Array.isArray(value)
+    ? /** @type {Record<string, unknown>} */ (value)
+    : {};
+}
+
+/** @param {unknown} value */
+function entries(value) {
+  return Array.isArray(value) ? value.map(record) : [];
+}
+
+/**
+ * Turn the publish API's mutually exclusive outcomes into one toolbar action.
+ * Keeping this pure makes recovery/conflict/deploy wording testable without DOM.
+ *
+ * @param {unknown} input
+ * @returns {PublishPresentation}
+ */
+export function presentPublishResult(input) {
+  const data = record(input);
+  const published = entries(data.published);
+  const conflicts = entries(data.conflicts);
+  const failed = entries(data.failed);
+  const rebuild = record(data.rebuild);
+  const retryAvailable = data.retryAvailable === true;
+
+  if (failed.length > 0) {
+    return {
+      completed: false,
+      reload: false,
+      retryAvailable,
+      status: { state: 'error', text: 'Publish needs recovery' },
+      toast: {
+        kind: 'error',
+        message: `Finished ${published.length} change(s); ${failed.length} need recovery. Some content may already be published. Retry Publish after checking storage. Drafts are kept.`,
+      },
+    };
+  }
+
+  if (conflicts.length > 0) {
+    const labels = conflicts.map(entry => {
+      const collection = typeof entry.collection === 'string' ? entry.collection : 'unknown';
+      const id = typeof entry.id === 'string' ? entry.id : 'unknown';
+      return `${collection}/${id}`;
+    }).join(', ');
+    return {
+      completed: false,
+      reload: false,
+      retryAvailable,
+      status: { state: 'error', text: 'Draft conflict' },
+      toast: {
+        kind: 'error',
+        message: `Drafts kept for ${labels}. Published content changed, or the draft predates conflict tracking. Copy your edits before using Discard (which removes all your drafts), then reload and reapply them.`,
+      },
+    };
+  }
+
+  if (rebuild.triggered === true && rebuild.ok === false) {
+    return {
+      completed: false,
+      reload: false,
+      retryAvailable,
+      status: { state: 'error', text: 'Published, deploy failed' },
+      toast: {
+        kind: 'error',
+        message: 'Changes are published, but the deploy webhook failed. Check your CI settings.',
+      },
+    };
+  }
+
+  const rebuildTriggered = rebuild.triggered === true;
+  return {
+    completed: true,
+    reload: true,
+    retryAvailable,
+    status: null,
+    toast: {
+      kind: 'success',
+      message: rebuildTriggered
+        ? published.length > 0
+          ? `Published ${published.length} change(s) — rebuild started`
+          : 'Your site is rebuilding'
+        : published.length > 0
+          ? `Published ${published.length} change(s) — rebuild and deploy to update visitors`
+          : 'Already up to date',
+    },
+  };
+}