@charlescms/astro 0.1.0

package/src/runtime-controller.js

@@ -0,0 +1,206 @@
+import { applyMediaPreviews } from "./media-preview.js";
+
+// Coordinates editor startup and repeatable DOM binding.
+//
+// Astro navigation and client-side hydration can replace page content without a
+// full reload. The controller therefore treats binding as an idempotent process:
+// source ids are resolved again, new elements receive edit actions, and a short
+// settle loop stops once the page has finished rendering.
+export function createRuntimeController({
+  state,
+  readConnectorConfig,
+  createConnectorClient,
+  closeEditor,
+  loadSourceMap,
+  applySourceMapIds,
+  restorePending,
+  applyValue,
+  applyBridgedValues,
+  addStyles,
+  installEditAffordance,
+  installToolbar,
+  installSectionControls,
+  scanEditableElements,
+  openEditor,
+  installContentBridge,
+  bindAssetImages,
+  downloadRepoPath,
+  isVisible
+}) {
+  async function start() {
+    if (state.initializedPath === location.pathname && state.toolbar?.isConnected) return;
+    resetEditorUi();
+    const config = readConnectorConfig();
+    state.authenticated = state.previewOnly || Boolean(config);
+    if (!state.authenticated) return;
+
+    state.connector = state.previewOnly ? null : createConnectorClient(config);
+    loadSourceMap();
+    applySourceMapIds();
+    // Bring any edits staged before a reload/navigation back into memory, then
+    // re-bind them to this page's DOM so the staged count and preview survive.
+    restorePending?.();
+    reconnectPendingEdits();
+    applyInitialEdits();
+    installEditor();
+    state.initializedPath = location.pathname;
+  }
+
+  function resetEditorUi() {
+    closeEditor();
+    state.toolbarObserver?.disconnect();
+    state.toolbarObserver = null;
+    state.lateObserver?.disconnect();
+    state.lateObserver = null;
+    for (const element of document.querySelectorAll("[data-charlescms-ui]")) element.remove();
+    for (const element of document.querySelectorAll(".charlescms-bridge")) {
+      element.classList.remove("charlescms-bridge");
+      delete element.dataset.charlescmsBridge;
+    }
+    state.affordanceCleanup?.();
+    state.affordanceCleanup = null;
+    state.affordanceInstalled = false;
+    document.documentElement.classList.remove("charlescms-active", "charlescms-links-mode");
+    state.toolbar = null;
+    state.sectionControls = [];
+  }
+
+  function reconnectPendingEdits() {
+    for (const pending of state.pending.values()) {
+      const element = document.querySelector(`[data-charlescms-id="${CSS.escape(pending.id)}"]`);
+      if (!element) continue;
+      pending.item.element = element;
+      applyValue(element, { type: pending.type, value: pending.value });
+    }
+  }
+
+  function applyInitialEdits() {
+    for (const edit of state.edits) {
+      const element = document.querySelector(`[data-charlescms-id="${CSS.escape(edit.id)}"]`);
+      if (element) applyValue(element, edit);
+    }
+  }
+
+  function installEditor() {
+    document.documentElement.classList.add("charlescms-active");
+    addStyles();
+    bindEditables();
+    installEditAffordance();
+    installToolbar();
+    installSectionControls();
+    watchForLateContent();
+  }
+
+  function bindEditables() {
+    applySourceMapIds();
+    for (const item of scanEditableElements()) {
+      if (item.element.dataset.charlescmsEditable === "true") continue;
+      item.element.dataset.charlescmsEditable = "true";
+      if (item.type === "link" || item.type === "download") {
+        attachLinkEditAction(item.element, () => openEditor(item));
+      } else {
+        item.element.charlescmsEdit = { open: () => openEditor(item), label: "✎ Edit" };
+      }
+    }
+    installDownloadReplacers();
+    // Astro-optimized images (astro:assets) aren't in the source map — their src is
+    // a hashed pipeline URL, not a literal path — so they're bound separately, by
+    // replacing the source asset in place.
+    bindAssetImages?.();
+    installContentBridge();
+    reapplyBridgedPending();
+    // Re-show any locally-previewed images on this (possibly newly navigated) page,
+    // so a replaced picture keeps showing until the real asset is served.
+    applyMediaPreviews();
+  }
+
+  // Bridged edits (data / nav / frontmatter) bind to elements by value, not by a
+  // source id, so reconnectPendingEdits can't restore their preview. Once the
+  // bridge has tagged this page's elements, push any staged values back into them
+  // so a reloaded or revisited page shows the staged preview, not the old text.
+  function reapplyBridgedPending() {
+    for (const pending of state.pending.values()) {
+      if (["data", "nav", "frontmatter"].includes(pending.type)) {
+        applyBridgedValues?.(pending.id, pending.value || {});
+      }
+    }
+  }
+
+  function watchForLateContent() {
+    const rebindIfActive = () => {
+      if (document.documentElement.classList.contains("charlescms-active")) bindEditables();
+    };
+    window.addEventListener("load", rebindIfActive, { once: true });
+
+    // A bounded settle loop covers streaming and delayed layout. It ends after
+    // three stable counts or forty attempts, so it cannot poll forever.
+    let last = -1;
+    let stableFor = 0;
+    let passes = 0;
+    const settle = () => {
+      if (!document.documentElement.classList.contains("charlescms-active")) return;
+      bindEditables();
+      const count = document.querySelectorAll('[data-charlescms-editable="true"]').length;
+      if (count === last) stableFor += 1;
+      else {
+        stableFor = 0;
+        last = count;
+      }
+      if (stableFor < 3 && (passes += 1) < 40) setTimeout(settle, 300);
+    };
+    setTimeout(settle, 120);
+
+    if (state.lateObserver) return;
+    let scheduled = false;
+    const observer = new MutationObserver((records) => {
+      const added = records.some((record) => [...record.addedNodes].some(
+        (node) => node.nodeType === 1 && !node.closest?.("[data-charlescms-ui]")
+      ));
+      if (!added || scheduled) return;
+      scheduled = true;
+      setTimeout(() => {
+        scheduled = false;
+        rebindIfActive();
+      }, 150);
+    });
+    observer.observe(document.body, { childList: true, subtree: true });
+    state.lateObserver = observer;
+  }
+
+  function installDownloadReplacers() {
+    for (const link of document.querySelectorAll("a[href]")) {
+      if (link.closest("[data-charlescms-ui]")) continue;
+      if (link.dataset.charlescmsEditable === "true") continue;
+      if (!isReplaceableDownload(link) || !isVisible(link)) continue;
+      link.dataset.charlescmsEditable = "true";
+      link.title = link.title || "Click to replace this file. Cmd/Ctrl+click opens it.";
+      link.addEventListener("click", (event) => {
+        if (event.metaKey || event.ctrlKey || event.shiftKey || event.altKey) return;
+        event.preventDefault();
+        event.stopPropagation();
+        openEditor({
+          id: null,
+          element: link,
+          fields: [],
+          type: "download",
+          value: {},
+          label: link.textContent.trim() || link.getAttribute("href") || "File"
+        });
+      });
+    }
+  }
+
+  function isReplaceableDownload(link) {
+    const href = link.getAttribute("href") || "";
+    if (!downloadRepoPath(href)) return false;
+    return link.hasAttribute("download")
+      || /\.(?:pdf|docx?|xlsx?|pptx?|csv|zip|rtf|odt|txt|pages|key|numbers)(?:[?#]|$)/i.test(href);
+  }
+
+  function attachLinkEditAction(element, open, label = "✎ Edit text") {
+    element.dataset.charlescmsEditable = "true";
+    element.charlescmsEdit = { open, label };
+  }
+
+  return { start, attachLinkEditAction };
+}

package/src/sanitize.js

@@ -0,0 +1,150 @@
+import { parseFragment, serialize } from "parse5";
+
+// Authoritative write-boundary allowlist sanitizer for rich-text fragments.
+// Client output is NEVER trusted: this is the security boundary that prevents
+// stored XSS from reaching the published site. Anything outside the allowlist
+// is unwrapped (markup dropped, text kept) or, for script/style, removed whole.
+const allowedTags = new Set(["strong", "em", "b", "i", "a", "span", "code", "small", "u", "mark", "br"]);
+const dropWithContentTags = new Set(["script", "style", "template", "iframe", "object", "embed", "noscript"]);
+const allowedAttributes = {
+  a: new Set(["href", "title"]),
+  span: new Set(["title"]),
+  abbr: new Set(["title"])
+};
+const urlAttributes = new Set(["href", "src"]);
+const allowedUrlSchemes = new Set(["http:", "https:", "mailto:", "tel:"]);
+const blockTags = new Set([
+  "h2", "h3", "h4", "p", "ul", "ol", "li", "blockquote", "figure",
+  "figcaption", "img", "a", "hr", "strong", "em", "code", "br"
+]);
+const blockAttributes = {
+  "*": new Set(["class", "title"]),
+  a: new Set(["class", "href", "title"]),
+  img: new Set(["class", "src", "alt", "title"])
+};
+
+/**
+ * Sanitize an inline rich-text fragment to the inline allowlist (bold, italic,
+ * links, …). Disallowed markup is unwrapped (text kept); script/style removed whole.
+ * @param {string} html Untrusted HTML from the editor.
+ * @returns {string} Safe HTML containing only allowlisted inline tags/attributes.
+ */
+export function sanitizeRichText(html) {
+  const fragment = parseFragment(String(html ?? ""));
+  sanitizeChildNodes(fragment, allowedTags, allowedAttributes);
+  return serialize(fragment);
+}
+
+/**
+ * Sanitize a block-level rich-text fragment (headings, lists, images, …) to the
+ * block allowlist, then neutralize Astro `{…}` braces so the result is content,
+ * never an expression.
+ * @param {string} html Untrusted HTML from the editor.
+ * @returns {string} Safe, brace-escaped block HTML.
+ */
+export function sanitizeBlockHtml(html) {
+  const fragment = parseFragment(String(html ?? ""));
+  sanitizeChildNodes(fragment, blockTags, blockAttributes);
+  return escapeAstroBraces(serialize(fragment));
+}
+
+/**
+ * Pure parse→serialize round-trip with NO filtering. Comparing
+ * `sanitizeBlockHtml(source)` against this tells whether the sanitizer actually
+ * CHANGED anything — without false alarms from harmless formatting the parser
+ * normalizes anyway (`<img />` vs `<img>`, attribute quoting, whitespace).
+ * @param {string} html HTML to normalize.
+ * @returns {string} The normalized, brace-escaped HTML.
+ */
+export function normalizeBlockHtml(html) {
+  return escapeAstroBraces(serialize(parseFragment(String(html ?? ""))));
+}
+
+/**
+ * Neutralize literal `{`/`}` so editor content is never read as an Astro
+ * expression. Astro reads `{…}` in markup as JS; editor values are content, never
+ * code, so braces reaching `.astro` source become HTML entities (the browser still
+ * renders a literal brace). Without this, typing "plans from {X}" would commit a
+ * file whose next `astro build` fails on an undefined-variable expression. Run
+ * only AFTER any `&`-escaping so the `&` these entities introduce isn't double-escaped.
+ * @param {string} value Text or serialized HTML to escape.
+ * @returns {string} The value with braces replaced by `&#123;`/`&#125;`.
+ */
+export function escapeAstroBraces(value) {
+  return String(value ?? "").replaceAll("{", "&#123;").replaceAll("}", "&#125;");
+}
+
+function sanitizeChildNodes(parent, tags, attributes) {
+  const result = [];
+  for (const node of parent.childNodes || []) {
+    if (node.nodeName === "#text") {
+      result.push(node);
+      continue;
+    }
+    if (!node.tagName) {
+      // Comments, doctypes, etc. are dropped.
+      continue;
+    }
+    const tag = node.tagName.toLowerCase();
+    if (dropWithContentTags.has(tag)) {
+      continue;
+    }
+    sanitizeChildNodes(node, tags, attributes);
+    if (!tags.has(tag)) {
+      // Unwrap: keep the (already sanitized) children, drop the tag itself.
+      result.push(...node.childNodes);
+      continue;
+    }
+    node.attrs = filterAttributes(tag, node.attrs || [], attributes);
+    result.push(node);
+  }
+  parent.childNodes = result;
+}
+
+function filterAttributes(tag, attrs, attributes) {
+  const allowed = new Set([
+    ...(attributes["*"] || []),
+    ...(attributes[tag] || [])
+  ]);
+  return attrs.filter((attribute) => {
+    const name = attribute.name.toLowerCase();
+    if (name.startsWith("on")) return false; // event handlers, always rejected
+    if (!allowed.has(name)) return false;
+    if (urlAttributes.has(name) && !isSafeUrl(attribute.value)) return false;
+    if (name === "class") {
+      if (!isSafeClassList(attribute.value)) return false;
+      // Strip the editor's own runtime classes (charlescms-editing, charlescms-pm,
+      // …) so they can never persist into committed source. Left behind, an
+      // element would read as "already editing" and become silently uneditable.
+      attribute.value = stripEditorClasses(attribute.value);
+      if (!attribute.value) return false; // nothing left → drop the empty class
+    }
+    return true;
+  });
+}
+
+function stripEditorClasses(value) {
+  return String(value || "")
+    .split(/\s+/)
+    .filter((token) => token && !token.startsWith("charlescms-"))
+    .join(" ");
+}
+
+function isSafeClassList(value) {
+  return String(value || "")
+    .split(/\s+/)
+    .filter(Boolean)
+    .every((token) => /^[A-Za-z0-9_:/.[\]%-]+$/.test(token));
+}
+
+// Relative URLs and anchors are safe. For absolute URLs, only an explicit scheme
+// allowlist passes — blocking javascript:, data:, vbscript: (incl. obfuscation
+// with control characters/whitespace, which browsers ignore before the scheme).
+function isSafeUrl(value) {
+  const stripped = Array.from(String(value ?? ""))
+    .filter((char) => char.charCodeAt(0) > 0x20)
+    .join("");
+  const scheme = stripped.match(/^([a-zA-Z][a-zA-Z0-9+.-]*):/);
+  if (!scheme) return true;
+  return allowedUrlSchemes.has(`${scheme[1].toLowerCase()}:`);
+}