feat: draft mode API routes + review follow-ups (#678)

codercatdev · web-flow · commit 3b128744f541 · 2026-03-16T17:39:59.000-04:00
Completes Visual Editing end-to-end:\n\nDraft mode routes:\n- /api/draft-mode/enable — validates SANITY_PREVIEW_SECRET (fail-closed: 503 if missing, 401 if invalid), sets httpOnly cookie, redirects\n- /api/draft-mode/disable — clears cookie, redirects\n\nPer-request draft mode:\n- loadQuery() accepts draftMode param (from Astro.cookies)\n- isDraftMode() checks site-wide env var OR per-request cookie\n- All 12 content pages pass cookie state to loadQuery\n- BaseLayout checks cookie OR env var for VisualEditing component\n\nReview follow-ups:\n- escapeXml extracted to src/utils/xml.ts (was duplicated in both RSS files)\n- Sitemap static page lastmod uses latest content _updatedAt (not new Date())"
diff --git a/apps/web/src/layouts/BaseLayout.astro b/apps/web/src/layouts/BaseLayout.astro
@@ -10,7 +10,8 @@ interface Props {
 const { title, description = "CodingCat.dev — Purrfect Web Tutorials" } = Astro.props;
 
 const visualEditingEnabled =
-  import.meta.env.PUBLIC_SANITY_VISUAL_EDITING_ENABLED === "true";
+  import.meta.env.PUBLIC_SANITY_VISUAL_EDITING_ENABLED === "true" ||
+  Astro.cookies.has("__sanity_preview");
 ---
 
 <!doctype html>
diff --git a/apps/web/src/pages/[slug].astro b/apps/web/src/pages/[slug].astro
@@ -14,7 +14,8 @@ if (reservedSlugs.includes(slug!)) {
   return Astro.redirect(`/${slug}`);
 }
 
-const { data: page } = await loadQuery<any>({ query: pageQuery, params: { slug } });
+const draftMode = Astro.cookies.has("__sanity_preview");
+const { data: page } = await loadQuery<any>({ query: pageQuery, params: { slug }, draftMode });
 
 if (!page) {
   return new Response(null, { status: 404 });
diff --git a/apps/web/src/pages/api/draft-mode/disable.ts b/apps/web/src/pages/api/draft-mode/disable.ts
@@ -0,0 +1,20 @@
+/**
+ * Disable draft mode for Sanity Visual Editing.
+ *
+ * Clears the preview cookie and redirects back to the page.
+ *
+ * Usage: /api/draft-mode/disable?slug=/post/my-post
+ */
+import type { APIRoute } from "astro";
+
+export const prerender = false;
+
+export const GET: APIRoute = async ({ url, cookies, redirect }) => {
+  const slug = url.searchParams.get("slug") || "/";
+
+  // Delete the preview cookie
+  cookies.delete("__sanity_preview", { path: "/" });
+
+  // Redirect back to the page (now showing published content)
+  return redirect(slug, 307);
+};
diff --git a/apps/web/src/pages/api/draft-mode/enable.ts b/apps/web/src/pages/api/draft-mode/enable.ts
@@ -0,0 +1,44 @@
+/**
+ * Enable draft mode for Sanity Visual Editing.
+ *
+ * Called by the Studio's Presentation Tool when loading the preview iframe.
+ * Validates SANITY_PREVIEW_SECRET, sets a __sanity_preview cookie, and
+ * redirects to the requested page.
+ *
+ * Usage: /api/draft-mode/enable?secret=<value>&slug=/post/my-post
+ */
+import type { APIRoute } from "astro";
+import { env } from "cloudflare:workers";
+
+export const prerender = false;
+
+export const GET: APIRoute = async ({ url, cookies, redirect }) => {
+  const secret = url.searchParams.get("secret");
+  const slug = url.searchParams.get("slug") || "/";
+
+  // Fail-closed: require SANITY_PREVIEW_SECRET to be configured
+  const expectedSecret = (env as Record<string, string>).SANITY_PREVIEW_SECRET;
+  if (!expectedSecret) {
+    return new Response("Draft mode not configured — SANITY_PREVIEW_SECRET is missing", {
+      status: 503,
+    });
+  }
+
+  // Validate the secret
+  if (!secret || secret !== expectedSecret) {
+    return new Response("Invalid preview secret", { status: 401 });
+  }
+
+  // Set the preview cookie — httpOnly so client JS can't tamper with it
+  cookies.set("__sanity_preview", "1", {
+    path: "/",
+    httpOnly: true,
+    sameSite: "none",
+    secure: true,
+    // 1 hour — long enough for an editing session
+    maxAge: 60 * 60,
+  });
+
+  // Redirect to the requested page
+  return redirect(slug, 307);
+};
diff --git a/apps/web/src/pages/author/[slug].astro b/apps/web/src/pages/author/[slug].astro
@@ -7,7 +7,8 @@ import { authorQuery } from "@/lib/queries";
 export const prerender = false;
 
 const { slug } = Astro.params;
-const { data: author } = await loadQuery<any>({ query: authorQuery, params: { slug } });
+const draftMode = Astro.cookies.has("__sanity_preview");
+const { data: author } = await loadQuery<any>({ query: authorQuery, params: { slug }, draftMode });
 
 if (!author) {
   return Astro.redirect("/404");
diff --git a/apps/web/src/pages/authors.astro b/apps/web/src/pages/authors.astro
@@ -12,8 +12,9 @@ const page = Number.isNaN(rawPage) || rawPage < 1 ? 1 : Math.floor(rawPage);
 const perPage = 12;
 const offset = (page - 1) * perPage;
 
+const draftMode = Astro.cookies.has("__sanity_preview");
 const [itemsResult, totalCount] = await Promise.all([
-  loadQuery<any[]>({ query: authorListQuery, params: { offset, end: offset + perPage } }),
+  loadQuery<any[]>({ query: authorListQuery, params: { offset, end: offset + perPage }, draftMode }),
   sanityFetch<number>(authorCountQuery),
 ]);
 const items = itemsResult.data;
diff --git a/apps/web/src/pages/blog.astro b/apps/web/src/pages/blog.astro
@@ -13,8 +13,9 @@ const page = Number.isNaN(rawPage) || rawPage < 1 ? 1 : Math.floor(rawPage);
 const perPage = 12;
 const offset = (page - 1) * perPage;
 
+const draftMode = Astro.cookies.has("__sanity_preview");
 const [postsResult, totalCount] = await Promise.all([
-  loadQuery<any[]>({ query: postListQuery, params: { offset, end: offset + perPage } }),
+  loadQuery<any[]>({ query: postListQuery, params: { offset, end: offset + perPage }, draftMode }),
   sanityFetch<number>(postCountQuery),
 ]);
 const posts = postsResult.data;
diff --git a/apps/web/src/pages/guest/[slug].astro b/apps/web/src/pages/guest/[slug].astro
@@ -7,7 +7,8 @@ import { guestQuery } from "@/lib/queries";
 export const prerender = false;
 
 const { slug } = Astro.params;
-const { data: guest } = await loadQuery<any>({ query: guestQuery, params: { slug } });
+const draftMode = Astro.cookies.has("__sanity_preview");
+const { data: guest } = await loadQuery<any>({ query: guestQuery, params: { slug }, draftMode });
 
 if (!guest) {
   return Astro.redirect("/404");
diff --git a/apps/web/src/pages/guests.astro b/apps/web/src/pages/guests.astro
@@ -12,8 +12,9 @@ const page = Number.isNaN(rawPage) || rawPage < 1 ? 1 : Math.floor(rawPage);
 const perPage = 12;
 const offset = (page - 1) * perPage;
 
+const draftMode = Astro.cookies.has("__sanity_preview");
 const [itemsResult, totalCount] = await Promise.all([
-  loadQuery<any[]>({ query: guestListQuery, params: { offset, end: offset + perPage } }),
+  loadQuery<any[]>({ query: guestListQuery, params: { offset, end: offset + perPage }, draftMode }),
   sanityFetch<number>(guestCountQuery),
 ]);
 const items = itemsResult.data;
diff --git a/apps/web/src/pages/index.astro b/apps/web/src/pages/index.astro
@@ -6,7 +6,8 @@ import { homePageQuery } from "@/lib/queries";
 
 export const prerender = false;
 
-const { data: homePage } = await loadQuery<any>({ query: homePageQuery });
+const draftMode = Astro.cookies.has("__sanity_preview");
+const { data: homePage } = await loadQuery<any>({ query: homePageQuery, draftMode });
 ---
 
 <BaseLayout title="CodingCat.dev — Purrfect Web Tutorials">
diff --git a/apps/web/src/pages/podcast/[slug].astro b/apps/web/src/pages/podcast/[slug].astro
@@ -7,7 +7,8 @@ import { podcastQuery } from "@/lib/queries";
 export const prerender = false;
 
 const { slug } = Astro.params;
-const { data: podcast } = await loadQuery<any>({ query: podcastQuery, params: { slug } });
+const draftMode = Astro.cookies.has("__sanity_preview");
+const { data: podcast } = await loadQuery<any>({ query: podcastQuery, params: { slug }, draftMode });
 
 if (!podcast) {
   return Astro.redirect("/404");
diff --git a/apps/web/src/pages/podcast/rss.xml.ts b/apps/web/src/pages/podcast/rss.xml.ts
@@ -1,18 +1,10 @@
 import type { APIRoute } from "astro";
 import { sanityFetch } from "@/utils/sanity";
 import { rssPodcastsQuery } from "@/lib/queries";
+import { escapeXml } from "@/utils/xml";
 
 export const prerender = false;
 
-function escapeXml(str: string): string {
-  return str
-    .replace(/&/g, "&amp;")
-    .replace(/</g, "&lt;")
-    .replace(/>/g, "&gt;")
-    .replace(/"/g, "&quot;")
-    .replace(/'/g, "&apos;");
-}
-
 export const GET: APIRoute = async () => {
   const site = "https://codingcat.dev";
   const podcasts = await sanityFetch<any[]>(rssPodcastsQuery);
diff --git a/apps/web/src/pages/podcasts.astro b/apps/web/src/pages/podcasts.astro
@@ -13,8 +13,9 @@ const page = Number.isNaN(rawPage) || rawPage < 1 ? 1 : Math.floor(rawPage);
 const perPage = 12;
 const offset = (page - 1) * perPage;
 
+const draftMode = Astro.cookies.has("__sanity_preview");
 const [podcastsResult, totalCount] = await Promise.all([
-  loadQuery<any[]>({ query: podcastListQuery, params: { offset, end: offset + perPage } }),
+  loadQuery<any[]>({ query: podcastListQuery, params: { offset, end: offset + perPage }, draftMode }),
   sanityFetch<number>(podcastCountQuery),
 ]);
 const podcasts = podcastsResult.data;
diff --git a/apps/web/src/pages/post/[slug].astro b/apps/web/src/pages/post/[slug].astro
@@ -7,7 +7,8 @@ import { postQuery } from "@/lib/queries";
 export const prerender = false;
 
 const { slug } = Astro.params;
-const { data: post } = await loadQuery<any>({ query: postQuery, params: { slug } });
+const draftMode = Astro.cookies.has("__sanity_preview");
+const { data: post } = await loadQuery<any>({ query: postQuery, params: { slug }, draftMode });
 
 if (!post) {
   return Astro.redirect("/404");
diff --git a/apps/web/src/pages/rss.xml.ts b/apps/web/src/pages/rss.xml.ts
@@ -1,18 +1,10 @@
 import type { APIRoute } from "astro";
 import { sanityFetch } from "@/utils/sanity";
 import { rssPostsQuery } from "@/lib/queries";
+import { escapeXml } from "@/utils/xml";
 
 export const prerender = false;
 
-function escapeXml(str: string): string {
-  return str
-    .replace(/&/g, "&amp;")
-    .replace(/</g, "&lt;")
-    .replace(/>/g, "&gt;")
-    .replace(/"/g, "&quot;")
-    .replace(/'/g, "&apos;");
-}
-
 export const GET: APIRoute = async () => {
   const site = "https://codingcat.dev";
   const posts = await sanityFetch<any[]>(rssPostsQuery);
diff --git a/apps/web/src/pages/sitemap.xml.ts b/apps/web/src/pages/sitemap.xml.ts
@@ -19,13 +19,21 @@ export const GET: APIRoute = async () => {
   const site = "https://codingcat.dev";
   const items = await sanityFetch<SitemapItem[]>(sitemapQuery);
 
+  // Use the most recent content update for static page lastmod
+  // (instead of current time which changes on every request)
+  const latestUpdate = items.length > 0
+    ? items.reduce((latest, item) =>
+        item._updatedAt > latest ? item._updatedAt : latest,
+      items[0]._updatedAt)
+    : new Date().toISOString();
+
   const staticPages = [
-    { url: site, lastmod: new Date().toISOString(), priority: "1.0" },
-    { url: `${site}/blog`, lastmod: new Date().toISOString(), priority: "0.8" },
-    { url: `${site}/podcasts`, lastmod: new Date().toISOString(), priority: "0.8" },
-    { url: `${site}/authors`, lastmod: new Date().toISOString(), priority: "0.5" },
-    { url: `${site}/guests`, lastmod: new Date().toISOString(), priority: "0.5" },
-    { url: `${site}/sponsors`, lastmod: new Date().toISOString(), priority: "0.5" },
+    { url: site, lastmod: latestUpdate, priority: "1.0" },
+    { url: `${site}/blog`, lastmod: latestUpdate, priority: "0.8" },
+    { url: `${site}/podcasts`, lastmod: latestUpdate, priority: "0.8" },
+    { url: `${site}/authors`, lastmod: latestUpdate, priority: "0.5" },
+    { url: `${site}/guests`, lastmod: latestUpdate, priority: "0.5" },
+    { url: `${site}/sponsors`, lastmod: latestUpdate, priority: "0.5" },
   ];
 
   const dynamicPages = items.map((item) => ({
diff --git a/apps/web/src/pages/sponsor/[slug].astro b/apps/web/src/pages/sponsor/[slug].astro
@@ -7,7 +7,8 @@ import { sponsorQuery } from "@/lib/queries";
 export const prerender = false;
 
 const { slug } = Astro.params;
-const { data: sponsor } = await loadQuery<any>({ query: sponsorQuery, params: { slug } });
+const draftMode = Astro.cookies.has("__sanity_preview");
+const { data: sponsor } = await loadQuery<any>({ query: sponsorQuery, params: { slug }, draftMode });
 
 if (!sponsor) {
   return Astro.redirect("/404");
diff --git a/apps/web/src/pages/sponsors.astro b/apps/web/src/pages/sponsors.astro
@@ -12,8 +12,9 @@ const page = Number.isNaN(rawPage) || rawPage < 1 ? 1 : Math.floor(rawPage);
 const perPage = 12;
 const offset = (page - 1) * perPage;
 
+const draftMode = Astro.cookies.has("__sanity_preview");
 const [itemsResult, totalCount] = await Promise.all([
-  loadQuery<any[]>({ query: sponsorListQuery, params: { offset, end: offset + perPage } }),
+  loadQuery<any[]>({ query: sponsorListQuery, params: { offset, end: offset + perPage }, draftMode }),
   sanityFetch<number>(sponsorCountQuery),
 ]);
 const items = itemsResult.data;
diff --git a/apps/web/src/utils/sanity.ts b/apps/web/src/utils/sanity.ts
@@ -1,7 +1,11 @@
 /**
  * Draft-aware Sanity query helper with Visual Editing support.
  *
- * When Visual Editing is enabled (PUBLIC_SANITY_VISUAL_EDITING_ENABLED=true):
+ * Draft mode is enabled when EITHER:
+ * 1. PUBLIC_SANITY_VISUAL_EDITING_ENABLED=true (site-wide, for dev environments)
+ * 2. The __sanity_preview cookie is set (per-session, via /api/draft-mode/enable)
+ *
+ * When draft mode is active:
  * - Fetches with perspective: "drafts" (shows unpublished content)
  * - Enables stega encoding (invisible edit markers for click-to-edit overlays)
  * - Uses SANITY_API_READ_TOKEN for authenticated requests
@@ -23,39 +27,57 @@ export function urlForImage(source: SanityImageSource) {
   return builder.image(source);
 }
 
-const visualEditingEnabled =
+/** Site-wide Visual Editing toggle (for dev/preview environments) */
+const siteWideVisualEditing =
   import.meta.env.PUBLIC_SANITY_VISUAL_EDITING_ENABLED === "true";
 const token = import.meta.env.SANITY_API_READ_TOKEN;
 
+interface LoadQueryOptions {
+  query: string;
+  params?: QueryParams;
+  /** Per-request draft mode — set from Astro.cookies in page frontmatter */
+  draftMode?: boolean;
+}
+
+/**
+ * Check if Visual Editing / draft mode is active.
+ * True when site-wide toggle is on OR per-request draft cookie is set.
+ */
+function isDraftMode(draftMode?: boolean): boolean {
+  return siteWideVisualEditing || draftMode === true;
+}
+
 /**
  * Fetch from Sanity with Visual Editing support.
- * Use this instead of sanityClient.fetch() directly.
+ *
+ * For pages: pass `draftMode: Astro.cookies.has('__sanity_preview')`
+ * to enable per-request draft mode from the preview cookie.
  */
 export async function loadQuery<T>({
   query,
   params,
-}: {
-  query: string;
-  params?: QueryParams;
-}): Promise<{ data: T }> {
-  if (visualEditingEnabled && !token) {
+  draftMode,
+}: LoadQueryOptions): Promise<{ data: T }> {
+  const drafts = isDraftMode(draftMode);
+
+  if (drafts && !token) {
     throw new Error(
       "The `SANITY_API_READ_TOKEN` environment variable is required during Visual Editing.",
     );
   }
 
-  const perspective = visualEditingEnabled ? "drafts" : "published";
+  const perspective = drafts ? "drafts" : "published";
 
   const { result, resultSourceMap } = await sanityClient.fetch<T>(
     query,
     params ?? {},
     {
       filterResponse: false,
       perspective,
-      resultSourceMap: visualEditingEnabled ? "withKeyArraySelector" : false,
-      stega: visualEditingEnabled,
-      ...(visualEditingEnabled ? { token } : {}),
-      useCdn: !visualEditingEnabled,
+      resultSourceMap: drafts ? "withKeyArraySelector" : false,
+      stega: drafts,
+      ...(drafts ? { token } : {}),
+      useCdn: !drafts,
     },
   );
 
diff --git a/apps/web/src/utils/xml.ts b/apps/web/src/utils/xml.ts
@@ -0,0 +1,16 @@
+/**
+ * XML utility functions for RSS feeds and sitemaps.
+ */
+
+/**
+ * Escape special XML characters in a string.
+ * Use for any user-generated content in XML output.
+ */
+export function escapeXml(str: string): string {
+  return str
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;")
+    .replace(/'/g, "&apos;");
+}

Original file line number	Diff line number	Diff line change
`@@ -14,7 +14,8 @@ if (reservedSlugs.includes(slug!)) {`
`14`	`14`	return Astro.redirect(`/${slug}`);
`15`	`15`	`}`
`16`	`16`
`17`		`-const { data: page } = await loadQuery<any>({ query: pageQuery, params: { slug } });`
	`17`	`+const draftMode = Astro.cookies.has("__sanity_preview");`
	`18`	`+const { data: page } = await loadQuery<any>({ query: pageQuery, params: { slug }, draftMode });`
`18`	`19`
`19`	`20`	`if (!page) {`
`20`	`21`	`return new Response(null, { status: 404 });`