@charlescms/astro 0.1.0

package/src/publishing.js

@@ -0,0 +1,457 @@
+import { registerMediaPreview } from "./media-preview.js";
+
+// Manages the edit transaction from local preview to connector commit.
+//
+// Feature editors call `stageEdit` and update the live DOM. This module keeps
+// the original value for discard, serializes verified publish payloads, and owns
+// immediate binary uploads whose source path must remain unchanged.
+export function createPublishing({
+  state,
+  applyValue,
+  applyBridgedValues,
+  closeEditor,
+  renderPendingTray,
+  setToolbarStatus,
+  setBusy,
+  waitForLivePage
+}) {
+  // While a deployed site rebuilds after a publish, editing must pause: the page
+  // is still serving the OLD build (old source map, old assets), so any further
+  // edit would be made against stale data and fail or look wrong. This full-screen
+  // lock makes the wait explicit and blocks interaction until the new build lands.
+  function showPublishingLock(message, onDismiss) {
+    let overlay = document.querySelector(".charlescms-publishing");
+    if (!overlay) {
+      overlay = document.createElement("div");
+      overlay.dataset.charlescmsUi = "true";
+      overlay.className = "charlescms-publishing";
+      document.body.append(overlay);
+    }
+    overlay.innerHTML = `
+      <div class="charlescms-publishing-card">
+        <div class="charlescms-spinner" aria-hidden="true"></div>
+        <strong>Publishing your changes…</strong>
+        <span>${message}</span>
+        ${onDismiss ? `<button type="button" class="charlescms-publishing-dismiss" data-dismiss>Keep editing — I'll wait</button>` : ""}
+      </div>`;
+    if (onDismiss) overlay.querySelector("[data-dismiss]")?.addEventListener("click", onDismiss);
+    return overlay;
+  }
+  function hidePublishingLock() {
+    document.querySelector(".charlescms-publishing")?.remove();
+  }
+  // Staged edits are mirrored into sessionStorage so they survive navigation, a
+  // full reload, and same-origin new tabs — instead of evaporating the moment the
+  // editor leaves the page. The DOM element and any live preview node are dropped
+  // (they belong to one page); the source-map entry IS kept so a staged edit can
+  // still publish after the page it was made on is no longer the current one.
+  const PENDING_STORAGE_KEY = "charlescms_pending";
+
+  function persistPending() {
+    try {
+      const out = [];
+      for (const [key, pending] of state.pending.entries()) {
+        const { item, preview, ...rest } = pending;
+        out.push({ key, ...rest, entry: rest.entry || state.sourceMapById.get(pending.id) || null, itemValue: item?.value });
+      }
+      if (out.length) sessionStorage.setItem(PENDING_STORAGE_KEY, JSON.stringify(out));
+      else sessionStorage.removeItem(PENDING_STORAGE_KEY);
+    } catch {}
+  }
+
+  // Rehydrate staged edits from storage into state.pending. The runtime's existing
+  // reconnectPendingEdits() then re-binds them to this page's DOM and re-applies
+  // the preview. In-memory entries (still present after an SPA transition) win.
+  function restorePending() {
+    let saved = null;
+    try { saved = JSON.parse(sessionStorage.getItem(PENDING_STORAGE_KEY) || "null"); } catch { saved = null; }
+    if (!Array.isArray(saved)) return;
+    for (const snapshot of saved) {
+      if (!snapshot?.key || state.pending.has(snapshot.key)) continue;
+      const { key, itemValue, ...rest } = snapshot;
+      state.pending.set(key, { ...rest, item: { id: rest.id, value: itemValue, element: null } });
+    }
+  }
+
+  function stageEdit(item, value, payload) {
+    const key = payload.pendingKey || item.id;
+    const existing = state.pending.get(key);
+    state.pending.set(key, {
+      ...payload,
+      value: cloneValue(value),
+      item,
+      entry: state.sourceMapById.get(payload.id || item.id) || existing?.entry,
+      originalValue: existing?.originalValue || cloneValue(item.value)
+    });
+    item.value = cloneValue(value);
+    persistPending();
+    renderPendingTray();
+    reportStagedCount();
+  }
+
+  function discardPending() {
+    if (state.busy || state.pending.size === 0) return;
+    for (const pending of state.pending.values()) {
+      if (pending.preview?.kind === "hide" && pending.preview.element) {
+        pending.preview.element.hidden = false;
+      } else if (pending.preview?.kind === "remove" && pending.preview.element) {
+        pending.preview.element.remove();
+      } else if (pending.item?.element) {
+        applyValue(pending.item.element, { type: pending.type, value: pending.originalValue });
+      } else if (["data", "nav", "frontmatter"].includes(pending.type)) {
+        // Bridged form edits updated the page on Save; restore those elements
+        // from the staged original so Discard really rewinds the preview.
+        applyBridgedValues?.(pending.id, pending.originalValue || {});
+      }
+      if (pending.item) pending.item.value = cloneValue(pending.originalValue);
+    }
+    state.pending.clear();
+    persistPending();
+    renderPendingTray();
+    setToolbarStatus("Preview discarded.");
+  }
+
+  async function publishPending() {
+    if (state.busy) return;
+    if (state.pending.size === 0) {
+      setToolbarStatus("No changes to publish.");
+      return;
+    }
+    setBusy(true, "Publishing changes...");
+    const published = [];
+    const commits = [];
+    const here = normalizeRoute(location.pathname);
+    const liveMarkers = [];
+    try {
+      // Resolve each edit's verified source entry. For plain content edits, commit
+      // same-file edits BOTTOM-UP (highest byte offset first): committing a later
+      // edit only shifts bytes after it, so an earlier edit's offsets stay valid
+      // against the freshly re-read file — without this, the 2nd+ content edit in
+      // one file drifts and fails. Section/media ops carry an `action` and can
+      // depend on each other's order, so if ANY are present we keep staging order.
+      const queue = [...state.pending.entries()].map(([key, pending]) => ({
+        key,
+        pending,
+        entry: state.sourceMapById.get(pending.id) || pending.entry
+      }));
+      if (queue.every(({ pending }) => !pending.action)) {
+        queue.sort((a, b) => {
+          const fa = a.entry?.file || "";
+          const fb = b.entry?.file || "";
+          if (fa !== fb) return fa < fb ? -1 : 1;
+          return entryStart(b.entry) - entryStart(a.entry);
+        });
+      }
+      for (const { key, pending, entry } of queue) {
+        if (!entry) throw new Error("No verified source-map entry exists for this element.");
+        const result = await state.connector.applyEdit(entry, {
+          id: pending.id,
+          type: pending.type,
+          action: pending.action,
+          anchorId: pending.anchorId,
+          position: pending.position,
+          route: pending.route,
+          value: pending.value,
+          label: pending.label,
+          original: pending.original,
+          message: commitMessage(pending)
+        });
+        if (result.commit) commits.push(result.commit);
+        published.push(key);
+        // Markers from edits on THIS page let us detect when the rebuilt site is
+        // actually serving the change — using the part of each field that DIFFERS
+        // from its old value, so we never match the old build and reload into
+        // stale content (the "it reset after publish" bug).
+        if (normalizeRoute(pending.route) === here) {
+          const next = pending.value || {};
+          const prev = pending.originalValue || {};
+          for (const key of Object.keys(next)) {
+            const marker = liveMarker(next[key], prev[key]);
+            if (marker) liveMarkers.push(marker);
+          }
+        }
+      }
+      state.pending.clear();
+      persistPending();
+      renderPendingTray();
+      const count = published.length;
+      const plural = count === 1 ? "" : "s";
+
+      // Dev mirrors the new source to disk immediately, so a quick reload gives a
+      // fresh, byte-consistent map.
+      if (import.meta.env?.DEV && count && !window.__CHARLESCMS_NO_RELOAD__ && !window.__CHARLESCMS_FORCE_PUBLISH_WAIT__) {
+        setToolbarStatus(`Published ${count} change${plural}.`);
+        setTimeout(() => location.reload(), 700);
+        return;
+      }
+      if (window.__CHARLESCMS_NO_RELOAD__) {
+        setToolbarStatus(`Published ${count} change${plural}.`);
+        return;
+      }
+
+      // Deployed: the live site still serves the OLD build until it rebuilds. Only
+      // reload once we can CONFIRM the new content is being served (a change marker
+      // appears) — reloading on mere reachability would drop us back onto the stale
+      // build and look like the edit "reset". The applied preview stays on screen
+      // meanwhile, so the user keeps seeing their change. If we can't confirm (no
+      // marker, or it times out), we keep the preview and let them reload when ready.
+      if (liveMarkers.length && waitForLivePage) {
+        let dismissed = false;
+        const dismiss = () => {
+          dismissed = true;
+          hidePublishingLock();
+          setBusy(false);
+          setToolbarStatus(`Published ${count} change${plural}. Your site is updating in the background — reload when you want the latest.`);
+        };
+        showPublishingLock("Your site is rebuilding — usually under a minute. The editor refreshes automatically when your changes are live.", dismiss);
+        const live = await waitForLivePage(liveMarkers);
+        if (dismissed) return; // user chose to keep editing; don't yank the page out
+        if (live) {
+          showPublishingLock("Changes are live — refreshing…");
+          location.reload();
+          return;
+        }
+        hidePublishingLock();
+      }
+      setBusy(false);
+      setToolbarStatus(`Published ${count} change${plural}. Your site is updating — reload the page in a minute to keep editing.`);
+      return;
+    } catch (error) {
+      // Successfully committed entries are removed; failed and later entries
+      // stay staged so the editor can retry without recreating their preview.
+      for (const key of published) state.pending.delete(key);
+      persistPending();
+      renderPendingTray();
+      setToolbarStatus(readablePublishError(error));
+    } finally {
+      setBusy(false);
+    }
+  }
+
+  async function uploadActiveMedia(event) {
+    if (!state.active || state.previewOnly) return;
+    const file = event.target.files?.[0];
+    if (!file) return;
+    const { dialog, item } = state.active;
+    const fieldName = primaryMediaField(item);
+    const input = dialog.querySelector(`[data-field="${CSS.escape(fieldName)}"]`);
+    if (!input) return;
+    // Block Save while the upload is in flight. Saving mid-upload stages the OLD
+    // path (the field isn't updated until the commit returns), so the new image
+    // wouldn't appear — that's the "I had to press Save twice / only every second
+    // change works" bug. Disabling Save means the first Save always has the upload.
+    const saveButton = dialog.querySelector("[data-save]");
+    event.target.disabled = true;
+    if (saveButton) saveButton.disabled = true;
+    setToolbarStatus("Uploading image…");
+    try {
+      const name = `${Date.now()}-${safeMediaFileName(file.name || "upload.bin")}`;
+      const repoPath = `public/uploads/${name}`;
+      await state.connector.putBase64(repoPath, await fileToBase64(file), { message: `Upload media: ${repoPath}` });
+      registerMediaPreview(`/uploads/${name}`, file);
+      input.value = `/uploads/${name}`;
+      setToolbarStatus("Image uploaded — click Save to keep it.");
+    } catch (error) {
+      showPanelError(dialog, error.message || "Upload failed.");
+    } finally {
+      event.target.disabled = false;
+      if (saveButton) saveButton.disabled = false;
+    }
+  }
+
+  async function replaceDownloadFile(event) {
+    if (!state.active || state.previewOnly) return;
+    const file = event.target.files?.[0];
+    if (!file) return;
+    const { dialog, item } = state.active;
+    const repoPath = downloadRepoPath(item.element?.getAttribute("href") || item.element?.getAttribute("src") || "");
+    if (!repoPath) {
+      showPanelError(dialog, "This link points to an external or dynamic file that can't be replaced here.");
+      return;
+    }
+    event.target.disabled = true;
+    try {
+      // GitHub needs the current blob SHA when an existing file is overwritten.
+      const existing = await state.connector.getFile(repoPath).catch(() => null);
+      await state.connector.putBase64(repoPath, await fileToBase64(file), {
+        sha: existing?.sha,
+        message: `Replace download: ${repoPath}`
+      });
+      setToolbarStatus(`Replaced ${repoPath}. Redeploy to serve the new file.`);
+    } catch (error) {
+      showPanelError(dialog, error.message || "Replace failed.");
+    } finally {
+      event.target.disabled = false;
+    }
+  }
+
+  function removeActiveMedia() {
+    if (!state.active || state.busy) return;
+    const { item } = state.active;
+    if (!isMediaItem(item) || !window.confirm("Remove this media item from the page preview?")) return;
+    const key = `${item.id}:delete`;
+    const existing = state.pending.get(key);
+    state.pending.set(key, {
+      id: item.id,
+      type: item.type,
+      action: "delete",
+      route: location.pathname,
+      value: {},
+      label: item.label,
+      original: JSON.stringify(item.value),
+      item,
+      entry: state.sourceMapById.get(item.id),
+      originalValue: existing?.originalValue || cloneValue(item.value),
+      preview: { kind: "hide", element: item.element }
+    });
+    item.element.hidden = true;
+    closeEditor();
+    persistPending();
+    renderPendingTray();
+    reportStagedCount();
+  }
+
+  function branchHint() {
+    const branch = state.connector?.config?.branch;
+    return branch
+      ? `the branch "${branch}" was not found (log out and reconnect, leaving the branch blank to use the repository default)`
+      : "the branch or repository was not found";
+  }
+
+  function readablePublishError(error) {
+    const message = readableSaveError(error?.message || "Publish failed.");
+    if (error?.status === 401) return "Publish failed: your editor session is no longer authorized. Log in again.";
+    if (error?.status === 403) return `Publish failed: this origin or repository is not allowed. ${message}`;
+    if (error?.status === 404) return `Publish failed: ${branchHint()} or the GitHub App isn't installed on the repository.`;
+    if (error?.status === 409) return `Publish conflicted with a newer source version. ${message}`;
+    if (error?.status === 422) return `GitHub rejected the publish request. ${message}`;
+    return `Publish failed: ${message}`;
+  }
+
+  function reportStagedCount() {
+    setToolbarStatus(`${state.pending.size} change${state.pending.size === 1 ? "" : "s"} staged.`);
+  }
+
+  return {
+    stageEdit,
+    discardPending,
+    publishPending,
+    restorePending,
+    uploadActiveMedia,
+    replaceDownloadFile,
+    removeActiveMedia,
+    branchHint
+  };
+}
+
+function normalizeRoute(path) {
+  return String(path || "").replace(/[?#].*$/, "").replace(/\/+$/, "") || "/";
+}
+
+// The smallest source byte offset an entry touches — used to publish same-file
+// edits bottom-up so their offsets stay valid as the file is rewritten.
+function entryStart(entry) {
+  const starts = (entry?.operations || []).map((operation) => operation.start).filter((value) => Number.isFinite(value));
+  return starts.length ? Math.min(...starts) : 0;
+}
+
+// Plain text of a (possibly HTML) value: strips tags and decodes entities so a
+// marker matches the rendered page, not the raw markup.
+function plainText(value) {
+  const raw = String(value ?? "");
+  if (!/[<&]/.test(raw)) return raw;
+  const el = document.createElement("div");
+  el.innerHTML = raw;
+  return (el.textContent || "").replace(/\s+/g, " ").trim();
+}
+
+// A marker the REBUILT page will contain but the OLD build won't: the region of
+// the new value that diverges from the old. This is what makes "wait until the
+// deploy serves my change" reliable — matching the unchanged start of a field
+// (e.g. "Good food…") would falsely report the old build as live and reload into
+// stale content.
+export function liveMarker(newValue, oldValue) {
+  const next = plainText(newValue);
+  const prev = plainText(oldValue);
+  if (!next || next === prev) return "";
+  let i = 0;
+  while (i < next.length && i < prev.length && next[i] === prev[i]) i++;
+  for (let len = 24; len >= 4; len -= 4) {
+    const candidate = next.slice(Math.max(0, i - 4), Math.max(0, i - 4) + len).trim();
+    if (candidate.length >= 4 && !prev.includes(candidate)) return candidate;
+  }
+  return !prev.includes(next) && next.length >= 4 ? next.slice(0, 40) : "";
+}
+
+export function downloadRepoPath(href) {
+  const value = String(href || "").trim();
+  if (!value || !value.startsWith("/") || value.startsWith("//")) return null;
+  const clean = value.split(/[?#]/)[0].replace(/^\/+/, "");
+  if (!clean || clean.split("/").includes("..")) return null;
+  return `public/${clean}`;
+}
+
+export function fileToBase64(file) {
+  return new Promise((resolve, reject) => {
+    const reader = new FileReader();
+    reader.addEventListener("load", () => {
+      const result = String(reader.result || "");
+      resolve(result.includes(",") ? result.split(",").pop() : result);
+    });
+    reader.addEventListener("error", () => reject(reader.error || new Error("Could not read file.")));
+    reader.readAsDataURL(file);
+  });
+}
+
+export function safeMediaFileName(name) {
+  const cleaned = String(name)
+    .split(/[\\/]/)
+    .pop()
+    .toLowerCase()
+    .replace(/[^a-z0-9._-]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .slice(0, 96);
+  return cleaned || "upload.bin";
+}
+
+export function showPanelError(dialog, message) {
+  let error = dialog.querySelector("[data-error]");
+  if (!error) {
+    error = document.createElement("div");
+    error.dataset.error = "true";
+    error.className = "charlescms-error";
+    dialog.insertBefore(error, dialog.querySelector(".charlescms-actions"));
+  }
+  error.textContent = message;
+}
+
+function readableSaveError(message) {
+  if (/Source changed since the CMS build|No verified source-map entry|Source-map entry/i.test(message)) {
+    return "This source location changed after the last CMS build. Redeploy the site, then edit it again.";
+  }
+  if (/Build validation failed/i.test(message)) return "The change was rolled back because the build failed afterwards.";
+  if (/Too many/i.test(message)) return "Too many attempts. Wait briefly and try again.";
+  return message;
+}
+
+function commitMessage(pending) {
+  if (pending.action === "delete" && pending.type === "section") return `Remove section: ${pending.label || pending.id}`;
+  if (pending.action === "delete") return `Remove media: ${pending.label || pending.id}`;
+  if (pending.action === "insert") return `Add section: ${pending.label || pending.id}`;
+  if (pending.type === "section") return `Update section: ${pending.label || pending.id}`;
+  return `Update content: ${pending.label || pending.id}`;
+}
+
+function primaryMediaField(item) {
+  if (item.fields.includes("src")) return "src";
+  if (item.fields.includes("data")) return "data";
+  return item.fields[0] || "src";
+}
+
+function isMediaItem(item) {
+  return item?.type === "image" || item?.type === "asset";
+}
+
+function cloneValue(value) {
+  return JSON.parse(JSON.stringify(value || {}));
+}

package/src/rich-text-editor.js

@@ -0,0 +1,209 @@
+// Runs inline rich-text editing while preserving the page's existing block tag.
+//
+// `loadTiptap` is injected from client.js so the package's dynamic imports stay
+// directly in Vite's entry module. This avoids the known file-install optimizer
+// issue without mixing editor behavior back into the main orchestrator.
+export function createRichTextEditor({
+  state,
+  loadTiptap,
+  stageEdit,
+  setToolbarStatus,
+  escapeHtml,
+  escapeAttribute
+}) {
+  async function openRichTextInline(item) {
+    const element = item.element;
+    const original = item.value.text;
+    element.classList.add("charlescms-editing");
+    if (hasInvisibleTextFill(element)) element.classList.add("charlescms-editing-plain");
+
+    let editor;
+    try {
+      const { Editor, Document, Text, Bold, Italic, Code, HardBreak, Link } = await loadTiptap();
+      element.innerHTML = "";
+      editor = new Editor({
+        element,
+        content: original || "",
+        // An inline-only schema prevents Tiptap from adding a paragraph wrapper
+        // inside a heading, paragraph, label, or other existing page element.
+        extensions: [
+          Document.extend({ content: "inline*" }),
+          Text,
+          Bold,
+          Italic,
+          Code,
+          HardBreak,
+          Link.configure({ openOnClick: false, autolink: false, protocols: ["http", "https", "mailto", "tel"] })
+        ],
+        editorProps: { attributes: { class: "charlescms-pm", spellcheck: "true" } }
+      });
+      editor.commands.focus("end");
+    } catch (error) {
+      console.error("[CharlesCMS] rich-text editor failed to load:", error);
+      element.classList.remove("charlescms-editing", "charlescms-editing-plain");
+      element.innerHTML = original;
+      setToolbarStatus("Could not open the editor - please retry.");
+      return;
+    }
+
+    const toolbar = createRichTextToolbar();
+    document.body.append(toolbar);
+    const reposition = () => positionToolbar(toolbar, element);
+    reposition();
+    window.addEventListener("scroll", reposition, true);
+    window.addEventListener("resize", reposition);
+
+    const finish = (saved, savedHtml) => {
+      window.removeEventListener("scroll", reposition, true);
+      window.removeEventListener("resize", reposition);
+      toolbar.remove();
+      editor?.destroy();
+      element.classList.remove("charlescms-editing", "charlescms-editing-plain");
+      element.innerHTML = saved ? savedHtml : original;
+      state.active = null;
+    };
+
+    // Keep focus in ProseMirror when toolbar buttons are pressed.
+    toolbar.addEventListener("mousedown", (event) => event.preventDefault());
+    toolbar.addEventListener("click", async (event) => {
+      const command = event.target.closest("[data-cmd]")?.dataset.cmd;
+      if (command) {
+        applyRichCommand(editor, command);
+        return;
+      }
+      if (event.target.closest("[data-rt-cancel]")) {
+        finish(false);
+        return;
+      }
+      if (event.target.closest("[data-rt-save]")) {
+        const html = serializeTiptapHtml(editor.getHTML(), escapeHtml, escapeAttribute);
+        stageRichText(item, html);
+        finish(true, html);
+      }
+    });
+
+    state.active = { inline: true, finish };
+  }
+
+  function stageRichText(item, html) {
+    // A DRAFT element (inside a not-yet-published section) has no source span to
+    // stage against — its single source of truth is the pending insert's HTML.
+    // The caller provides draftSave to absorb the edit there instead.
+    if (item.draftSave) {
+      item.draftSave(html);
+      return;
+    }
+    const value = item.fields.includes("body") ? { text: html, body: html } : { text: html };
+    stageEdit(item, value, {
+      id: item.id,
+      type: "richtext",
+      route: location.pathname,
+      value,
+      label: item.label,
+      original: item.value.text
+    });
+  }
+
+  function positionToolbar(toolbar, element) {
+    const rect = element.getBoundingClientRect();
+    const margin = 8;
+    const toolbarTop = state.toolbar?.getBoundingClientRect().top || window.innerHeight;
+    const above = rect.top - toolbar.offsetHeight - margin;
+    const below = rect.bottom + margin;
+    const top = above >= margin ? above : Math.min(below, toolbarTop - toolbar.offsetHeight - margin);
+    const left = Math.max(margin, Math.min(rect.left, window.innerWidth - toolbar.offsetWidth - margin));
+    toolbar.style.top = `${Math.max(margin, top)}px`;
+    toolbar.style.left = `${left}px`;
+  }
+
+  return { openRichTextInline };
+}
+
+function createRichTextToolbar() {
+  const toolbar = document.createElement("div");
+  toolbar.dataset.charlescmsUi = "true";
+  toolbar.className = "charlescms-rt-toolbar";
+  toolbar.innerHTML = `
+    <div class="charlescms-rt-row">
+      <button type="button" data-cmd="bold" title="Bold"><b>B</b></button>
+      <button type="button" data-cmd="italic" title="Italic"><i>I</i></button>
+      <button type="button" data-cmd="link" title="Link">&#128279;</button>
+      <button type="button" data-cmd="clear" title="Clear formatting">⌫</button>
+      <span class="charlescms-rt-sep"></span>
+      <button type="button" data-rt-cancel>Cancel</button>
+      <button type="button" data-rt-save>Save</button>
+    </div>
+  `;
+  return toolbar;
+}
+
+function hasInvisibleTextFill(element) {
+  const style = getComputedStyle(element);
+  const clip = `${style.webkitBackgroundClip || ""} ${style.backgroundClip || ""}`;
+  if (clip.includes("text")) return true;
+  const fill = style.webkitTextFillColor || style.color || "";
+  return /,\s*0(?:\.0+)?\)\s*$/.test(fill);
+}
+
+function applyRichCommand(editor, command) {
+  if (!editor) return;
+  const chain = editor.chain().focus();
+  if (command === "bold") chain.toggleBold().run();
+  else if (command === "italic") chain.toggleItalic().run();
+  else if (command === "clear") chain.unsetAllMarks().run();
+  else if (command === "link") {
+    const previous = editor.getAttributes("link")?.href || "";
+    const url = window.prompt("Link URL", previous);
+    if (url === null) chain.run();
+    else if (url.trim() === "") chain.unsetLink().run();
+    else if (isSafeClientUrl(url)) chain.extendMarkRange("link").setLink({ href: url.trim() }).run();
+    else chain.run();
+  }
+}
+
+function serializeTiptapHtml(html, escapeHtml, escapeAttribute) {
+  const container = document.createElement("div");
+  container.innerHTML = html;
+  return serializeRichText(container, escapeHtml, escapeAttribute);
+}
+
+// Canonicalize browser/Tiptap HTML to the same small inline subset accepted by
+// the server sanitizer. Unknown wrappers are removed but their text is retained.
+function serializeRichText(element, escapeHtml, escapeAttribute) {
+  const mapping = {
+    strong: "strong",
+    b: "strong",
+    em: "em",
+    i: "em",
+    a: "a",
+    code: "code",
+    br: "br",
+    small: "small",
+    mark: "mark",
+    u: "u"
+  };
+  const serializeNode = (node) => {
+    if (node.nodeType === Node.TEXT_NODE) return escapeHtml(node.nodeValue);
+    if (node.nodeType !== Node.ELEMENT_NODE) return "";
+    const tag = node.tagName.toLowerCase();
+    const inner = [...node.childNodes].map(serializeNode).join("");
+    const mapped = mapping[tag];
+    if (!mapped) return inner;
+    if (mapped === "br") return "<br>";
+    if (mapped === "a") {
+      const href = node.getAttribute("href") || "";
+      return isSafeClientUrl(href) ? `<a href="${escapeAttribute(href)}">${inner}</a>` : inner;
+    }
+    return `<${mapped}>${inner}</${mapped}>`;
+  };
+  return [...element.childNodes].map(serializeNode).join("").trim();
+}
+
+function isSafeClientUrl(value) {
+  const stripped = Array.from(String(value ?? ""))
+    .filter((character) => character.charCodeAt(0) > 0x20)
+    .join("");
+  const scheme = stripped.match(/^([a-zA-Z][a-zA-Z0-9+.-]*):/);
+  if (!scheme) return true;
+  return ["http:", "https:", "mailto:", "tel:"].includes(`${scheme[1].toLowerCase()}:`);
+}

package/src/routes.js

@@ -0,0 +1,21 @@
+// Converts source files under src/pages into the routes where their content can
+// appear. Dynamic route syntax is preserved; callers decide whether it matches
+// the current browser route.
+export function routeFromAstroFile(file, fallback = "/") {
+  const path = String(file || "").replace(/\\/g, "/");
+  const match = path.match(/(?:^|\/)src\/pages\/(.+)\.astro$/);
+  if (!match) return fallback;
+  return routeFromPagePath(match[1]);
+}
+
+export function routeFromMarkdownFile(file) {
+  const path = String(file || "").replace(/\\/g, "/");
+  const match = path.match(/(?:^|\/)src\/pages\/(.+)\.(?:md|mdx)$/);
+  if (!match) return null;
+  return routeFromPagePath(match[1]);
+}
+
+function routeFromPagePath(pagePath) {
+  const page = pagePath.replace(/\/index$/, "");
+  return page === "index" || page === "" ? "/" : `/${page}`;
+}