@elytracms/next 0.0.82 → 0.0.83

package/dist/index.d.ts

@@ -16,6 +16,7 @@ import { z } from 'zod';
 export { z } from 'zod';
 import { ImageLoader } from 'next/image';
 import { HostImageRenderer } from './host-image.js';
+import { HostComponentEntry } from '@elytracms/core/studio-core';
 
 /**
  * One host-repo component: the manifest the builder edits against plus the
@@ -1491,8 +1492,26 @@ interface ElytraHostOptions {
      * SAME modules the studio composes with). Base primitives are always
      * included; `base.Image` is swapped for `next/image` delivery by default
      * (see `image`).
+     *
+     * Typed as the CONFIG's `HostComponentEntry` (`implementation: unknown`), not
+     * the stricter {@link HostComponent}, so that `createElytraHost({ ...site })`
+     * — the shape EC-532 makes the contract — compiles however the consumer typed
+     * their project entry. It previously demanded `ComponentType`, which meant the
+     * recommended spread worked only when the entry's implementation types
+     * survived inference: `apps/demo/elytra.config.ts` gets away with it via
+     * `satisfies`, and anyone using the engine's own published `HostComponentEntry`
+     * / `WorkspaceProjectEntry` annotation did not. Both production consumers hit
+     * exactly that and each carried one hand-restated `components` line (EC-539).
+     *
+     * What this costs, stated plainly rather than glossed: a list passed HERE no
+     * longer gets a compile-time check that each `implementation` is really a
+     * component, and nothing yet checks it at runtime either — a garbage value
+     * would reach the renderer. `defineHostComponents` keeps the strict
+     * {@link HostComponent} signature, so a hand-built list passed there directly
+     * is still checked. Closing the gap properly needs a registration issue code
+     * in the core registry; booked as EC-541 rather than smuggled in here.
      */
-    components?: readonly HostComponent[];
+    components?: readonly HostComponentEntry[];
     /**
      * `base.Image` delivery options (loader/sizes/quality — the non-Vercel CDN
      * seam), or `false` to keep the plain-`<img>` primitive. Default: Next's own
@@ -1548,6 +1567,25 @@ interface LoadGlobalsOptions {
     /** Perspective of the chrome read. Default `'published'` (live is published-only). */
     perspective?: Perspective;
 }
+/**
+ * Which world {@link ElytraHost.loadContent} reads from.
+ *
+ * - `live` — the configured Convex deployment (published; token-gated draft).
+ * - `fallback` — the host's own `fallbackContent` world (the scaffold's seeded
+ *   starter, the demo's in-memory fixture). A legitimate, supported mode.
+ * - `empty` — no backend and no fallback: this project's structure with no
+ *   content, so every URL is a clean 404. Correct for a CI build; almost never
+ *   what a deployed site intends.
+ *
+ * The mode was decided from env long before EC-527 and readable by **nobody**,
+ * so a site serving the fallback looked identical from the outside to one
+ * reading the real deployment. Measured on the demo: `/` returned `200` while
+ * all four of EC-512's published fixtures 404'd — an agent following AGENTS.md
+ * §5 gets no signal that the thing under test was never exercised. Declared
+ * once, read here, so a host can *say* which world it is in instead of
+ * re-deriving it from `env` and drifting.
+ */
+type ElytraContentMode = 'live' | 'fallback' | 'empty';
 /** The delivery host handle {@link createElytraHost} yields. */
 interface ElytraHost {
     /**
@@ -1555,6 +1593,13 @@ interface ElytraHost {
      * studio's webhook tags), else the config slug.
      */
     contentScope: string;
+    /**
+     * Which world {@link loadContent} reads from — see {@link ElytraContentMode}.
+     * Read it to announce the mode (a boot line, a dev-only banner) rather than
+     * re-deriving it from {@link env}, which is the drift this field exists to
+     * prevent.
+     */
+    contentMode: ElytraContentMode;
     /** The resolved env bag (documented names, trimmed, empty = unset). */
     env: ElytraHostEnv;
     /** Materialized route records (a derive is run once, at factory time). */
@@ -1742,4 +1787,4 @@ declare function evaluatePreviewRequest(requestUrl: string | URL, expectedToken:
  */
 declare const PACKAGE = "@elytracms/next";
 
-export { type AssetImageLoaderOptions, type BindingPayloads, type CacheWrapper, type CacheWrapperOptions, type CachedEntry, type CanvasCacheOptions, type CanvasContentRequest, type CanvasDataSource, type CanvasPageOutcome, type CanvasPayloadContext, type CanvasPayloadsFactory, CanvasRenderer, type CanvasRendererProps, type CanvasRequestInfo, type CanvasRoute, type CanvasRouteOptions, type CanvasRouteProps, type CanvasSitemapOptions, type CanvasSitemapResult, type CanvasWrapContext, type ContentSnapshot, type ContentSnapshotOptions, type ContentSource, type CreateCanvasSitemapOptions, type DefineHostComponentsOptions, type DeliveryPresentation, ELYTRA_HOST_ENV_KEYS, type ElytraHost, type ElytraHostEnv, type ElytraHostImageOptions, type ElytraHostOptions, ElytraImage, type ElytraImageAsset, type ElytraImageProps, type GlobalsConventions, type HostCanvasRouteOptions, type HostComponent, type HostComponents, type LiveContentOptions, type LoadGlobalsOptions, type MaterializeSourcePayloadsInput, type MaterializedSourcePayloads, type NextImagePrimitiveOptions, PACKAGE, type PreviewEvaluation, type PreviewRouteHandlers, type PreviewRouteOptions, REVALIDATE_SIGNATURE_HEADER, type ResolveCanvasPageOptions, type ResolveGlobalsOptions, type ResolvedLink, type ResolvedNavEntry, type ResolvedNavLink, type RevalidateEvaluation, type RevalidatePayload, type RevalidateRouteHandlers, type RevalidateRouteOptions, type SiteGlobals, type SitemapParamsProvider, type SitemapRouteContext, type SitemapSkippedRoute, type SourcePayloadError, type StaticContentData, assembleLiveSource, bodyItemsOf, canvasPageMetadata, canvasSitemapEntries, collectBindingSourceIds, collectionCacheTag, createAssetImageLoader, createBindingResolver, createCanvasRoute, createCanvasSitemap, createContentSnapshot, createElytraHost, createPreviewDisableRoute, createPreviewRoute, createRevalidateRoute, createStaticContentSource, defaultBindingPayloads, defineHostComponents, docCacheTag, elytraHostImage, evaluatePreviewRequest, evaluateRevalidateRequest, firstBlockFullBleed, isSourcePayloadError, loadCachedEntry, loadLiveContent, materializeSourcePayloads, mergeCacheTags, nextCacheTags, nextImagePrimitive, pathFromSlug, projectSweepTag, resolveCanvasPage, resolveGlobals, resolveHostEnv, resolvePayloadToken, revalidatePayloadSchema, routeCacheTag, safeRedirectTarget, scopeCacheTag, signRevalidateBody, sourcePayloadError };
+export { type AssetImageLoaderOptions, type BindingPayloads, type CacheWrapper, type CacheWrapperOptions, type CachedEntry, type CanvasCacheOptions, type CanvasContentRequest, type CanvasDataSource, type CanvasPageOutcome, type CanvasPayloadContext, type CanvasPayloadsFactory, CanvasRenderer, type CanvasRendererProps, type CanvasRequestInfo, type CanvasRoute, type CanvasRouteOptions, type CanvasRouteProps, type CanvasSitemapOptions, type CanvasSitemapResult, type CanvasWrapContext, type ContentSnapshot, type ContentSnapshotOptions, type ContentSource, type CreateCanvasSitemapOptions, type DefineHostComponentsOptions, type DeliveryPresentation, ELYTRA_HOST_ENV_KEYS, type ElytraContentMode, type ElytraHost, type ElytraHostEnv, type ElytraHostImageOptions, type ElytraHostOptions, ElytraImage, type ElytraImageAsset, type ElytraImageProps, type GlobalsConventions, type HostCanvasRouteOptions, type HostComponent, type HostComponents, type LiveContentOptions, type LoadGlobalsOptions, type MaterializeSourcePayloadsInput, type MaterializedSourcePayloads, type NextImagePrimitiveOptions, PACKAGE, type PreviewEvaluation, type PreviewRouteHandlers, type PreviewRouteOptions, REVALIDATE_SIGNATURE_HEADER, type ResolveCanvasPageOptions, type ResolveGlobalsOptions, type ResolvedLink, type ResolvedNavEntry, type ResolvedNavLink, type RevalidateEvaluation, type RevalidatePayload, type RevalidateRouteHandlers, type RevalidateRouteOptions, type SiteGlobals, type SitemapParamsProvider, type SitemapRouteContext, type SitemapSkippedRoute, type SourcePayloadError, type StaticContentData, assembleLiveSource, bodyItemsOf, canvasPageMetadata, canvasSitemapEntries, collectBindingSourceIds, collectionCacheTag, createAssetImageLoader, createBindingResolver, createCanvasRoute, createCanvasSitemap, createContentSnapshot, createElytraHost, createPreviewDisableRoute, createPreviewRoute, createRevalidateRoute, createStaticContentSource, defaultBindingPayloads, defineHostComponents, docCacheTag, elytraHostImage, evaluatePreviewRequest, evaluateRevalidateRequest, firstBlockFullBleed, isSourcePayloadError, loadCachedEntry, loadLiveContent, materializeSourcePayloads, mergeCacheTags, nextCacheTags, nextImagePrimitive, pathFromSlug, projectSweepTag, resolveCanvasPage, resolveGlobals, resolveHostEnv, resolvePayloadToken, revalidatePayloadSchema, routeCacheTag, safeRedirectTarget, scopeCacheTag, signRevalidateBody, sourcePayloadError };

package/dist/index.js

@@ -715,7 +715,8 @@ function canvasSitemapEntries(source, options) {
     }
     return client;
   };
-  const byPath = /* @__PURE__ */ new Map();
+  const byUrl = /* @__PURE__ */ new Map();
+  const byGroup = /* @__PURE__ */ new Map();
   for (const route of routes) {
     const paramNames = paramNamesOf(route.pattern);
     const mount = hierarchyMount(route);
@@ -776,9 +777,12 @@ function canvasSitemapEntries(source, options) {
           );
           continue;
         }
-        const perLocale = byPath.get(path) ?? /* @__PURE__ */ new Map();
-        perLocale.set(locale, originOf(options.baseUrl) + urlPath);
-        byPath.set(path, perLocale);
+        const absolute = originOf(options.baseUrl) + urlPath;
+        const group = result.document ? `${route.id}\0doc\0${result.document.collection}\0${result.document.id}` : `${route.id}\0path\0${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(
@@ -789,14 +793,10 @@ function canvasSitemapEntries(source, options) {
     }
   }
   const entries = [];
-  for (const perLocale of byPath.values()) {
-    const languages = Object.fromEntries(perLocale);
-    for (const url of perLocale.values()) {
-      entries.push({
-        url,
-        ...perLocale.size > 1 ? { alternates: { languages } } : {}
-      });
-    }
+  for (const [url, { group }] of byUrl) {
+    const perLocale = byGroup.get(group);
+    const languages = perLocale && perLocale.size > 1 ? Object.fromEntries(perLocale) : void 0;
+    entries.push({ url, ...languages ? { alternates: { languages } } : {} });
   }
   entries.sort((a, b) => a.url < b.url ? -1 : a.url > b.url ? 1 : 0);
   return { entries, skipped };
@@ -1266,12 +1266,23 @@ function createElytraHost(options) {
   const env = resolveHostEnv(options.env ?? process.env);
   const routes = materializeRoutes(options.routes, options.collections);
   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];
+    throw new Error(
+      `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. Narrowing here is the
+    // one place that widening is paid for; see the option's doc comment and
+    // EC-541 for the runtime check that should back it.
     ...options.components ?? []
   ]);
   const emptySource = createStaticContentSource({
@@ -1341,6 +1352,7 @@ function createElytraHost(options) {
   };
   return {
     contentScope,
+    contentMode,
     env,
     routes,
     components,