feat: support Cache Components

[angeloashmore]

Resolves: N/A

Description

This PR adds support for Cache Components using three new APIs:

1. cacheTagPrismicPages() - Calls cacheTag for Prismic pages and their dependent pages.
2. revalidatePrismicPages() - Calls revalidateTag for Prismic pages.
3. getPrismicCacheTags() - Converts a list of Prismic pages to cache tags. Used by cacheTagPrismicPages().

Cache tags are formatted as prismic/${id}, where id is a Prismic page's ID. With the above APIs, developers shouldn't be writing cache tags manually for Prismic pages.

Checklist

• A comprehensive Linear ticket, providing sufficient context and details to facilitate the review of the PR, is linked to the PR.
• If my changes require tests, I added them.
• If my changes affect backward compatibility, it has been discussed.
• If my changes require an update to the CONTRIBUTING.md guide, I updated it.

Preview

Tagging a page:

// app/[uid]/page.tsx

export default async function Page({ params }: PageProps<"/[uid]">) {
  "use cache: remote";
  cacheLife("max");

  const { uid } = await params;
  const client = createClient();
  const page = await client.getByUID("page", uid);
  cacheTagPrismicPages([page]);

  return <SliceZone slices={page.data.slices} components={components} />;
}

Revalidating changed pages:

// app/api/revalidate/route.ts

export async function POST(request: Request) {
  const body: WebhookBody = await request.json();

  if (body.type === "api-update") revalidatePrismicPages(body.documents);

  return NextResponse.json({ revalidated: true, now: Date.now() });
}

How to QA ¹

Footnotes

1. Please use these labels when submitting a review:
   ❓ #ask: Ask a question.
   💡 #idea: Suggest an idea.
   ⚠️ #issue: Strongly suggest a change.
   🎉 #nice: Share a compliment. ↩

[angeloashmore]

Two additions to round out the preview story for Cache Components:

1. Add getPreviewRef() — the read-side counterpart to redirectToPreviewURL.

enableAutoPreviews can't be used with use cache: it injects the ref via queryContentFromRef(() => cookies()…), i.e. it reads request data at query time. That can't run inside a cached scope, and even if it could, the ref wouldn't be part of the cache key. So under Cache Components the ref has to be read outside the cached function and passed in as an argument so it lands in the key.

getPreviewRef() should mirror enableAutoPreviews' read logic: bail if !draftMode().isEnabled, read cookie.preview (the same @prismicio/client constant redirectToPreviewURL already writes), and apply the same websitePreviewId= gate. Returns Promise<string | undefined>.

// page.tsx
const page = await fetchPage(uid, await getPreviewRef());
// fetchPage keeps "use cache" + cacheLife + cacheTagPrismicPages in userland — untouched

2. Clear cookie.preview in exitPreview() — it currently only disables draft mode and leaves the cookie behind. redirectToPreviewURL owns the write, so exitPreview should own the clear and close the loop.

Both keep use cache / cacheLife / cacheTag fully in userland — the SDK just owns the preview-cookie contract end to end (write → read → clear).