@charlescms/astro 0.1.0

package/src/source-edit.js

@@ -0,0 +1,310 @@
+import { escapeAstroBraces, sanitizeBlockHtml, sanitizeRichText } from "./sanitize.js";
+import { load } from "js-yaml";
+import { fromMarkdown } from "mdast-util-from-markdown";
+import { gfmFromMarkdown, gfmToMarkdown } from "mdast-util-gfm";
+import { toMarkdown } from "mdast-util-to-markdown";
+import { toString } from "mdast-util-to-string";
+import { gfm } from "micromark-extension-gfm";
+import { parseFragment } from "parse5";
+
+// Applies staged edits at the source boundary.
+//
+// Every operation first proves that its recorded bytes are still present. Rich
+// content is parsed and sanitized again here, so browser previews are never
+// trusted as permission to write arbitrary markup or alter surrounding syntax.
+const markdownInlineTypes = new Set(["text", "emphasis", "strong", "inlineCode", "link", "break"]);
+
+/**
+ * Produce the new file contents for one staged edit, applied at the source boundary.
+ *
+ * Every operation first proves its recorded bytes are still present, and rich
+ * content is re-parsed and re-sanitized here, so a browser preview is never
+ * trusted as permission to write arbitrary markup or alter surrounding syntax.
+ *
+ * @param {string} source Current file contents.
+ * @param {object} entry Source-map entry describing the region (operations, tag, file).
+ * @param {object} edit Staged change ({ action: "update"|"insert"|"delete", value, ... }).
+ * @returns {string} The edited file contents.
+ * @throws {UnsafeSourceEditError} If recorded bytes drifted or the edit is disallowed.
+ */
+export function createEditedSource(source, entry, edit) {
+  if (edit.action === "insert") {
+    return createInsertedSource(source, entry, edit);
+  }
+  if (edit.action === "delete") {
+    return createDeletedSource(source, entry);
+  }
+
+  for (const operation of entry.operations) {
+    if (entry.tag === "a" && operation.kind.startsWith("attribute")) {
+      throw new UnsafeSourceEditError("Link attributes are not editable.");
+    }
+    const current = source.slice(operation.start, operation.end);
+    if (current !== operation.oldValue) {
+      throw new UnsafeSourceEditError("Source changed since the CMS build. Refusing unsafe edit.");
+    }
+  }
+
+  let next = source;
+  for (const operation of [...entry.operations].sort((a, b) => b.start - a.start)) {
+    const value = getOperationValue(edit.value, operation);
+    next = `${next.slice(0, operation.start)}${serializeOperationValue(value, operation)}${next.slice(operation.end)}`;
+  }
+  return next;
+}
+
+function createInsertedSource(source, entry, edit) {
+  const anchor = entry.anchors?.find((item) => item.anchorId === edit.anchorId);
+  if (!anchor) {
+    throw new UnsafeSourceEditError("No verified section anchor exists for this insertion.");
+  }
+  assertOuterSpan(source, anchor);
+  if (edit.position !== "before" && edit.position !== "after") {
+    throw new UnsafeSourceEditError("Section position must be before or after its anchor.");
+  }
+  const html = sanitizeBlockHtml(edit.value).trim();
+  if (!html) {
+    throw new UnsafeSourceEditError("A section needs at least one safe content block.");
+  }
+  const sectionClass = sanitizeClassList(entry.sectionClass);
+  const classAttribute = sectionClass ? ` class="${sectionClass}"` : "";
+  const blockId = createBlockId();
+  const indent = lineIndentAt(source, anchor.outerStart);
+  const wrapper = `<div data-charlescms-block="${blockId}"${classAttribute}>${html}</div>`;
+  const index = edit.position === "before" ? anchor.outerStart : anchor.outerEnd;
+  const insertion = edit.position === "before"
+    ? `${wrapper}\n${indent}`
+    : `\n${indent}${wrapper}`;
+  return `${source.slice(0, index)}${insertion}${source.slice(index)}`;
+}
+
+function createDeletedSource(source, entry) {
+  assertOuterSpan(source, entry);
+  return `${source.slice(0, entry.outerStart)}${source.slice(entry.outerEnd)}`;
+}
+
+export class UnsafeSourceEditError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "UnsafeSourceEditError";
+  }
+}
+
+function getOperationValue(value, operation) {
+  if (typeof value === "string") return value;
+  if (value && typeof value === "object") {
+    return value[operation.name] ?? value[operation.kind] ?? "";
+  }
+  return "";
+}
+
+function serializeOperationValue(value, operation) {
+  // Rich text is written verbatim, but only AFTER the authoritative sanitizer
+  // re-checks it here — never trust whatever produced the edit. The whole-file
+  // Astro-compiler validation downstream is the second gate.
+  if (operation.kind === "rich-text") {
+    // Lands directly in .astro markup, so braces must be neutralized too —
+    // sanitizeRichText preserves them (it is also reused for the Markdown path,
+    // where braces are literal and must stay).
+    return escapeAstroBraces(sanitizeRichText(value));
+  }
+  if (operation.kind === "block-html") {
+    return sanitizeBlockHtml(value);
+  }
+  if (operation.kind === "frontmatter") {
+    return serializeFrontmatterValue(value, operation);
+  }
+  if (operation.kind === "markdown-text") {
+    return serializeMarkdownText(value);
+  }
+  if (operation.kind === "markdown-block") {
+    return serializeMarkdownBlock(value, operation);
+  }
+  if (operation.kind === "data-string") {
+    return serializeDataString(value, operation);
+  }
+  // A value resolved from a `{const}` — an inline {expr} heading or a media
+  // src/alt that points at a frontmatter constant — is written back INTO that JS
+  // string literal. So it is escaped for the literal's quote exactly like a data
+  // string (which it now carries), and is NEVER HTML-encoded: Astro escapes the
+  // `{expr}` itself at render, so HTML-encoding here would surface `&amp;`/`&lt;`
+  // verbatim on the page. serializeDataString also refuses newlines and escapes
+  // the quote/backslash, so the value can never break out of the literal.
+  if (operation.kind === "text-expression" || operation.kind === "attribute-expression") {
+    return serializeDataString(value, operation);
+  }
+  return escapeSourceValue(value, operation);
+}
+
+// A navigation label is written back into a JS/TS string literal in a data
+// file. Only the characters that could break out of that literal are escaped
+// (the enclosing quote and backslash); newlines are refused so a label can
+// never split the array across lines. The href is never an operation here, so
+// the link destination cannot be reached through this path.
+function serializeDataString(value, operation) {
+  const raw = String(value);
+  if (/[\r\n]/.test(raw)) {
+    throw new UnsafeSourceEditError("Navigation labels must stay on one line.");
+  }
+  const quote = operation.quote === "'" ? "'" : '"';
+  return raw.replaceAll("\\", "\\\\").replaceAll(quote, `\\${quote}`);
+}
+
+function serializeFrontmatterValue(value, operation) {
+  const raw = String(value);
+
+  if (operation.valueType === "boolean") {
+    if (!/^(?:true|false)$/i.test(raw.trim())) {
+      throw new UnsafeSourceEditError("Frontmatter boolean must be true or false.");
+    }
+    return raw.trim().toLowerCase();
+  }
+  if (operation.valueType === "number") {
+    const number = Number(raw.trim());
+    if (!raw.trim() || !Number.isFinite(number)) {
+      throw new UnsafeSourceEditError("Frontmatter number is invalid.");
+    }
+    return raw.trim();
+  }
+  if (operation.valueType === "date") {
+    const trimmed = raw.trim();
+    if (!/^\d{4}-\d{2}-\d{2}(?:[Tt][^\s]+)?$/.test(trimmed) || Number.isNaN(Date.parse(trimmed))) {
+      throw new UnsafeSourceEditError("Frontmatter date is invalid.");
+    }
+    return trimmed;
+  }
+
+  // A double-quoted YAML string can carry a line break safely as the escape
+  // "\n" — so the editor can show clean multi-line text and we encode it here.
+  if (operation.quote === '"') return JSON.stringify(raw).slice(1, -1);
+  // Single-quoted and plain scalars cannot, so a newline there is refused.
+  if (/[\r\n]/.test(raw)) {
+    throw new UnsafeSourceEditError("This value must stay on one line.");
+  }
+  if (operation.quote === "'") return raw.replaceAll("'", "''");
+  return isSafePlainYamlString(raw) ? raw : JSON.stringify(raw);
+}
+
+function isSafePlainYamlString(value) {
+  if (!value || value.trim() !== value) return false;
+  if (/^(?:[-?:,\[\]{}#&*!|>'"%@`]|\.\.\.)/.test(value)) return false;
+  if (/:\s|(?:^|\s)#/.test(value)) return false;
+  try {
+    return load(`value: ${value}\n`)?.value === value;
+  } catch {
+    return false;
+  }
+}
+
+function serializeMarkdownText(value) {
+  const raw = String(value);
+  if (/[\r\n]/.test(raw)) {
+    throw new UnsafeSourceEditError("Markdown text must stay on one line.");
+  }
+  if (/^(?:#{1,6}(?:\s|$)|>|[-*+](?:\s|$)|`{3,}|\||\d+\.(?:\s|$))/.test(raw.trimStart())) {
+    throw new UnsafeSourceEditError("Markdown text cannot introduce a block marker.");
+  }
+  const tree = parseMarkdown(raw);
+  const paragraph = singleMarkdownParagraph(tree);
+  if (!paragraph || paragraph.children.length !== 1 || paragraph.children[0].type !== "text") {
+    throw new UnsafeSourceEditError("Markdown text cannot introduce inline formatting.");
+  }
+  return raw;
+}
+
+function serializeMarkdownBlock(value, operation) {
+  const html = sanitizeRichText(value);
+  const fragment = parseFragment(html);
+  const children = fragment.childNodes.flatMap(htmlNodeToMdast);
+  const tree = { type: "root", children: [{ type: "paragraph", children }] };
+  const markdown = toMarkdown(tree, { extensions: [gfmToMarkdown()] }).trimEnd();
+  const parsed = parseMarkdown(markdown);
+  const paragraph = singleMarkdownParagraph(parsed);
+  if (!paragraph || !paragraph.children.every(isAllowedMarkdownInline)) {
+    throw new UnsafeSourceEditError("Rich Markdown did not round-trip as one safe inline block.");
+  }
+
+  const original = singleMarkdownParagraph(parseMarkdown(operation.oldValue));
+  if (original && toString(paragraph) === toString(original)) {
+    return operation.oldValue;
+  }
+  return markdown;
+}
+
+function parseMarkdown(value) {
+  try {
+    return fromMarkdown(value, {
+      extensions: [gfm()],
+      mdastExtensions: [gfmFromMarkdown()]
+    });
+  } catch {
+    return null;
+  }
+}
+
+function singleMarkdownParagraph(tree) {
+  return tree?.children?.length === 1 && tree.children[0].type === "paragraph"
+    ? tree.children[0]
+    : null;
+}
+
+function isAllowedMarkdownInline(node) {
+  return markdownInlineTypes.has(node.type) && (node.children || []).every(isAllowedMarkdownInline);
+}
+
+function htmlNodeToMdast(node) {
+  if (node.nodeName === "#text") return node.value ? [{ type: "text", value: node.value }] : [];
+  if (!node.tagName) return [];
+  const children = (node.childNodes || []).flatMap(htmlNodeToMdast);
+  if (node.tagName === "strong" || node.tagName === "b") return [{ type: "strong", children }];
+  if (node.tagName === "em" || node.tagName === "i") return [{ type: "emphasis", children }];
+  if (node.tagName === "code") return [{ type: "inlineCode", value: toString({ type: "paragraph", children }) }];
+  if (node.tagName === "br") return [{ type: "break" }];
+  if (node.tagName === "a") {
+    const href = node.attrs?.find((attribute) => attribute.name === "href")?.value || "";
+    return href ? [{ type: "link", url: href, children }] : children;
+  }
+  return children;
+}
+
+function assertOuterSpan(source, entry) {
+  if (!Number.isInteger(entry.outerStart) || !Number.isInteger(entry.outerEnd) || typeof entry.outerValue !== "string") {
+    throw new UnsafeSourceEditError("No verified outer source span exists for this element.");
+  }
+  if (source.slice(entry.outerStart, entry.outerEnd) !== entry.outerValue) {
+    throw new UnsafeSourceEditError("Source changed since the CMS build. Refusing unsafe edit.");
+  }
+}
+
+function sanitizeClassList(value) {
+  return String(value || "")
+    .split(/\s+/)
+    .filter((token) => /^[A-Za-z0-9_:/.[\]%-]+$/.test(token))
+    .join(" ");
+}
+
+function lineIndentAt(source, index) {
+  const lineStart = source.lastIndexOf("\n", Math.max(0, index - 1)) + 1;
+  return source.slice(lineStart, index).match(/^\s*/)?.[0] || "";
+}
+
+function createBlockId() {
+  const random = globalThis.crypto?.randomUUID?.().replaceAll("-", "");
+  return `block_${random || Math.random().toString(16).slice(2)}`
+}
+
+function escapeSourceValue(value, operation) {
+  const raw = String(value);
+  // Both branches write into .astro source, where a literal `{`/`}` is parsed as
+  // a JS expression — escapeAstroBraces neutralizes it. Braces are escaped last
+  // so the `&` in their entity form is not caught by the `&` replacement above.
+  if (operation.kind === "text") {
+    return escapeAstroBraces(raw.replaceAll("&", "&amp;").replaceAll("<", "&lt;"));
+  }
+  const quote = operation.quote || '"';
+  return escapeAstroBraces(raw
+    .replaceAll("&", "&amp;")
+    .replaceAll("<", "&lt;")
+    .replaceAll(">", "&gt;")
+    .replaceAll(quote, quote === '"' ? "&quot;" : "&#039;"));
+}

package/src/source-map-runtime.js

@@ -0,0 +1,184 @@
+import { fieldName } from "./fields.js";
+
+// Turns the build-time source map into safe runtime bindings.
+//
+// The important boundary is conservative matching: an entry receives a DOM id
+// only when the number and order of matching elements are unambiguous. If the
+// rendered page contains extra dynamic copies, the runtime leaves them unbound
+// instead of guessing which source span should be edited.
+export function createSourceMapRuntime({
+  state,
+  sourceMapData,
+  routeFromAstroFile,
+  routeFromMarkdownFile,
+  isFrontmatterEntry,
+  isMarkdownBodyEntry,
+  isVisible
+}) {
+  function loadSourceMap() {
+    const entries = sourceMapData?.entries || {};
+    state.allSourceMap = Object.entries(entries).map(([id, entry]) => ({
+      id,
+      ...entry,
+      fields: entry.fields || [...new Set((entry.operations || []).map(fieldName))]
+    }));
+    state.sourceMap = state.allSourceMap
+      .filter((entry) => !isFrontmatterEntry(entry))
+      .filter(entryMatchesCurrentRoute);
+    state.sourceMapById = new Map(state.sourceMap.map((entry) => [entry.id, entry]));
+    for (const entry of state.allSourceMap) state.sourceMapById.set(entry.id, entry);
+  }
+
+  function entryMatchesCurrentRoute(entry) {
+    const here = location.pathname.replace(/\/+$/, "") || "/";
+    if (isMarkdownBodyEntry(entry)) {
+      if (routeFromMarkdownFile(entry.file) === here) return true;
+      // A content-collection file renders on a route derived from its slug, not
+      // its path (src/content/blog/p.md → /blog/p). Matching by slug binds the
+      // whole post — including SHORT blocks like an "Example" heading that the
+      // content-presence fallback below skips (its ≥12-char guard drops them).
+      if (entryMatchesRouteSlug(entry, here)) return true;
+      // Otherwise content presence is the only route-independent signal.
+      return entryRenderedHere(entry);
+    }
+    return routeFromAstroFile(entry.file, here) === here;
+  }
+
+  function entryRenderedHere(entry) {
+    const pageText = normalizeRenderedText(document.body.innerText)
+      .replace(/[*_`#>~\[\]()]/g, "");
+    for (const operation of entry.operations || []) {
+      const clean = normalizeRenderedText(operation.oldValue).replace(/[*_`#>~\[\]()]/g, "");
+      if (clean.length >= 12 && pageText.includes(clean.slice(0, 40))) return true;
+    }
+    return false;
+  }
+
+  function applySourceMapIds() {
+    const groups = new Map();
+    for (const entry of state.sourceMap) {
+      if (entry.kind === "section-container") continue;
+      if (document.querySelector(`[data-charlescms-id="${CSS.escape(entry.id)}"]`)) continue;
+      const signature = entrySignature(entry);
+      if (!groups.has(signature)) groups.set(signature, []);
+      groups.get(signature).push(entry);
+    }
+
+    const here = location.pathname.replace(/\/+$/, "") || "/";
+    for (const group of groups.values()) {
+      let entries = group;
+      // Resolve same-text ambiguity by the URL: when entries with identical text
+      // come from different content-collection files, the one whose slug matches
+      // the current route is the page's content (Astro routes `/blog/b1` from
+      // `src/content/blog/b1.md`). This lets real collection content — and even
+      // duplicate-placeholder posts — bind correctly instead of being skipped.
+      if (entries.length > 1) {
+        const routed = entries.filter((entry) => entryMatchesRouteSlug(entry, here));
+        if (routed.length && routed.length < entries.length) entries = routed;
+      }
+      entries = [...entries].sort((a, b) => {
+        const byFile = String(a.file || "").localeCompare(String(b.file || ""));
+        return byFile || entrySourceOrder(a) - entrySourceOrder(b);
+      });
+      const candidates = [...document.querySelectorAll(entries[0].tag)]
+        .filter((element) => !element.closest("[data-charlescms-ui]"))
+        .filter((element) => !element.dataset.charlescmsId)
+        .filter(isVisible)
+        .filter((element) => elementMatchesEntry(element, entries[0]));
+
+      // Source-order pairing is safe only when both sides have the same count.
+      if (candidates.length !== entries.length) continue;
+      entries.forEach((entry, index) => {
+        candidates[index].dataset.charlescmsId = entry.id;
+        candidates[index].dataset.charlescmsFields = entry.fields.join(",");
+      });
+    }
+  }
+
+  function scanEditableElements(describeElement) {
+    // Visibility is intentionally not required here. Lazy or responsive content
+    // may have no layout during the first pass but still has a stable source id.
+    return [...document.querySelectorAll("[data-charlescms-id]")]
+      .filter((element) => !element.closest("[data-charlescms-ui]"))
+      .map(describeElement)
+      .filter(Boolean);
+  }
+
+  function entrySignature(entry) {
+    if (isMarkdownBodyEntry(entry)) {
+      return `${entry.tag}::markdown=${normalizeRenderedText(entry.text)}`;
+    }
+    if (entry.operations?.[0]?.kind === "block-html") {
+      return `${entry.tag}::block=${normalizeFragment(entry.operations[0].oldValue)}`;
+    }
+    return [entry.tag, ...entry.operations.map((operation) => `${operation.name}=${operation.oldValue}`)].join("::");
+  }
+
+  function elementMatchesEntry(element, entry) {
+    if (isMarkdownBodyEntry(entry)) {
+      return normalizeRenderedText(element.textContent) === normalizeRenderedText(entry.text);
+    }
+    for (const operation of entry.operations) {
+      if (operation.kind === "block-html") {
+        if (normalizeFragment(element.innerHTML) !== normalizeFragment(operation.oldValue)) return false;
+      } else if (operation.name === "text") {
+        if (!textMatchesSource(element, operation.oldValue)) return false;
+      } else {
+        const value = operation.name === "data" && element.tagName.toLowerCase() === "object"
+          ? element.data
+          : element.getAttribute(operation.name);
+        if (value !== operation.oldValue) return false;
+      }
+    }
+    return true;
+  }
+
+  return { loadSourceMap, applySourceMapIds, scanEditableElements };
+}
+
+function entrySourceOrder(entry) {
+  const starts = entry.operations
+    .map((operation) => operation.start)
+    .filter((value) => typeof value === "number");
+  return starts.length ? Math.min(...starts) : 0;
+}
+
+// A content-collection entry's slug: its path under src/content/<collection>/,
+// minus the extension (e.g. "src/content/blog/b1.md" -> "blog/b1", basename "b1").
+// Astro routes a collection entry by this slug, so it's how we tie a rendered
+// page to the right source file when several files share identical text.
+export function entryMatchesRouteSlug(entry, here) {
+  const match = String(entry.file || "").replace(/\\/g, "/")
+    .match(/src\/content\/[^/]+\/(.+?)\.(?:md|mdx|markdoc)$/i);
+  if (!match) return false;
+  const slug = match[1].replace(/^\/+|\/+$/g, "");
+  const route = String(here || "").replace(/^\/+|\/+$/g, "");
+  const segments = route.split("/").filter(Boolean);
+  const base = slug.split("/").pop();
+  return route === slug || route.endsWith(`/${slug}`) || segments.includes(base);
+}
+
+function normalizeRenderedText(value) {
+  return String(value || "")
+    .replace(/[\u2018\u2019\u201a\u201b]/g, "'")
+    .replace(/[\u201c\u201d\u201e\u201f]/g, '"')
+    .replace(/[\u2013\u2014]/g, "-")
+    .replace(/\s+/g, " ")
+    .trim();
+}
+
+function textMatchesSource(element, oldValue) {
+  if (element.textContent.trim() === oldValue) return true;
+  return normalizeFragment(element.innerHTML) === normalizeFragment(oldValue);
+}
+
+function normalizeFragment(html) {
+  const template = document.createElement("template");
+  template.innerHTML = String(html).trim();
+  for (const node of template.content.querySelectorAll("*")) {
+    for (const attribute of [...node.attributes]) {
+      if (attribute.name.startsWith("data-astro")) node.removeAttribute(attribute.name);
+    }
+  }
+  return template.innerHTML.trim();
+}

package/src/staged-panel.js

@@ -0,0 +1,145 @@
+// Lists every staged-but-unpublished change so the toolbar's count is never a
+// mystery. Because edits now persist across navigation, a change can live on a
+// page you're not currently looking at — this panel says exactly which page each
+// one is on, lets you VIEW a change on the current page (scroll to it + flash it),
+// or OPEN one on another page. Everything here publishes together.
+export function createStagedPanel({
+  state,
+  closeEditor,
+  mountPanel,
+  discardPending,
+  publishPending,
+  escapeHtml,
+  escapeAttribute
+}) {
+  function findChangeElement(pending, opName) {
+    // Jump to the element bound to the EXACT operation that changed (e.g. the one
+    // menu link that was renamed). If that operation has no element on the page,
+    // return null rather than flashing a DIFFERENT field of the same entry — a
+    // wrong highlight is more misleading than none.
+    if (opName) {
+      return document.querySelector(`[data-charlescms-bridge-entry="${CSS.escape(pending.id)}"][data-charlescms-bridge-op="${CSS.escape(opName)}"]`) || null;
+    }
+    return document.querySelector(`[data-charlescms-id="${CSS.escape(pending.id)}"]`)
+      || document.querySelector(`[data-charlescms-bridge-entry="${CSS.escape(pending.id)}"]`);
+  }
+
+  function viewChange(pending, opName) {
+    closeEditor();
+    const element = findChangeElement(pending, opName);
+    if (!element) return;
+    element.scrollIntoView({ behavior: "smooth", block: "center" });
+    element.classList.add("charlescms-flash");
+    setTimeout(() => element.classList.remove("charlescms-flash"), 1900);
+  }
+
+  function openStagedPanel() {
+    closeEditor();
+    const here = normalizeRoute(location.pathname);
+    const items = [...state.pending.values()];
+    const offPage = items.filter((pending) => normalizeRoute(pending.route) !== here).length;
+
+    const dialog = document.createElement("div");
+    dialog.dataset.charlescmsUi = "true";
+    dialog.className = "charlescms-panel";
+    dialog.innerHTML = `
+      <div class="charlescms-panel-header">
+        <div>
+          <div class="charlescms-kicker">Staged changes</div>
+          <div class="charlescms-title">${items.length} unpublished change${items.length === 1 ? "" : "s"}</div>
+        </div>
+        <button class="charlescms-icon-button" data-close aria-label="Close">×</button>
+      </div>
+      <p class="charlescms-panel-note">${items.length
+        ? `They all go live together when you publish.${offPage ? ` ${offPage} ${offPage === 1 ? "is" : "are"} on another page.` : ""}`
+        : "Nothing staged yet. Edits you make are collected here until you publish."}</p>
+      <div class="charlescms-versions-list" data-staged-list></div>
+      <div class="charlescms-actions">
+        ${items.length ? `<button class="charlescms-danger-button" data-discard-all>Discard all</button>` : ""}
+        <button data-close>Close</button>
+        ${items.length ? `<button data-save data-publish-all>Publish all</button>` : ""}
+      </div>
+    `;
+
+    const list = dialog.querySelector("[data-staged-list]");
+    for (const pending of items) {
+      const route = normalizeRoute(pending.route);
+      const onHere = route === here;
+      const change = describeChange(pending);
+      const row = document.createElement("div");
+      row.className = "charlescms-version";
+      row.innerHTML = `
+        <div>
+          <strong>${escapeHtml(change.detail)}</strong>
+          <span>${escapeHtml(change.title)} · ${onHere ? "on this page" : escapeHtml(route)}</span>
+        </div>`;
+      const action = document.createElement(onHere ? "button" : "a");
+      action.className = "charlescms-staged-go";
+      action.textContent = onHere ? "View" : "Open ↗";
+      if (onHere) {
+        action.type = "button";
+        action.addEventListener("click", () => viewChange(pending, change.key));
+      } else {
+        action.setAttribute("href", escapeAttribute(route));
+        action.addEventListener("click", closeEditor); // navigating shows the change on arrival
+      }
+      row.append(action);
+      list.append(row);
+    }
+
+    mountPanel(dialog);
+    for (const close of dialog.querySelectorAll("[data-close]")) close.addEventListener("click", closeEditor);
+    dialog.querySelector("[data-discard-all]")?.addEventListener("click", () => { closeEditor(); discardPending(); });
+    dialog.querySelector("[data-publish-all]")?.addEventListener("click", () => { closeEditor(); publishPending(); });
+  }
+
+  return { openStagedPanel };
+}
+
+function normalizeRoute(path) {
+  return String(path || "").replace(/[?#].*$/, "").replace(/\/+$/, "") || "/";
+}
+
+// Turn a staged edit into a human row: WHAT it now says (detail), a category
+// (title), and the exact operation that changed (key) so View can jump to it.
+function describeChange(pending) {
+  const next = pending.value || {};
+  const prev = pending.originalValue || {};
+  if (pending.type === "image" || pending.type === "asset" || pending.action === "delete" || "src" in next) {
+    return { title: "Image", detail: pending.action === "delete" ? "Removed" : "New image" };
+  }
+  if (typeof next.text === "string") {
+    return { title: "Text", detail: snippet(next.text) || "(empty)" };
+  }
+  const changed = Object.keys(next).filter((key) => String(next[key] ?? "") !== String(prev[key] ?? ""));
+  if (changed.length) {
+    const key = changed[0];
+    const more = changed.length > 1 ? ` (+${changed.length - 1} more)` : "";
+    const from = snippet(prev[key]);
+    const to = snippet(next[key]) || "(empty)";
+    return { title: fieldTitle(pending, key), detail: (from ? `${from} → ${to}` : to) + more, key };
+  }
+  return { title: pending.label || "Change", detail: snippet(Object.values(next)[0]) || "Updated" };
+}
+
+function fieldTitle(pending, key) {
+  if (/^item_?\d+(_(?:label|title|name|text))?$/i.test(key) || /link/i.test(key)) return "Menu link";
+  if (/title$/i.test(key)) return "Title";
+  if (/description$/i.test(key)) return "Description";
+  if (pending.type === "nav") return "Menu";
+  return pending.label || "Content";
+}
+
+// Plain, tag-free text for display — the user should never see raw HTML like
+// "<br>" or "<em>" in the Review list.
+function snippet(value) {
+  const raw = String(value ?? "");
+  let text = raw;
+  if (/[<&]/.test(raw)) {
+    const el = document.createElement("div");
+    el.innerHTML = raw;
+    text = el.textContent || "";
+  }
+  text = text.replace(/\s+/g, " ").trim();
+  return text.length > 42 ? `${text.slice(0, 42)}…` : text;
+}