@elytracms/next 0.0.90 → 0.0.92

package/dist/index.js

@@ -1,34 +1,26 @@
-import { ComponentRegistry } from '@elytracms/core/component-registry';
-export { defineComponent } from '@elytracms/core/component-registry';
-import { basePrimitives, getImplementation, registerImplementations, renderDocumentBodyItems, documentBodyItems, ImageManifest, serializeListingQuery, RenderErrorBoundary, documentBodyRichTextValues, documentBodyCompositionNodes, richTextEmbedsInValue, collectReferencedAssetIds, collectRichTextRefsInValue, collectReferencedRelations, collectReferencedListings, collectReferencedRichTextLinks, normalizeImageSource } from '@elytracms/core/runtime-renderer';
-import { isValidElement } from 'react';
+import { registerComponents, renderDocumentBodyItems, documentBodyItems, serializeListingQuery, documentBodyRichTextValues, documentBodyCompositionNodes, richTextEmbedsInValue, collectReferencedAssetIds, collectRichTextRefsInValue, collectReferencedRelations, collectReferencedListings, collectReferencedRichTextLinks, RenderErrorBoundary, nodeListingOf, listingRequestOf } from '@elytracms/core/runtime-renderer';
+import { Fragment as Fragment$1, isValidElement } from 'react';
 import { isBlockSequenceValueShape } from '@elytracms/core/rich-text';
-import { jsx, Fragment } from 'react/jsx-runtime';
+import { jsx, Fragment, jsxs } from 'react/jsx-runtime';
 import { cacheTags, isDocumentHistory, resolvedAsset, createContentClient, createContentContext } from '@elytracms/core/content';
-import { parseLocaleConfig, documentKey, splitLocalePath, hierarchyMount, composePath, localeUrlPath, mergeRouteRecords, fallbackHomeRoutes, presentationBodyFields, splitPath, documentSchema, redirectRecordSchema } from '@elytracms/core/cms-core';
-export { documentSchema, fallbackHomeRoutes, localeConfigSchema, localeUrlPath, mergeRouteRecords, parseLocaleConfig, redirectRecordSchema, resolveLocale, routeRecordSchema, splitLocalePath, textDirection } from '@elytracms/core/cms-core';
-import { revalidateTag, unstable_cache } from 'next/cache';
+import { DEFAULT_SEO_FIELD, parseLocaleConfig, documentKey, liveRedirectRecords, SEO_SUBFIELDS, splitLocalePath, DRAFT_PERSPECTIVE, splitPath, localeUrlPath, variantOf, DRAFT_VARIANT, createRouter, presentationBodyFields, documentSchema, redirectRecordSchema } from '@elytracms/core/cms-core';
+export { DRAFT_PERSPECTIVE, documentSchema, localeConfigSchema, localeUrlPath, parseLocaleConfig, redirectRecordSchema, resolveLocale, routeRecordSchema, splitLocalePath, textDirection, variantOf } from '@elytracms/core/cms-core';
+import { revalidateTag, cacheTag } from 'next/cache';
 import { draftMode } from 'next/headers';
 import { redirect, notFound, permanentRedirect } from 'next/navigation';
 import { COMPOSITE_KEY_SEPARATOR } from '@elytracms/core/project-graph';
 import { verifyRevalidationSignature, readRevalidationBody, REVALIDATE_SIGNATURE_HEADER } from '@elytracms/core/revalidation';
 export { REVALIDATE_SIGNATURE_HEADER, revalidationEventSchema, signRevalidationBody, signedRevalidationRequest } from '@elytracms/core/revalidation';
 import NextImage from 'next/image';
+import { normalizeImageSource } from '@elytracms/components';
+import { projectFrontendUrl, resolveProject } from '@elytracms/core/studio-core';
+export { defineComponent } from '@elytracms/core/component-registry';
 export { z } from 'zod';
 
 // src/components.ts
-function defineHostComponents(components = [], options = {}) {
-  const includeBase = options.includeBasePrimitives !== false;
-  const base = includeBase ? basePrimitives() : { manifests: [], implementations: {} };
-  const registry = new ComponentRegistry([...base.manifests, ...components.map((c) => c.manifest)]);
-  const implementations = {};
-  for (const manifest of base.manifests) {
-    const implementation = getImplementation(base.implementations, manifest.id);
-    if (implementation) implementations[manifest.id] = implementation;
-  }
-  const host = registerImplementations(components);
-  Object.assign(implementations, host.implementations);
-  return { registry, implementations, issues: [...registry.issues, ...host.issues] };
+function defineHostComponents(components = []) {
+  const { registry, implementations } = registerComponents(components);
+  return { registry, implementations };
 }
 function relationResolver(relations) {
   return (ref) => relations[`${ref.collection}:${ref.id}`] ?? null;
@@ -37,7 +29,22 @@ function linkResolver(links) {
   return (ref) => links[`${ref.collection}:${ref.id}`] ?? null;
 }
 function listingResolver(listings) {
-  return (query) => listings[serializeListingQuery(query)] ?? null;
+  return (query) => {
+    const baked = listings[serializeListingQuery(query)];
+    return Array.isArray(baked) ? baked : null;
+  };
+}
+function listingFailureOf(node, components, listings) {
+  const manifest = components.registry.getManifest(node.componentId);
+  if (!manifest) return null;
+  const listing = nodeListingOf(node, manifest, components.registry);
+  if (!listing || listing.state === "awaiting") return null;
+  if (listing.state === "invalid") return listing.messages;
+  const baked = listings?.[serializeListingQuery(listing.query)];
+  return baked && !Array.isArray(baked) ? baked.errors.map((error) => error.message) : null;
+}
+function InvalidListingNotice(props) {
+  return /* @__PURE__ */ jsx("div", { "data-ec-fallback": "invalid-listing", "data-ec-node-id": props.nodeId, role: "note", children: `This listing can't run: ${props.messages.join(" ")}` });
 }
 function assetResolver(assets) {
   const byId = new Map(assets.map((asset) => [asset.id, asset]));
@@ -49,7 +56,7 @@ function assetResolver(assets) {
       height: asset.height,
       alt: asset.alt,
       focalPoint: asset.focalPoint,
-      // EC-420: carry the LQIP so a placed base.Image blurs up on delivery.
+      // EC-420: carry the LQIP so a placed Image blurs up on delivery.
       lqip: asset.lqip,
       meta: asset.meta
     } : null;
@@ -86,7 +93,15 @@ async function CanvasRenderer(props) {
     // so a host that did not opt in degrades a reference link to the visible
     // `unresolved-ref` issue (EC-290) rather than a wrong href.
     ...props.links ? { resolveLink: linkResolver(props.links) } : {},
-    decorateNode: stripServerErrorBoundary
+    decorateNode: (node, rendered) => {
+      const stripped = stripServerErrorBoundary(node, rendered);
+      const failure = listingFailureOf(node, components, props.listings);
+      if (!failure) return stripped;
+      return /* @__PURE__ */ jsxs(Fragment$1, { children: [
+        /* @__PURE__ */ jsx(InvalidListingNotice, { nodeId: node.id, messages: failure }),
+        stripped
+      ] }, node.id);
+    }
   };
   const document = result.document;
   if (document) {
@@ -186,17 +201,11 @@ function createStaticContentSource(data) {
   };
 }
 async function createContentSnapshot(adapter, projectId, options) {
-  const schema = await adapter.cms.findSchema(projectId);
   const documentRecords = await adapter.cms.listDocuments(projectId);
   const versionRecords = await adapter.cms.listAllDocumentVersions(projectId);
   const assetRecords = await adapter.assets.listAssets(projectId);
   const redirectRecords = await adapter.redirects.listRedirects(projectId);
-  const redirects = redirectRecords.filter((record2) => record2.enabled).map((record2) => ({
-    id: record2.id,
-    from: record2.from,
-    to: record2.to,
-    permanent: record2.permanent
-  }));
+  const redirects = liveRedirectRecords(redirectRecords);
   const versionsByKey = /* @__PURE__ */ new Map();
   for (const record2 of versionRecords) {
     const key = `${record2.collection}:${record2.docId}`;
@@ -217,12 +226,89 @@ async function createContentSnapshot(adapter, projectId, options) {
     locales: options.locales,
     ...options.routes ? { routes: options.routes } : {},
     redirects: options.redirects ? [...options.redirects] : redirects,
-    ...schema ? { collections: schema.collections } : {},
+    collections: options.collections,
     documents,
     assets: assetRecords,
     assetUrl: (asset) => adapter.blobs.url(asset.storageKey)
   });
 }
+function seoContextOf(result, assets = []) {
+  return {
+    seoField: result.seoField ?? null,
+    title: result.title ?? null,
+    locale: result.tags.locale,
+    assets
+  };
+}
+function str(value) {
+  return typeof value === "string" && value.length > 0 ? value : null;
+}
+function looksLikeUrl(value) {
+  return /^(https?:)?\/\//.test(value) || value.startsWith("/");
+}
+function resolveSeoImage(value, assets) {
+  if (value && typeof value === "object") {
+    const url = value.url;
+    return typeof url === "string" && url.length > 0 ? url : null;
+  }
+  if (typeof value !== "string" || value.length === 0) return null;
+  if (looksLikeUrl(value)) return value;
+  return assets.find((asset) => asset.id === value)?.url ?? null;
+}
+function openGraphLocale(locale) {
+  return locale.includes("-") ? locale.replace(/-/g, "_") : null;
+}
+function seoObjectOf(doc, seoField = DEFAULT_SEO_FIELD) {
+  if (!doc || seoField === null) return {};
+  const value = doc[seoField ?? DEFAULT_SEO_FIELD];
+  return value && typeof value === "object" && !Array.isArray(value) ? value : {};
+}
+function seoMetadata(doc, ctx = {}) {
+  const seo = seoObjectOf(doc, ctx.seoField);
+  const assets = ctx.assets ?? [];
+  const seoTitle = str(seo[SEO_SUBFIELDS.title]);
+  const description = str(seo[SEO_SUBFIELDS.description]);
+  const ogTitle = str(seo[SEO_SUBFIELDS.ogTitle]);
+  const ogDescription = str(seo[SEO_SUBFIELDS.ogDescription]);
+  const image = resolveSeoImage(seo[SEO_SUBFIELDS.image], assets);
+  const noindex = seo[SEO_SUBFIELDS.noindex] === true;
+  const canonical = str(seo[SEO_SUBFIELDS.canonical]);
+  const docTitle = ctx.title !== void 0 ? str(ctx.title) : str(doc?.["title"]) ?? str(doc?.["name"]);
+  const title = seoTitle ?? docTitle;
+  const metadata = {};
+  if (title !== null) metadata.title = title;
+  if (description) metadata.description = description;
+  if (doc) {
+    const effectiveOgTitle = ogTitle ?? title;
+    const effectiveOgDescription = ogDescription ?? description;
+    const ogLocale = ctx.locale !== void 0 ? openGraphLocale(ctx.locale) : null;
+    metadata.openGraph = {
+      ...effectiveOgTitle !== null ? { title: effectiveOgTitle } : {},
+      ...effectiveOgDescription ? { description: effectiveOgDescription } : {},
+      ...image ? { images: [{ url: image }] } : {},
+      ...ogLocale !== null ? { locale: ogLocale } : {}
+    };
+  }
+  if (noindex) metadata.robots = { index: false };
+  if (canonical) metadata.alternates = { canonical };
+  return metadata;
+}
+function mergeMetadataOverParent(parent, page) {
+  if (!parent) return page;
+  const merged = { ...page };
+  for (const [key, pageValue] of Object.entries(page)) {
+    const parentValue = parent[key];
+    if (isPlainObject(pageValue) && isPlainObject(parentValue)) {
+      merged[key] = { ...parentValue, ...pageValue };
+    }
+  }
+  return merged;
+}
+function isPlainObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+// src/route-core.ts
 function canvasWrapContext(result, info) {
   const collection = result.document?.collection;
   return {
@@ -235,6 +321,7 @@ function canvasWrapContext(result, info) {
 function pathFromSlug(slug) {
   return "/" + (slug ?? []).join("/");
 }
+var systemClock = () => (/* @__PURE__ */ new Date()).toISOString();
 function scopeAssetsToPage(allAssets, registry, result, body, resolveRelation) {
   if (allAssets.length === 0) return allAssets;
   const ids = /* @__PURE__ */ new Set();
@@ -245,7 +332,7 @@ function scopeAssetsToPage(allAssets, registry, result, body, resolveRelation) {
   for (const value of body.richTexts) {
     collectRichTextRefsInValue(value, { onAsset: (id) => ids.add(id) });
   }
-  const ogImage = result.document?.["seoOgImage"];
+  const ogImage = seoObjectOf(result.document, result.seoField)[SEO_SUBFIELDS.image];
   const ogImageId = typeof ogImage === "string" ? ogImage : ogImage && typeof ogImage === "object" && typeof ogImage.id === "string" ? ogImage.id : null;
   if (ogImageId) ids.add(ogImageId);
   return ids.size === 0 ? [] : allAssets.filter((asset) => ids.has(asset.id));
@@ -281,27 +368,33 @@ function populatePageRelations(body, client, registry) {
   );
   return { relations, docKeys: [...refKeys] };
 }
-function populatePageListings(body, client, registry) {
-  if (!registry) return { listings: {}, tags: [] };
+function populatePageListings(body, client, registry, clock) {
+  if (!registry) return { listings: {}, tags: [], readsNow: false };
   const tags = [];
+  let instant;
+  const now = () => instant ??= clock();
   const listings = collectReferencedListings(
     body.nodes,
     registry,
     (query) => {
-      const listed = client.listDocuments(query.collection, {
-        where: query.where,
-        ...query.sort ? { sort: query.sort } : {},
-        ...query.limit !== void 0 ? { limit: query.limit } : {}
-      });
+      const listed = client.listDocuments(query.collection, listDocumentsQueryOf(query, now));
       tags.push(listed.tags);
-      return listed.ok ? listed.documents : [];
+      return listed.ok ? listed.documents : { errors: listed.errors };
     },
     // EC-255: reach listings nested inside transcluded reusable content (the same
     // depth-1 populate the relation bake uses), so a grid inside a reusable bakes —
     // and its membership tag is folded in — instead of rendering empty on the host.
     (ref) => client.resolveRelation(ref)
   );
-  return { listings, tags };
+  return { listings, tags, readsNow: instant !== void 0 };
+}
+function listDocumentsQueryOf(query, now) {
+  const request = listingRequestOf(query, now);
+  return {
+    where: request.where,
+    ...request.sort ? { sort: request.sort } : {},
+    ...request.limit !== void 0 ? { limit: request.limit } : {}
+  };
 }
 function populatePageLinks(body, client, registry) {
   if (!registry) return { links: {}, docKeys: [] };
@@ -359,11 +452,11 @@ async function resolveCanvasPage(source, url, perspective, options = {}) {
     options.registry
   );
   const relationTags = cacheTags({ docs: relationDocKeys, locale: result.tags.locale });
-  const { listings, tags: listingTags } = populatePageListings(
-    body,
-    client,
-    options.registry
-  );
+  const {
+    listings,
+    tags: listingTags,
+    readsNow
+  } = populatePageListings(body, client, options.registry, options.clock ?? systemClock);
   const { links, docKeys: linkDocKeys } = populatePageLinks(body, client, options.registry);
   const linkTags = cacheTags({ docs: linkDocKeys, locale: result.tags.locale });
   return {
@@ -372,6 +465,7 @@ async function resolveCanvasPage(source, url, perspective, options = {}) {
     assets: bakedAssets,
     relations,
     listings,
+    readsNow,
     links,
     ...presentation ? { presentation } : {},
     tags: mergeCacheTags(
@@ -423,7 +517,6 @@ function revalidationTags(event, project) {
     case "delete":
       tags.add(docCacheTag(`${event.collection}:${event.id}`, scope));
       for (const locale of project.locales) tags.add(collectionCacheTag(event.collection, locale, scope));
-      tags.add(projectSweepTag(scope));
       break;
     case "redirects":
       tags.add(projectSweepTag(scope));
@@ -436,135 +529,81 @@ function revalidationTags(event, project) {
   return [...tags].sort();
 }
 function canvasCacheKey({ scope, mode, url }) {
-  return ["elytra-route", scope ?? "", mode ?? "", url];
+  return JSON.stringify([scope ?? "", mode ?? "", url]);
 }
-var CacheDiscoveryBail = class extends Error {
-  constructor() {
-    super("elytra cache discovery bail (never user-visible)");
-    this.name = "CacheDiscoveryBail";
-  }
-};
-function passthrough(impl) {
-  return async () => impl();
-}
-async function loadCachedEntry(cache, keyParts, baselineTags, load) {
-  let fresh;
-  const probe = cache(
-    passthrough(async () => {
-      fresh = await load();
-      throw new CacheDiscoveryBail();
-    }),
-    keyParts,
-    { tags: [...baselineTags], revalidate: false }
-  );
+function parseCanvasCacheKey(key) {
+  let parsed;
   try {
-    return await probe();
-  } catch (error) {
-    if (!(error instanceof CacheDiscoveryBail)) throw error;
-  }
-  const entry = fresh;
-  const write = cache(
-    passthrough(async () => entry),
-    keyParts,
-    { tags: entry.tags, revalidate: false }
-  );
-  return write();
-}
-
-// src/metadata.ts
-function str(value) {
-  return typeof value === "string" && value.length > 0 ? value : null;
-}
-function looksLikeUrl(value) {
-  return /^(https?:)?\/\//.test(value) || value.startsWith("/");
-}
-function resolveOgImage(value, assets) {
-  if (value && typeof value === "object") {
-    const url = value.url;
-    return typeof url === "string" && url.length > 0 ? url : null;
+    parsed = JSON.parse(key);
+  } catch {
+    return void 0;
   }
-  if (typeof value !== "string" || value.length === 0) return null;
-  if (looksLikeUrl(value)) return value;
-  return assets.find((asset) => asset.id === value)?.url ?? null;
-}
-function openGraphLocale(locale) {
-  return locale.includes("-") ? locale.replace(/-/g, "_") : null;
-}
-function canvasPageMetadata(result, assets = []) {
-  const doc = result.document;
-  const seoTitle = str(doc?.["seoTitle"]);
-  const seoDescription = str(doc?.["seoDescription"]);
-  const seoOgTitle = str(doc?.["seoOgTitle"]);
-  const seoOgImage = resolveOgImage(doc?.["seoOgImage"], assets);
-  const seoNoindex = doc?.["seoNoindex"] === true;
-  const seoCanonical = str(doc?.["seoCanonical"]);
-  const docTitle = str(doc?.["name"]) ?? str(doc?.["title"]);
-  const title = seoTitle ?? docTitle;
-  const metadata = {};
-  if (title !== null) metadata.title = title;
-  if (seoDescription) metadata.description = seoDescription;
-  const ogTitle = seoOgTitle ?? title;
-  if (doc) {
-    const ogLocale = openGraphLocale(result.tags.locale);
-    metadata.openGraph = {
-      ...ogTitle !== null ? { title: ogTitle } : {},
-      ...seoDescription ? { description: seoDescription } : {},
-      ...seoOgImage ? { images: [{ url: seoOgImage }] } : {},
-      ...ogLocale !== null ? { locale: ogLocale } : {}
-    };
+  if (!Array.isArray(parsed) || parsed.length !== 3 || !parsed.every((part) => typeof part === "string")) {
+    return void 0;
   }
-  if (seoNoindex) metadata.robots = { index: false };
-  if (seoCanonical) metadata.alternates = { canonical: seoCanonical };
-  return metadata;
-}
-function mergeMetadataOverParent(parent, page) {
-  if (!parent) return page;
-  const merged = { ...page };
-  for (const [key, pageValue] of Object.entries(page)) {
-    const parentValue = parent[key];
-    if (isPlainObject(pageValue) && isPlainObject(parentValue)) {
-      merged[key] = { ...parentValue, ...pageValue };
-    }
+  const [scope, mode, url] = parsed;
+  return { scope, mode, url };
+}
+var NEXT_CACHE_TAG_CALL_LIMIT = 128;
+function entryTagCalls(tags, scope) {
+  const sweep = projectSweepTag(scope);
+  const rest = nextCacheTags(tags, scope).filter((tag) => tag !== sweep);
+  const calls = [[sweep]];
+  for (let start = 0; start < rest.length; start += NEXT_CACHE_TAG_CALL_LIMIT) {
+    calls.push(rest.slice(start, start + NEXT_CACHE_TAG_CALL_LIMIT));
   }
-  return merged;
-}
-function isPlainObject(value) {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
+  return calls;
 }
+var CANVAS_VALIDATION_SLUG = ["_elytra"];
+var CANVAS_VALIDATION_PATH = pathFromSlug([...CANVAS_VALIDATION_SLUG]);
 function defaultMetadata(result, assets) {
-  return canvasPageMetadata(result, assets);
+  return seoMetadata(result.document, seoContextOf(result, assets));
 }
 async function requestPerspective() {
   const { isEnabled } = await draftMode();
-  return isEnabled ? "draft" : "published";
+  return isEnabled ? DRAFT_PERSPECTIVE : "published";
 }
-var nextCacheWrapper = (cb, keyParts, options) => unstable_cache(cb, keyParts, { tags: options.tags, revalidate: options.revalidate });
 function createCanvasRoute(options) {
-  const loadOutcome = async (url, perspective) => {
-    const resolveFresh = async () => {
-      const source = await options.loadContent({ perspective });
-      return resolveCanvasPage(source, url, perspective, {
-        // EC-205: page-scope the baked assets to what the page actually uses.
-        registry: options.components.registry
-      });
-    };
-    const devBypass = process.env.NODE_ENV === "development";
-    if (!options.cache || perspective !== "published" || devBypass) return resolveFresh();
-    const scope = options.cache.scope;
-    const entry = await loadCachedEntry(
-      nextCacheWrapper,
-      canvasCacheKey({ scope, mode: options.cache.mode, url }),
-      [projectSweepTag(scope)],
-      async () => {
-        const outcome = await resolveFresh();
-        return { value: outcome, tags: nextCacheTags(outcome.tags, scope) };
-      }
+  if (Object.hasOwn(options, "published") && options.published === void 0) {
+    throw new Error(
+      "Elytra canvas route: `published` was passed but is undefined. If it names your cache function (the one carrying the cache directive), declare that function ABOVE the canvasRoute() call \u2014 Next compiles a cached function into a variable assigned where it is written, so it is not hoisted like a plain function. To render without a cache, omit `published` entirely."
     );
-    return entry.value;
+  }
+  const resolveFresh = async (url, perspective) => {
+    const source = await options.loadContent({ perspective });
+    return resolveCanvasPage(source, url, perspective, {
+      // EC-205: page-scope the baked assets to what the page actually uses.
+      registry: options.components.registry
+    });
+  };
+  const scope = options.scope ?? "";
+  const mode = options.mode ?? "";
+  const keyFor = (url) => canvasCacheKey({ scope, mode, url });
+  const resolve = async (key) => {
+    const parts = parseCanvasCacheKey(key);
+    if (!parts) {
+      throw new Error(
+        `Elytra canvas route: resolve() was handed ${JSON.stringify(key)}, which is not a key this route produced. Pass your cache function's argument through unchanged \u2014 it is the entry's key.`
+      );
+    }
+    if (parts.scope !== scope || parts.mode !== mode) {
+      throw new Error(
+        `Elytra canvas route: resolve() was handed a cache key of scope "${parts.scope}" and content mode "${parts.mode}", but this route resolves in scope "${scope}" and mode "${mode}". The entry would be keyed under one world and filled from another (EC-543). Pass each route's \`published\` function the key that route hands it, and call that same route's resolve().`
+      );
+    }
+    return resolveFresh(parts.url, "published");
+  };
+  const applyCacheTags = (result) => {
+    for (const tags of entryTagCalls(result.tags, scope)) cacheTag(...tags);
+  };
+  const loadOutcome = async (url, perspective) => {
+    if (perspective !== "published" || !options.published) return resolveFresh(url, perspective);
+    return options.published(keyFor(url));
   };
   const Page = async (props) => {
     const { slug } = await props.params;
     const url = pathFromSlug(slug);
+    if (url === CANVAS_VALIDATION_PATH) return notFound();
     const perspective = await requestPerspective();
     const outcome = await loadOutcome(url, perspective);
     options.onTags?.(outcome.tags, { url, perspective });
@@ -594,8 +633,9 @@ function createCanvasRoute(options) {
   const pageMetadata = async (props) => {
     const { slug } = await props.params;
     const url = pathFromSlug(slug);
+    if (url === CANVAS_VALIDATION_PATH) return {};
     const perspective = await requestPerspective();
-    if (options.cache && perspective === "published") {
+    if (options.published && perspective === "published") {
       const outcome2 = await loadOutcome(url, perspective);
       if (outcome2.kind !== "render") return {};
       return options.metadata ? options.metadata(outcome2.result, { url, perspective }) : defaultMetadata(outcome2.result, outcome2.assets);
@@ -609,29 +649,16 @@ function createCanvasRoute(options) {
     const [page, resolvedParent] = await Promise.all([pageMetadata(props), parent]);
     return mergeMetadataOverParent(resolvedParent, page);
   };
-  return { Page, generateMetadata };
-}
-function paramNamesOf(pattern) {
-  return splitPath(pattern).filter((segment) => segment.startsWith(":")).map((segment) => segment.slice(1));
-}
-function fillPattern(pattern, params) {
-  const segments = [];
-  for (const segment of splitPath(pattern)) {
-    if (!segment.startsWith(":")) {
-      segments.push(segment);
-      continue;
-    }
-    const value = params[segment.slice(1)];
-    if (value === void 0 || value.length === 0) return null;
-    segments.push(encodeURIComponent(value));
-  }
-  return "/" + segments.join("/");
+  const generateStaticParams = async () => [
+    { slug: [...CANVAS_VALIDATION_SLUG] }
+  ];
+  return { Page, generateMetadata, resolve, applyCacheTags, generateStaticParams };
 }
 function originOf(baseUrl) {
   return baseUrl.replace(/\/+$/, "");
 }
 function canvasSitemapEntries(source, options) {
-  const routes = options.routes ?? source.routes ?? [];
+  const routes = source.routes ?? [];
   const locales = source.locales;
   const skipped = [];
   const skip = (route, reason) => {
@@ -648,83 +675,79 @@ function canvasSitemapEntries(source, options) {
     }
     return client;
   };
-  const byUrl = /* @__PURE__ */ new Map();
-  const byGroup = /* @__PURE__ */ new Map();
+  const candidates = [];
+  const collectionLocales = /* @__PURE__ */ new Map();
   for (const route of routes) {
-    const paramNames = paramNamesOf(route.pattern);
-    const mount = hierarchyMount(route);
-    const routeLocales = route.locale ? [route.locale] : locales.locales;
-    for (const locale of routeLocales) {
-      const client = clientFor(locale);
-      let paths;
-      if (mount) {
-        const listed = client.listDocuments(mount.collection);
-        if (!listed.ok) {
-          skip(route, `hierarchy collection "${mount.collection}" could not be listed`);
-          continue;
-        }
-        const rows = listed.documents.map((doc) => ({
-          collection: mount.collection,
-          id: doc.id,
-          values: { slug: doc["slug"], parent: doc["parent"] }
-        }));
-        const byId = new Map(rows.map((row) => [row.id, row]));
-        paths = [];
-        for (const row of rows) {
-          if (typeof row.values["slug"] !== "string" || row.values["slug"] === "") continue;
-          const composed = composePath(row, (id) => byId.get(id));
-          if (!composed.ok) continue;
-          paths.push("/" + [...mount.prefix, ...composed.segments].join("/"));
-        }
-      } else if (paramNames.length === 0) {
-        paths = [route.pattern];
-      } else {
-        const paramSets = options.params?.({ route, locale, client });
-        if (paramSets == null) {
-          skip(route, "dynamic route not enumerated (no params provider entry)");
-          continue;
-        }
-        paths = [];
-        for (const paramSet of paramSets) {
-          const path = fillPattern(route.pattern, paramSet);
-          if (path === null) {
-            skip(route, `params entry missing one of :${paramNames.join(", :")}`);
-            continue;
-          }
-          paths.push(path);
-        }
-      }
-      let unresolved = 0;
-      for (const path of paths) {
-        const result = client.resolvePage(path, locale);
-        if (result.status !== "ok") {
-          if (result.status !== "redirect") unresolved += 1;
-          continue;
-        }
-        if (result.document?.["seoNoindex"] === true) continue;
-        const { urlPath, addressable } = localeUrlPath(path, locale, locales);
-        if (!addressable) {
-          skip(
-            route,
-            `"${path}" (locale "${locale}") has no addressable URL \u2014 its first segment is read as a locale prefix`
-          );
-          continue;
-        }
-        const absolute = originOf(options.baseUrl) + urlPath;
-        const group = result.document ? `${route.id}${COMPOSITE_KEY_SEPARATOR}doc${COMPOSITE_KEY_SEPARATOR}${result.document.collection}${COMPOSITE_KEY_SEPARATOR}${result.document.id}` : `${route.id}${COMPOSITE_KEY_SEPARATOR}path${COMPOSITE_KEY_SEPARATOR}${path}`;
-        if (!byUrl.has(absolute)) byUrl.set(absolute, { group, locale });
-        const perLocale = byGroup.get(group) ?? /* @__PURE__ */ new Map();
-        if (!perLocale.has(locale)) perLocale.set(locale, absolute);
-        byGroup.set(group, perLocale);
-      }
-      if (mount && paths.length > 0 && unresolved === paths.length) {
-        skip(
-          route,
-          `hierarchy mount over "${mount.collection}" composed ${paths.length} path(s) in locale "${locale}", none of which the resolver serves`
-        );
+    if (!route.document) continue;
+    const set = collectionLocales.get(route.document.collection) ?? /* @__PURE__ */ new Set();
+    for (const locale of route.locale ? [route.locale] : locales.locales) set.add(locale);
+    collectionLocales.set(route.document.collection, set);
+  }
+  for (const [collection, routeLocales] of collectionLocales) {
+    for (const locale of locales.locales) {
+      if (!routeLocales.has(locale)) continue;
+      for (const entry of clientFor(locale).urlsFor(collection)) {
+        candidates.push({
+          route: entry.route,
+          locale,
+          routePath: entry.routePath,
+          path: entry.path,
+          addressable: entry.addressable,
+          // EC-517: group by the DOCUMENT — the locale-invariant fact — scoped by route.
+          group: `${entry.route.id}${COMPOSITE_KEY_SEPARATOR}doc${COMPOSITE_KEY_SEPARATOR}${collection}${COMPOSITE_KEY_SEPARATOR}${entry.id}`
+        });
       }
     }
   }
+  for (const route of routes) {
+    if (route.document || splitPath(route.pattern).some((segment) => segment.startsWith(":"))) continue;
+    for (const locale of route.locale ? [route.locale] : locales.locales) {
+      const { urlPath, addressable } = localeUrlPath(route.pattern, locale, locales);
+      candidates.push({
+        route,
+        locale,
+        routePath: route.pattern,
+        path: urlPath,
+        addressable,
+        group: `${route.id}${COMPOSITE_KEY_SEPARATOR}path${COMPOSITE_KEY_SEPARATOR}${route.pattern}`
+      });
+    }
+  }
+  const byUrl = /* @__PURE__ */ new Map();
+  const byGroup = /* @__PURE__ */ new Map();
+  const tally = /* @__PURE__ */ new Map();
+  for (const candidate of candidates) {
+    const key = `${candidate.route.id}${COMPOSITE_KEY_SEPARATOR}${candidate.locale}`;
+    const count = tally.get(key) ?? { route: candidate.route, locale: candidate.locale, total: 0, unresolved: 0 };
+    count.total += 1;
+    tally.set(key, count);
+    const result = clientFor(candidate.locale).resolvePage(candidate.routePath, candidate.locale);
+    if (result.status !== "ok") {
+      if (result.status !== "redirect") count.unresolved += 1;
+      continue;
+    }
+    if (seoObjectOf(result.document, result.seoField)[SEO_SUBFIELDS.noindex] === true) continue;
+    if (!candidate.addressable) {
+      skip(
+        candidate.route,
+        `"${candidate.routePath}" (locale "${candidate.locale}") has no addressable URL \u2014 its first segment is read as a locale prefix`
+      );
+      continue;
+    }
+    const absolute = originOf(options.baseUrl) + candidate.path;
+    if (!byUrl.has(absolute)) byUrl.set(absolute, { group: candidate.group, locale: candidate.locale });
+    const perLocale = byGroup.get(candidate.group) ?? /* @__PURE__ */ new Map();
+    if (!perLocale.has(candidate.locale)) perLocale.set(candidate.locale, absolute);
+    byGroup.set(candidate.group, perLocale);
+  }
+  for (const { route, locale, total, unresolved } of tally.values()) {
+    if (total > 0 && unresolved === total && route.document && splitPath(route.pattern).at(-1)?.endsWith("*")) {
+      skip(
+        route,
+        `hierarchy mount over "${route.document.collection}" composed ${total} path(s) in locale "${locale}", none of which the resolver serves`
+      );
+    }
+  }
   const entries = [];
   for (const [url, { group }] of byUrl) {
     const perLocale = byGroup.get(group);
@@ -828,8 +851,8 @@ function createAssetImageLoader(options = {}) {
     return `${src}${separator}${widthParam}=${width}&${qualityParam}=${quality ?? defaultQuality}`;
   };
 }
-function createNextImagePrimitive(options) {
-  return function NextImagePrimitive(props) {
+function createNextImage(options) {
+  return function ElytraNextImage(props) {
     const { url, width, height, alt, focalPoint, lqip } = normalizeImageSource(props);
     if (url.length === 0) return null;
     return /* @__PURE__ */ jsx(
@@ -844,11 +867,12 @@ function createNextImagePrimitive(options) {
     );
   };
 }
-function nextImagePrimitive(options = {}) {
-  return {
-    manifest: ImageManifest,
-    implementation: createNextImagePrimitive(options)
-  };
+function withNextImage(components, options = {}) {
+  const list = [...components ?? []];
+  const image = registerComponents(list).registry.roleComponent("image");
+  if (!image) return list;
+  const implementation = createNextImage(options);
+  return list.map((entry) => entry.manifest === image ? { manifest: entry.manifest, implementation } : entry);
 }
 function elytraHostImage(options = {}) {
   return ({ asset, alt, className, priority, sizes, loading }) => /* @__PURE__ */ jsx(
@@ -925,7 +949,7 @@ function parseRedirects(rows) {
 function assembleLiveSource(payload, options, perspective) {
   const locales = options.locales;
   const documents = parseDocuments(payload.documents);
-  const routes = mergeRouteRecords([...options.routes], fallbackHomeRoutes(documents, locales));
+  const routes = [...options.routes];
   const documentSources = perspective === "published" ? documents.map((doc) => ({ draft: doc, published: doc, versions: [] })) : documents;
   return createStaticContentSource({
     projectId: payload.projectId,
@@ -944,7 +968,13 @@ async function loadLiveContent(options, perspective) {
   const fetchImpl = options.fetch ?? globalThis.fetch;
   const args = { projectId: options.projectId };
   let payload;
-  if (perspective === "draft") {
+  const variant = variantOf(perspective);
+  if (variant !== void 0) {
+    if (variant !== DRAFT_VARIANT) {
+      throw new Error(
+        `Elytra live content: no delivery snapshot serves the "${variant}" variant \u2014 the deployment serves the published snapshot and the "${DRAFT_VARIANT}" variant's only.`
+      );
+    }
     if (!options.draftToken) {
       throw new Error(
         "Draft preview requested but DRAFT_PREVIEW_TOKEN is not configured on the host."
@@ -1028,8 +1058,6 @@ function resolveGlobals(source, options = {}) {
       if (typeof shaped.path === "string" && shaped.path.startsWith("/")) {
         return { href: shaped.path, openInNewTab };
       }
-      const slug = str2(shaped.slug);
-      if (slug) return { href: `/${slug}`, openInNewTab };
       return null;
     }
     return null;
@@ -1156,12 +1184,35 @@ function createPreviewDisableRoute() {
 }
 
 // src/host-kit.ts
-function materializeRoutes(routes, collections) {
-  return typeof routes === "function" ? routes([...collections]) : [...routes];
+function resolveHostProject(entry) {
+  const result = resolveProject(entry);
+  if (result.ok) return result.project;
+  const lines = result.issues.filter((issue) => issue.severity === "error").map((issue) => {
+    const at = issue.path.length > 0 ? ` at ${issue.path.join(".")}` : "";
+    return `  \u2022 ${issue.code}${at}: ${issue.message}`;
+  });
+  throw new Error(
+    `Elytra delivery host: the project config "${String(entry["slug"])}" is invalid \u2014 the studio refuses it too:
+${lines.join("\n")}`
+  );
+}
+function surfaceRouteIssues(slug, issues) {
+  if (issues.length === 0) return;
+  const building = process.env["NEXT_PHASE"] === "phase-production-build";
+  if (!building && process.env["NODE_ENV"] === "production") return;
+  const lines = issues.map((issue) => `  \u2022 ${issue.severity} ${issue.code}: ${issue.message}`);
+  const report = `[elytra] project "${slug}": ${issues.length} route issue(s) \u2014
+${lines.join("\n")}`;
+  if (issues.some((issue) => issue.severity === "error")) console.error(report);
+  else console.warn(report);
 }
 function createElytraHost(options) {
-  const env = resolveHostEnv(options.env ?? process.env);
-  const routes = materializeRoutes(options.routes, options.collections);
+  const { env: envOption, fallbackContent, globals, fetch: fetchOption, ...entry } = options;
+  const project = resolveHostProject(entry);
+  const env = resolveHostEnv(envOption ?? process.env);
+  const routes = project.routes;
+  const routeIssues = createRouter(project).issues;
+  surfaceRouteIssues(project.slug, routeIssues);
   const live = env.convexUrl !== void 0 && env.projectId !== void 0;
   if (!live && (env.convexUrl !== void 0 || env.projectId !== void 0)) {
     const [present, missing] = env.convexUrl !== void 0 ? [ELYTRA_HOST_ENV_KEYS.convexUrl, ELYTRA_HOST_ENV_KEYS.projectId] : [ELYTRA_HOST_ENV_KEYS.projectId, ELYTRA_HOST_ENV_KEYS.convexUrl];
@@ -1169,26 +1220,16 @@ function createElytraHost(options) {
       `Elytra delivery host: ${present} is set but ${missing} is not \u2014 live content needs both. Left as it is, this site would serve fallback content and look healthy. Set ${missing} to go live, or unset ${present} to run the no-backend fallback on purpose.`
     );
   }
-  const contentMode = live ? "live" : options.fallbackContent ? "fallback" : "empty";
-  const contentScope = live ? env.projectId : options.slug;
-  const components = defineHostComponents([
-    // Batteries included (EC-368 image defaults): graph `base.Image` nodes render
-    // through next/image — resized variants via the host's own optimizer. The
-    // canonical manifest stays (first registration wins in defineHostComponents).
-    ...options.image === false ? [] : [nextImagePrimitive(options.image ?? {})],
-    // EC-539: the option is the CONFIG's entry shape (`implementation: unknown`)
-    // so the recommended `{ ...site }` spread compiles; EC-541: registration
-    // takes that shape too and checks each implementation at runtime (see the
-    // option's doc comment) — no narrowing cast here.
-    ...options.components ?? []
-  ]);
+  const contentMode = live ? "live" : fallbackContent ? "fallback" : "empty";
+  const contentScope = live ? env.projectId : project.slug;
+  const components = defineHostComponents(project.components ?? []);
   const emptySource = createStaticContentSource({
     projectId: contentScope,
-    locales: options.locales,
+    locales: project.locales,
     routes,
     // Redirects are editorial DATA (EC-303) — the no-backend build has none.
     redirects: [],
-    collections: [...options.collections],
+    collections: project.collections,
     documents: [],
     assets: []
   });
@@ -1198,16 +1239,16 @@ function createElytraHost(options) {
         {
           convexUrl: env.convexUrl,
           projectId: env.projectId,
-          locales: options.locales,
-          collections: options.collections,
+          locales: project.locales,
+          collections: project.collections,
           routes,
           ...env.draftToken ? { draftToken: env.draftToken } : {},
-          ...options.fetch ? { fetch: options.fetch } : {}
+          ...fetchOption ? { fetch: fetchOption } : {}
         },
         request.perspective
       );
     }
-    if (options.fallbackContent) return options.fallbackContent(request);
+    if (fallbackContent) return fallbackContent(request);
     return Promise.resolve(emptySource);
   };
   const loadGlobals = async (globalsOptions = {}) => {
@@ -1215,21 +1256,22 @@ function createElytraHost(options) {
     const source = await loadContent({ perspective });
     return resolveGlobals(source, {
       perspective,
-      ...options.globals ? { conventions: options.globals } : {}
-    });
-  };
-  const canvasRoute = (routeOptions = {}) => {
-    const { cache, ...rest } = routeOptions;
-    return createCanvasRoute({
-      loadContent,
-      components,
-      // Tag scope = `contentScope`, the SAME value `revalidateRoute` derives its
-      // invalidation tags with (EC-579) — one scope, so they cannot disagree.
-      // EC-543: the mode is in the entry key so no world ever reads another's entries.
-      ...cache === false ? {} : { cache: { mode: contentMode, scope: contentScope } },
-      ...rest
+      ...globals ? { conventions: globals } : {}
     });
   };
+  const canvasRoute = (routeOptions = {}) => createCanvasRoute({
+    ...routeOptions,
+    loadContent,
+    components,
+    // EC-620: the route caches nothing itself; these reach the host's own cache
+    // function. Tag scope = `contentScope`, the SAME value `revalidateRoute` derives
+    // its invalidation tags with (EC-579) — so `route.applyCacheTags` writes exactly
+    // the strings the receiver revalidates. EC-543: the mode rides in every cache key
+    // the route hands out, so no world ever reads another's entries. Spread last:
+    // neither can be overridden.
+    scope: contentScope,
+    mode: contentMode
+  });
   const revalidateRoute = (overrides = {}) => createRevalidateRoute({
     // An unset secret keeps the endpoint CLOSED (401) — the kit never ships a
     // default secret (an auth-shaped no-op is worse than an explicit gap).
@@ -1238,26 +1280,29 @@ function createElytraHost(options) {
     // under (`canvasRoute` above) and every locale it serves. The emitter sends only
     // the event, so this is the one place the scope and locales are read for it.
     scope: contentScope,
-    locales: options.locales.locales
+    locales: project.locales.locales
   });
   const previewRoute = () => createPreviewRoute({ token: env.draftToken });
   const previewDisableRoute = () => createPreviewDisableRoute();
   const pageOpensFullBleed = async (slug) => {
-    const { isEnabled } = await draftMode();
-    const perspective = isEnabled ? "draft" : "published";
+    const perspective = await requestPerspective();
     const source = await loadContent({ perspective });
     const { locale, path } = splitLocalePath(pathFromSlug(slug), source.locales);
     const client = source.client({ perspective, locale });
     const resolved = client.resolvePage(path);
     return firstBlockFullBleed(resolved.document, components.registry);
   };
+  const frontendUrl = projectFrontendUrl(project);
   return {
+    routeIssues,
+    collections: options.collections,
     contentScope,
     contentMode,
     env,
+    project,
     routes,
     components,
-    ...options.frontendUrl !== void 0 ? { frontendUrl: options.frontendUrl } : {},
+    ...frontendUrl !== void 0 ? { frontendUrl } : {},
     loadContent,
     loadGlobals,
     canvasRoute,
@@ -1269,6 +1314,6 @@ function createElytraHost(options) {
 }
 var PACKAGE = "@elytracms/next";
 
-export { CanvasRenderer, ELYTRA_HOST_ENV_KEYS, ElytraImage, PACKAGE, assembleLiveSource, bodyItemsOf, canvasPageMetadata, canvasSitemapEntries, collectionCacheTag, createAssetImageLoader, createCanvasRoute, createCanvasSitemap, createContentSnapshot, createElytraHost, createPreviewDisableRoute, createPreviewRoute, createRevalidateRoute, createStaticContentSource, defineHostComponents, docCacheTag, elytraHostImage, evaluatePreviewRequest, evaluateRevalidateRequest, firstBlockFullBleed, loadCachedEntry, loadLiveContent, mergeCacheTags, mergeMetadataOverParent, nextCacheTags, nextImagePrimitive, openGraphLocale, pathFromSlug, projectSweepTag, resolveCanvasPage, resolveGlobals, resolveHostEnv, revalidationTags, routeCacheTag, safeRedirectTarget, scopeCacheTag };
+export { CANVAS_VALIDATION_SLUG, CanvasRenderer, ELYTRA_HOST_ENV_KEYS, ElytraImage, PACKAGE, assembleLiveSource, bodyItemsOf, canvasSitemapEntries, collectionCacheTag, createAssetImageLoader, createCanvasRoute, createCanvasSitemap, createContentSnapshot, createElytraHost, createPreviewDisableRoute, createPreviewRoute, createRevalidateRoute, createStaticContentSource, defineHostComponents, docCacheTag, elytraHostImage, evaluatePreviewRequest, evaluateRevalidateRequest, firstBlockFullBleed, loadLiveContent, mergeCacheTags, mergeMetadataOverParent, nextCacheTags, openGraphLocale, pathFromSlug, projectSweepTag, requestPerspective, resolveCanvasPage, resolveGlobals, resolveHostEnv, revalidationTags, routeCacheTag, safeRedirectTarget, scopeCacheTag, seoContextOf, seoMetadata, seoObjectOf, withNextImage };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map