@karibsen/eponyme 0.4.0 → 0.6.0

package/README.md

@@ -587,15 +587,44 @@ shorten. A visitor holding a copy keeps it until it expires, publication or not,
 why the default is deliberately small. Set it to `0` if a publication must be visible
 immediately to everyone; navigation then costs a round trip again.
 
-The CDN window can be long because it can be purged, and `eponyme:entry:published` is the
-place to do it:
+### Purging the CDN
+
+The CDN window can be long because it can be purged. CDNs purge by **tag** rather than by
+URL — one entry appears in several cached responses, its own and its collection's listing —
+so every cacheable response carries `Vercel-Cache-Tag` and `Cache-Tag`:
+
+| Response | Tags |
+|---|---|
+| `pages/homepage` | `eponyme`, `eponyme:pages/homepage` |
+| `articles/my-article` | `eponyme`, `eponyme:articles/my-article`, `eponyme:articles` |
+| The `articles` listing | `eponyme`, `eponyme:articles` |
+
+`getEponymeCacheTags()` returns exactly those tags and is auto-imported into server code,
+so a listener purges precisely what the responses were tagged with. On Vercel:
 
 ```ts
-nitroApp.hooks.hook('eponyme:entry:published', async ({ name, collection }) => {
-  await purgeCdnCache(collection ? `/${collection.name}/${collection.slug}` : `/${name}`)
+// server/plugins/purge.ts
+import { invalidateByTag } from '@vercel/functions'
+
+export default defineNitroPlugin((nitroApp) => {
+  const purge = async ({ name, collection }: { name: string, collection?: { name: string } }) => {
+    if (!import.meta.env.VERCEL) return
+    await invalidateByTag(getEponymeCacheTags(name, collection)).catch(() => {})
+  }
+
+  nitroApp.hooks.hook('eponyme:entry:published', purge)
+  nitroApp.hooks.hook('eponyme:entry:restored', purge)
+  nitroApp.hooks.hook('eponyme:entry:trashed', purge)
+  nitroApp.hooks.hook('eponyme:entry:untrashed', purge)
+  nitroApp.hooks.hook('eponyme:entry:purged', purge)
 })
 ```
 
+Invalidating marks the entry stale and revalidates in the background, so no visitor waits
+for it. A failed purge is swallowed: a CDN that cannot be reached must not turn a
+successful publication into an error the editor cannot act on. The worst case is the
+content appearing when `cdnCacheSeconds` expires on its own.
+
 **Only published content is ever cached.** Drafts, historical versions, `raw=1` reads,
 submissions, the trash, the user list and the session route all answer `no-store`. That is
 enforced by a server middleware that marks every Eponyme route uncacheable, which the few
@@ -806,7 +835,7 @@ a trash move leaves the entry itself untouched.
 
 ## Current status
 
-Eponyme is at version `0.4.0`. It is ready for controlled projects and production pilots. A few workflows still need hardening before a broad public release:
+Eponyme is at version `0.5.0`. It is ready for controlled projects and production pilots. A few workflows still need hardening before a broad public release:
 
 - Client revision tokens for long-running concurrent edits: the current `updatedAt` check protects overlapping writes within one request, not two editors who loaded the same older revision. A deletion is not guarded by a revision either
 - Retention controls for the trash: entries stay there until someone empties it

package/dist/module.json

@@ -1,7 +1,7 @@
 {
   "name": "@karibsen/eponyme",
   "configKey": "eponyme",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "builder": {
     "@nuxt/module-builder": "1.0.2",
     "unbuild": "3.6.1"

package/dist/module.mjs

@@ -2,6 +2,7 @@ import { defineNuxtModule, useLogger, createResolver, findPath, addImports, addI
 import pc from 'picocolors';
 import tailwindcss from '@tailwindcss/vite';
 import { resolve } from 'node:path';
+import { tagPreviewPathRoutes } from '../dist/runtime/utils/cache-tags.js';
 
 const module$1 = defineNuxtModule({
   meta: {
@@ -78,6 +79,14 @@ const module$1 = defineNuxtModule({
       browserCacheSeconds: options.browserCacheSeconds ?? 30,
       cdnCacheSeconds: options.cdnCacheSeconds ?? 300
     };
+    const tagged = tagPreviewPathRoutes(options.previewPaths ?? {}, nuxt.options.routeRules ??= {});
+    if (tagged.length) {
+      const width = Math.max(...tagged.map(({ route }) => route.length));
+      logger.info(
+        `Cache tags added to ${tagged.length} public route${tagged.length > 1 ? "s" : ""}, so publishing can purge them:
+` + tagged.map(({ route, tag }) => `  ${route.padEnd(width)}  ${tag}`).join("\n")
+      );
+    }
     const preparing = Boolean(nuxt.options._prepare);
     if (!options.prismaClient) {
       if (!preparing) throw new Error(`${pc.red("[Eponyme]")} eponyme.prismaClient is required.`);
@@ -106,7 +115,10 @@ Note that '~/' points at ${nuxt.options.srcDir}, so a server module needs '~~/'.
       { name: "getEponymeSitemapEntries", from: resolver.resolve("./runtime/server/utils/eponyme-sitemap") },
       // A `custom` form posts to the host application's own route, so this is what
       // keeps server-side validation as the security boundary.
-      { name: "validateEponymeForm", from: resolver.resolve("./runtime/server/utils/eponyme-form") }
+      { name: "validateEponymeForm", from: resolver.resolve("./runtime/server/utils/eponyme-form") },
+      // The tags a CDN purge has to invalidate when an entry changes, matching exactly what
+      // the cached responses were tagged with.
+      { name: "getEponymeCacheTags", from: resolver.resolve("./runtime/server/utils/eponyme-cache") }
     ]);
     addRouteMiddleware({
       name: "eponyme-auth",

package/dist/runtime/assets.d.ts

@@ -0,0 +1,9 @@
+declare module '*.ico?url' {
+  const url: string
+  export default url
+}
+
+declare module '*.png?url' {
+  const url: string
+  export default url
+}

package/dist/runtime/components/editor/EponymePreviewPanel.vue

@@ -3,6 +3,7 @@ import { computed, ref, watch } from "vue";
 import EPButton from "../ui/EPButton.vue";
 import EPSelect from "../ui/EPSelect.vue";
 import { formatVersionDate, useEponymeHistory } from "../../composables/useEponymeHistory";
+import { EPONYME_PREVIEW_QUERY, EPONYME_PREVIEW_TOKEN_QUERY, EPONYME_PREVIEW_VERSION_QUERY } from "../../utils/preview";
 const props = defineProps({
   name: { type: String, required: true },
   path: { type: String, required: true },
@@ -25,9 +26,9 @@ const options = computed(() => [
 ]);
 const previewUrl = computed(() => {
   const url = new URL(props.path, "http://placeholder");
-  url.searchParams.set("__eponyme_preview", props.name);
-  url.searchParams.set("__eponyme_preview_version", selected.value);
-  url.searchParams.set("__eponyme_preview_token", previewToken.value);
+  url.searchParams.set(EPONYME_PREVIEW_QUERY, props.name);
+  url.searchParams.set(EPONYME_PREVIEW_VERSION_QUERY, selected.value);
+  url.searchParams.set(EPONYME_PREVIEW_TOKEN_QUERY, previewToken.value);
   return `${url.pathname}${url.search}`;
 });
 async function reload() {

package/dist/runtime/composables/useEponyme.d.ts

@@ -1,4 +1,4 @@
-import type { Ref } from 'vue';
+import type { ComputedRef, Ref } from 'vue';
 import type eponymeConfig from '#eponyme/config';
 import type { EponymeDataByName, EponymeName } from '../types/index.js';
 import type { EponymeAction, EponymeStatus, EponymeVersionSelector } from '../server/services/eponyme-store.js';
@@ -9,18 +9,26 @@ export interface UseEponymeOptions {
     /** Keep `{{ variables }}` unresolved. The dashboard editor needs the source text. */
     raw?: boolean;
 }
-/** Read and save a configured eponyme through the public or draft API. */
-export declare function useEponyme<const Name extends ConfigEponymeName>(name: Name, options?: UseEponymeOptions): {
-    data: Ref<EponymeDataByName<any, Name> | undefined>;
-    status: import("vue").ComputedRef<EponymeStatus>;
-    publishedAt: import("vue").ComputedRef<string | null>;
-    pending: import("vue").ComputedRef<boolean>;
-    error: Ref<import("nuxt/app").NuxtError<unknown> | undefined, import("nuxt/app").NuxtError<unknown> | undefined>;
-    errors: Ref<ValidationErrors, ValidationErrors>;
+/**
+ * Named, and annotated on the function below, rather than left to inference.
+ *
+ * An inferred return type has to be expanded when the declaration files are generated, and
+ * the expansion loses `typeof eponymeConfig`: it came out as `EponymeDataByName<any, Name>`,
+ * which collapses every field to the union of all possible field values. Source and
+ * playground were unaffected — they read `src` — so only installed versions of the package
+ * lost their types, on the one composable everything else goes through.
+ */
+export interface UseEponymeResult<Data extends Record<string, unknown>> {
+    data: Ref<Data | undefined>;
+    status: ComputedRef<EponymeStatus>;
+    publishedAt: ComputedRef<string | null>;
+    pending: ComputedRef<boolean>;
+    error: Ref<Error | null | undefined>;
+    errors: Ref<ValidationErrors>;
     refresh: () => Promise<void>;
-    save: {
-        (): Promise<EponymeDataByName<any, Name> | undefined>;
-        (patch: Partial<EponymeDataByName<any, Name>>, action?: EponymeAction): Promise<EponymeDataByName<any, Name> | undefined>;
-    };
-};
+    /** Without a patch, saves the data currently held. Publishes unless told otherwise. */
+    save: (patch?: Partial<Data>, action?: EponymeAction) => Promise<Data | undefined>;
+}
+/** Read and save a configured eponyme through the public or draft API. */
+export declare function useEponyme<const Name extends ConfigEponymeName>(name: Name, options?: UseEponymeOptions): UseEponymeResult<EponymeDataByName<typeof eponymeConfig, Name>>;
 export {};

package/dist/runtime/composables/useEponyme.js

@@ -1,7 +1,7 @@
 import { clearNuxtData, useAsyncData, useRequestFetch, useRoute } from "#app";
 import { computed, ref } from "vue";
 import { readPreviewQuery, readPreviewVersion } from "../utils/preview.js";
-import { cacheDuringHydrationOnly } from "../utils/hydration-cache.js";
+import { cacheForPublicRead } from "../utils/hydration-cache.js";
 export function useEponyme(name, options = {}) {
   const route = useRoute();
   const preview = readPreviewQuery(route.query);
@@ -10,11 +10,13 @@ export function useEponyme(name, options = {}) {
   const saving = ref(false);
   const requestFetch = useRequestFetch();
   const cacheKey = `eponyme:${name}:${version}${options.raw ? ":raw" : ""}`;
-  const fetchCache = version === "published" && !options.raw ? void 0 : "no-store";
+  const isPublicContent = version === "published" && !options.raw;
+  const fetchCache = isPublicContent ? void 0 : "no-store";
+  const isPreviewRead = options.version === void 0 && !isPublicContent;
   const { data: response, pending: loading, error, refresh: load } = useAsyncData(
     cacheKey,
     () => requestFetch(`/api/eponyme/${name}`, { query: { version, raw: options.raw ? 1 : void 0 }, cache: fetchCache }),
-    { getCachedData: cacheDuringHydrationOnly }
+    { server: !isPreviewRead, getCachedData: cacheForPublicRead(isPublicContent) }
   );
   const data = computed(() => response.value?.data);
   const status = computed(() => response.value?.status ?? "published");

package/dist/runtime/composables/useEponymeCollection.js

@@ -2,7 +2,7 @@ import { useAsyncData, useRequestFetch, useRoute } from "#app";
 import { useEventListener } from "@vueuse/core";
 import { computed } from "vue";
 import { readPreviewQuery, readPreviewVersion } from "../utils/preview.js";
-import { cacheDuringHydrationOnly } from "../utils/hydration-cache.js";
+import { cacheForPublicRead } from "../utils/hydration-cache.js";
 export function useEponymeCollection(name, options = {}) {
   const requestFetch = useRequestFetch();
   const query = {
@@ -17,7 +17,7 @@ export function useEponymeCollection(name, options = {}) {
     `eponyme:collection:public:${name}:${options.take ?? ""}:${options.skip ?? ""}:${options.orderBy ?? ""}:${options.order ?? ""}`,
     // Always the published listing, which is publicly cacheable: the browser cache may answer it.
     () => requestFetch(`/api/eponyme-collections/${name}`, { query }),
-    { getCachedData: cacheDuringHydrationOnly }
+    { getCachedData: cacheForPublicRead(true) }
   );
   const entries = computed(() => result.data.value?.entries ?? []);
   if (import.meta.client) useEventListener(window, "focus", () => void result.refresh());
@@ -36,14 +36,16 @@ export function useEponymeCollectionEntry(name, slug, options = {}) {
   const preview = readPreviewQuery(route.query);
   const version = options.version ?? (preview.entry === `${name}/${slug}` ? readPreviewVersion(preview.version) : "published");
   const requestFetch = useRequestFetch();
+  const isPublicContent = version === "published";
+  const isPreviewRead = options.version === void 0 && !isPublicContent;
   const result = useAsyncData(
     `eponyme:collection-entry:${name}:${slug}:${version}`,
     () => requestFetch(`/api/eponyme/${name}/${encodeURIComponent(slug)}`, {
       query: { version },
       // A draft or a historical version must never be stored, whatever the server says.
-      cache: version === "published" ? void 0 : "no-store"
+      cache: isPublicContent ? void 0 : "no-store"
     }),
-    { getCachedData: cacheDuringHydrationOnly }
+    { server: !isPreviewRead, getCachedData: cacheForPublicRead(isPublicContent) }
   );
   if (import.meta.client) useEventListener(window, "focus", () => void result.refresh());
   return {

package/dist/runtime/composables/useEponymeFavicon.d.ts

@@ -0,0 +1 @@
+export declare function useEponymeFavicon(): void;

package/dist/runtime/composables/useEponymeFavicon.js

@@ -0,0 +1,14 @@
+import { useHead } from "#app";
+import iconUrl from "../assets/icon.ico?url";
+export function useEponymeFavicon() {
+  useHead({
+    link: [
+      {
+        key: "eponyme-favicon",
+        rel: "icon",
+        type: "image/x-icon",
+        href: iconUrl
+      }
+    ]
+  });
+}

package/dist/runtime/pages/EponymeChangePasswordPage.vue

@@ -2,9 +2,11 @@
 import { navigateTo, useRuntimeConfig, useSeoMeta } from "#app";
 import { computed, ref } from "vue";
 import { useEponymeAuth } from "../composables/useEponymeAuth";
+import { useEponymeFavicon } from "../composables/useEponymeFavicon";
 import EPButton from "../components/ui/EPButton.vue";
 import EPFormField from "../components/ui/EPFormField.vue";
 import EPInputText from "../components/ui/EPInputText.vue";
+useEponymeFavicon();
 useSeoMeta({ title: "Change password \xB7 Eponyme" });
 const auth = useEponymeAuth();
 const currentPassword = ref("");

package/dist/runtime/pages/EponymeDetailPage.vue

@@ -9,6 +9,7 @@ import EponymeFolderPage from "../components/editor/EponymeFolderPage.vue";
 import EponymePageNavigation from "../components/editor/EponymePageNavigation.vue";
 import EponymeSidebar from "../components/editor/EponymeSidebar.vue";
 import { useEponymeConfig } from "../composables/useEponymeConfig";
+import { useEponymeFavicon } from "../composables/useEponymeFavicon";
 import { getEponymeCollections, getEponymeForms, getEponymeSchemas } from "../utils/get-eponyme-schemas";
 const route = useRoute();
 const config = useEponymeConfig();
@@ -29,6 +30,7 @@ const isFolder = computed(() => !schemas[eponymeName.value] && !collection.value
 function label(name) {
   return name.replace(/[-_]/g, " ").replace(/\b\w/g, (char) => char.toUpperCase());
 }
+useEponymeFavicon();
 useSeoMeta({
   title: () => `${label(eponymeName.value.split("/").at(-1) ?? eponymeName.value)} \xB7 Eponyme`
 });

package/dist/runtime/pages/EponymeIndexPage.vue

@@ -8,6 +8,7 @@ import EPDialog from "../components/ui/EPDialog.vue";
 import EPToast from "../components/ui/EPToast.vue";
 import { useEponymeAuth } from "../composables/useEponymeAuth";
 import { useEponymeConfig } from "../composables/useEponymeConfig";
+import { useEponymeFavicon } from "../composables/useEponymeFavicon";
 import { getEponymeCollections, getEponymeForms, getEponymeSchemas } from "../utils/get-eponyme-schemas";
 const config = useEponymeConfig();
 const route = useRoute();
@@ -17,6 +18,7 @@ const eponymes = getEponymeSchemas(config);
 const collections = getEponymeCollections(config);
 const forms = getEponymeForms(config);
 const entries = { ...eponymes, ...collections, ...forms };
+useEponymeFavicon();
 useSeoMeta({ title: "Eponyme" });
 const fileInput = ref();
 const exporting = ref(false);

package/dist/runtime/pages/EponymeLoginPage.vue

@@ -2,15 +2,18 @@
 import { navigateTo, useRoute, useRuntimeConfig, useSeoMeta } from "#app";
 import { computed, ref } from "vue";
 import { useEponymeAuth } from "../composables/useEponymeAuth";
+import { useEponymeFavicon } from "../composables/useEponymeFavicon";
 import EPButton from "../components/ui/EPButton.vue";
 import EPFormField from "../components/ui/EPFormField.vue";
 import EPInputText from "../components/ui/EPInputText.vue";
+import logoUrl from "../assets/logo.png?url";
 const route = useRoute();
 const auth = useEponymeAuth();
 const username = ref("");
 const password = ref("");
 const error = ref("");
 const dashboardPath = computed(() => useRuntimeConfig().public.eponyme?.dashboardPath ?? "/__eponyme");
+useEponymeFavicon();
 useSeoMeta({ title: "Sign in \xB7 Eponyme" });
 const existingUser = await auth.refresh();
 if (existingUser)
@@ -37,10 +40,12 @@ async function navigateAfterLogin(mustChangePassword) {
 <template>
   <main class="eponyme-root ep:flex ep:min-h-screen ep:items-center ep:justify-center ep:bg-theme-ep ep:px-6 ep:py-12 ep:font-sans ep:text-text-ep">
     <section class="ep:w-full ep:max-w-sm">
-      <p class="ep:m-0 ep:text-[11px] ep:font-semibold ep:tracking-widest ep:text-muted-ep ep:uppercase">
-        Eponyme
-      </p>
-      <h1 class="ep:mt-2 ep:mb-2 ep:text-3xl ep:font-semibold ep:tracking-tight ep:text-white">
+      <img
+        :src="logoUrl"
+        alt="Eponyme"
+        class="ep:block ep:size-14"
+      >
+      <h1 class="ep:mt-4 ep:mb-2 ep:text-3xl ep:font-semibold ep:tracking-tight ep:text-white">
         Sign in
       </h1>
       <p class="ep:mt-0 ep:mb-8 ep:text-sm ep:leading-relaxed ep:text-muted-ep">

package/dist/runtime/pages/EponymeUsersPage.vue

@@ -3,6 +3,7 @@ import { useRequestFetch, useRoute, useSeoMeta } from "#app";
 import { computed, ref } from "vue";
 import EponymeCopy from "../components/editor/EponymeCopy.vue";
 import EponymeSidebar from "../components/editor/EponymeSidebar.vue";
+import { useEponymeFavicon } from "../composables/useEponymeFavicon";
 import EPButton from "../components/ui/EPButton.vue";
 import EPDialog from "../components/ui/EPDialog.vue";
 import EPFormField from "../components/ui/EPFormField.vue";
@@ -11,6 +12,7 @@ import EPSelect from "../components/ui/EPSelect.vue";
 import EPSwitch from "../components/ui/EPSwitch.vue";
 import EPTooltip from "../components/ui/EPTooltip.vue";
 import EPAvatar from "../components/ui/EPAvatar.vue";
+useEponymeFavicon();
 useSeoMeta({ title: "Users \xB7 Eponyme" });
 const route = useRoute();
 const requestFetch = useRequestFetch();

package/dist/runtime/server/api/eponyme/[name].get.js

@@ -1,7 +1,8 @@
 import { createError, defineEventHandler, getQuery, getRequestURL } from "h3";
 import { useEponymeService } from "../../services/eponyme-service.js";
 import { requireEponymeUser } from "../../utils/auth.js";
-import { setEponymePublicCache } from "../../utils/eponyme-cache.js";
+import { getEponymeCacheTags, setEponymePublicCache } from "../../utils/eponyme-cache.js";
+import { splitEponymeCollectionEntry } from "../../utils/eponyme-entry.js";
 import { interpolateEponymeContent } from "../../utils/eponyme-variables.js";
 function readVersion(raw) {
   if (raw === "draft") return "draft";
@@ -14,7 +15,7 @@ export default defineEventHandler(async (event) => {
   const version = readVersion(requestedVersion);
   const raw = Boolean(getQuery(event).raw);
   if (version !== "published") await requireEponymeUser(event);
-  else if (!raw) setEponymePublicCache(event);
+  else if (!raw) setEponymePublicCache(event, getEponymeCacheTags(name, splitEponymeCollectionEntry(useEponymeService(), name)?.name));
   const result = name ? await useEponymeService().getResult(name, version) : void 0;
   if (!result) throw createError({ statusCode: 404, statusMessage: "Eponyme entry not found." });
   const data = raw ? result.data : interpolateEponymeContent(result.data);

package/dist/runtime/server/api/eponyme-collections/[path].get.js

@@ -1,7 +1,7 @@
 import { createError, defineEventHandler, getQuery, getRequestURL } from "h3";
 import { useEponymeService } from "../../services/eponyme-service.js";
 import { requireEponymeUser } from "../../utils/auth.js";
-import { setEponymePublicCache } from "../../utils/eponyme-cache.js";
+import { getEponymeCacheTags, setEponymePublicCache } from "../../utils/eponyme-cache.js";
 import { interpolateEponymeContent } from "../../utils/eponyme-variables.js";
 const MAX_TAKE = 200;
 function readCount(raw, min, max) {
@@ -15,7 +15,7 @@ export default defineEventHandler(async (event) => {
   const query = getQuery(event);
   const version = query.version === "draft" ? "draft" : "published";
   if (version === "draft") await requireEponymeUser(event);
-  else if (!query.raw) setEponymePublicCache(event);
+  else if (!query.raw) setEponymePublicCache(event, getEponymeCacheTags(name));
   if (!name) throw createError({ statusCode: 404, statusMessage: "Eponyme collection not found." });
   const service = useEponymeService();
   const orderBy = query.orderBy === void 0 || query.orderBy === "" ? void 0 : String(query.orderBy);

package/dist/runtime/server/api/eponyme-sitemap.get.js

@@ -1,7 +1,7 @@
 import { defineEventHandler } from "h3";
-import { setEponymePublicCache } from "../utils/eponyme-cache.js";
+import { getEponymeCacheTags, setEponymePublicCache } from "../utils/eponyme-cache.js";
 import { getEponymeSitemapEntries } from "../utils/eponyme-sitemap.js";
 export default defineEventHandler(async (event) => {
-  setEponymePublicCache(event);
+  setEponymePublicCache(event, getEponymeCacheTags("sitemap"));
   return { entries: await getEponymeSitemapEntries() };
 });

package/dist/runtime/server/middleware/eponyme-no-store.js

@@ -1,6 +1,9 @@
 import { defineEventHandler, getRequestURL } from "h3";
 import { setEponymePrivateCache } from "../utils/eponyme-cache.js";
+import { EPONYME_PREVIEW_QUERY } from "../../utils/preview.js";
 export default defineEventHandler((event) => {
-  if (!getRequestURL(event).pathname.startsWith("/api/eponyme")) return;
+  const url = getRequestURL(event);
+  if (url.searchParams.has(EPONYME_PREVIEW_QUERY)) return setEponymePrivateCache(event);
+  if (!url.pathname.startsWith("/api/eponyme")) return;
   setEponymePrivateCache(event);
 });

package/dist/runtime/server/utils/eponyme-cache.d.ts

@@ -1,4 +1,6 @@
 import type { H3Event } from 'h3';
+/** Re-exported so server code keeps one import for everything cache-related. */
+export { getEponymeCacheTags } from '../../utils/cache-tags.js';
 /**
  * Published content is identical for every visitor, so both the browser and the CDN may
  * hold on to it. The two windows are deliberately different:
@@ -8,7 +10,7 @@ import type { H3Event } from 'h3';
  * - `max-age` is the browser's, and a browser cache cannot be purged by anyone. Whatever
  *   it holds is served until it expires, publication or not, which is why it stays short.
  */
-export declare function setEponymePublicCache(event: H3Event): void;
+export declare function setEponymePublicCache(event: H3Event, tags?: string[]): void;
 /**
  * Drafts and historical versions are unreleased material. `no-store` rather than
  * `no-cache`: nothing may keep a copy at all, not even one it promises to revalidate.

package/dist/runtime/server/utils/eponyme-cache.js

@@ -1,7 +1,14 @@
 import { setResponseHeader } from "h3";
 import { useRuntimeConfig } from "nitropack/runtime";
 const STALE_WHILE_REVALIDATE_FACTOR = 12;
-export function setEponymePublicCache(event) {
+export { getEponymeCacheTags } from "../../utils/cache-tags.js";
+function setCacheTags(event, tags) {
+  if (!tags.length) return;
+  const value = tags.join(",");
+  setResponseHeader(event, "Vercel-Cache-Tag", value);
+  setResponseHeader(event, "Cache-Tag", value);
+}
+export function setEponymePublicCache(event, tags = []) {
   const config = useRuntimeConfig().eponymeContent;
   const browser = Math.max(0, Math.trunc(config?.browserCacheSeconds ?? 30));
   const cdn = Math.max(0, Math.trunc(config?.cdnCacheSeconds ?? 300));
@@ -14,6 +21,7 @@ export function setEponymePublicCache(event) {
     "Cache-Control",
     `public, max-age=${browser}, s-maxage=${cdn}, stale-while-revalidate=${cdn * STALE_WHILE_REVALIDATE_FACTOR}`
   );
+  setCacheTags(event, tags);
 }
 export function setEponymePrivateCache(event) {
   setResponseHeader(event, "Cache-Control", "no-store");

package/dist/runtime/utils/cache-tags.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Single source of truth for Eponyme cache tags, shared by the API responses that carry
+ * them, the module that tags the host's page routes at build time, and any purge the host
+ * runs on publication. Kept free of server imports so `module.ts` can use it too: a page
+ * and its API response must be tagged by the same code, or a purge would drop one and
+ * leave the other.
+ *
+ * A CDN cannot usually be purged by URL — Vercel and Cloudflare both purge by tag — and one
+ * entry appears in more than one cached response: its own, its collection's listing, and the
+ * page that renders it. Tagging all of them is what lets publishing an article drop the
+ * article, the index that lists it, and the HTML a visitor would otherwise keep receiving.
+ *
+ * A comma is the delimiter every CDN uses for this header, so it is stripped rather than
+ * escaped: a tag containing one would silently become two.
+ */
+export declare function getEponymeCacheTags(name: string, collection?: {
+    name: string;
+} | string): string[];
+/** The shape of `nuxt.options.routeRules` this needs, declared so this file stays build-safe. */
+type TaggableRouteRules = Record<string, {
+    headers?: Record<string, string>;
+}>;
+/**
+ * Tags the host's public routes with the same tags their API responses carry.
+ *
+ * A published entry ends up in two caches: the JSON the browser reads, and — as soon as the
+ * host puts a route under `swr`, `isr` or `prerender` — the HTML itself. Only the first was
+ * tagged, so a purge on publication dropped the JSON and left visitors on the old page.
+ * `previewPaths` already declares which route renders which entry, which is exactly the
+ * mapping needed to tag the other one, once, at build time.
+ *
+ * A collection pattern cannot name a slug in a route rule, so its pages carry the
+ * collection-level tag: publishing one article purges every article page and the index that
+ * lists them. Broader than strictly needed, and never wrong — tagging per entry would mean
+ * tracking every entry read during a render, and nitro's request context is not shared
+ * across the internal fetch that reads them.
+ *
+ * A header the host wrote wins: this only fills in what nobody set. Returns what it did, so
+ * the module can say it out loud: writing into someone else's `routeRules` is invisible to
+ * whoever reads their own config, and an effect nobody can see is one nobody can debug.
+ */
+export declare function tagPreviewPathRoutes(previewPaths: Record<string, string>, routeRules: TaggableRouteRules): {
+    route: string;
+    tag: string;
+}[];
+export {};

package/dist/runtime/utils/cache-tags.js

@@ -0,0 +1,28 @@
+export function getEponymeCacheTags(name, collection) {
+  const collectionName = typeof collection === "string" ? collection : collection?.name;
+  const tags = ["eponyme", `eponyme:${name}`];
+  if (collectionName) tags.push(`eponyme:${collectionName}`);
+  return [...new Set(tags)].map((tag) => tag.replace(/,/g, "").slice(0, 256));
+}
+export function tagPreviewPathRoutes(previewPaths, routeRules) {
+  const tagged = [];
+  for (const [name, path] of Object.entries(previewPaths)) {
+    if (!path.startsWith("/")) continue;
+    const isCollection = path.includes(":slug");
+    const route = isCollection ? path.replace(/:slug\b.*$/, "**") : path;
+    const tags = getEponymeCacheTags(name, isCollection ? name : void 0);
+    const value = tags.join(",");
+    const existing = routeRules[route] ?? {};
+    routeRules[route] = {
+      ...existing,
+      headers: {
+        // Vercel reads its own header; `Cache-Tag` is what Cloudflare and Fastly-style CDNs read.
+        "Vercel-Cache-Tag": value,
+        "Cache-Tag": value,
+        ...existing.headers
+      }
+    };
+    tagged.push({ route, tag: tags[tags.length - 1] });
+  }
+  return tagged;
+}

package/dist/runtime/utils/hydration-cache.d.ts

@@ -9,3 +9,13 @@ import type { NuxtApp } from '#app';
  * first paint faithful and still refetches on every later navigation.
  */
 export declare function cacheDuringHydrationOnly<T>(key: string, nuxtApp: NuxtApp): T | undefined;
+/**
+ * `getCachedData` for one read, or `undefined` to keep Nuxt's own policy.
+ *
+ * Published content is the same for every visitor and already answers with a public
+ * `Cache-Control`, so Nuxt's default is exactly right: the SSR payload while hydrating,
+ * then `nuxtApp.static.data`, which prerendered and prefetched payloads fill. A client
+ * navigation to a prerendered route then costs no request at all. Unreleased material
+ * keeps refetching after hydration.
+ */
+export declare function cacheForPublicRead(isPublic: boolean): typeof cacheDuringHydrationOnly | undefined;

package/dist/runtime/utils/hydration-cache.js

@@ -1,3 +1,6 @@
 export function cacheDuringHydrationOnly(key, nuxtApp) {
   return nuxtApp.isHydrating ? nuxtApp.payload.data[key] : void 0;
 }
+export function cacheForPublicRead(isPublic) {
+  return isPublic ? void 0 : cacheDuringHydrationOnly;
+}

package/dist/runtime/utils/preview.d.ts

@@ -20,6 +20,16 @@ export declare function splitCollectionEntry(collectionNames: string[], name: st
  * returns `previewPaths[collection]` with `:slug` filled in.
  */
 export declare function resolvePreviewPath(previewPaths: Record<string, string>, collectionNames: string[], name: string): string | undefined;
+/**
+ * The query parameters that turn a public route into a preview.
+ *
+ * Named here because three places have to agree on them: the panel that builds the URL,
+ * the composables that read it, and the middleware that keeps such a response out of
+ * every cache. A typo in any one of them fails silently, in the direction of leaking.
+ */
+export declare const EPONYME_PREVIEW_QUERY = "__eponyme_preview";
+export declare const EPONYME_PREVIEW_VERSION_QUERY = "__eponyme_preview_version";
+export declare const EPONYME_PREVIEW_TOKEN_QUERY = "__eponyme_preview_token";
 /** Reads `?__eponyme_preview_version=` — `draft` by default, or a numeric history id. */
 export declare function readPreviewVersion(raw: unknown): PreviewVersion;
 /** Reads the preview query params, unwrapping the repeated-param array form. */

package/dist/runtime/utils/preview.js

@@ -18,13 +18,18 @@ export function resolvePreviewPath(previewPaths, collectionNames, name) {
   if (!pattern || !pattern.includes(":slug")) return void 0;
   return applyPreviewSlug(pattern, entry.slug);
 }
+export const EPONYME_PREVIEW_QUERY = "__eponyme_preview";
+export const EPONYME_PREVIEW_VERSION_QUERY = "__eponyme_preview_version";
+export const EPONYME_PREVIEW_TOKEN_QUERY = "__eponyme_preview_token";
 export function readPreviewVersion(raw) {
   if (raw === "published") return "published";
   const id = Number(raw);
   return Number.isSafeInteger(id) && id > 0 ? id : "draft";
 }
 export function readPreviewQuery(query) {
-  const entry = Array.isArray(query.__eponyme_preview) ? query.__eponyme_preview[0] : query.__eponyme_preview;
-  const version = Array.isArray(query.__eponyme_preview_version) ? query.__eponyme_preview_version[0] : query.__eponyme_preview_version;
+  const rawEntry = query[EPONYME_PREVIEW_QUERY];
+  const rawVersion = query[EPONYME_PREVIEW_VERSION_QUERY];
+  const entry = Array.isArray(rawEntry) ? rawEntry[0] : rawEntry;
+  const version = Array.isArray(rawVersion) ? rawVersion[0] : rawVersion;
   return { entry: entry === void 0 || entry === null ? void 0 : String(entry), version };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@karibsen/eponyme",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "A lightweight, type-safe content manager for Nuxt.",
   "license": "MIT",
   "type": "module",