@elytracms/next 0.0.85 → 0.0.86

package/dist/index.d.ts

@@ -3,10 +3,11 @@ import { ComponentRegistry, ComponentIssue, ComponentManifest } from '@elytracms
 export { ComponentManifest, PropField, SlotSpec, defineComponent } from '@elytracms/core/component-registry';
 import { ComponentImplementations, ResolveBinding, RelationTarget, DocumentBodyItem } from '@elytracms/core/runtime-renderer';
 export { ComponentImplementations, RenderAsset } from '@elytracms/core/runtime-renderer';
+import { HostComponentEntry } from '@elytracms/core/studio-core';
 import { ResolvePageResult, ResolvedAsset, Perspective, ContentClient, CacheTags, ContentDocumentSource, ResolvedDocument } from '@elytracms/core/content';
 export { Perspective } from '@elytracms/core/content';
 import { LocaleConfig, Locale, RouteRecord, CollectionDef, RedirectRecord } from '@elytracms/core/cms-core';
-export { CmsDocument, CollectionDef, FieldDef, Locale, LocaleConfig, LocaleUrlPath, RedirectRecord, RouteRecord, documentSchema, fallbackHomeRoutes, localeConfigSchema, localeUrlPath, mergeRouteRecords, redirectRecordSchema, routeRecordSchema, splitLocalePath } from '@elytracms/core/cms-core';
+export { CmsDocument, CollectionDef, FieldDef, Locale, LocaleConfig, LocaleRequest, LocaleStrategy, LocaleUrlPath, RedirectRecord, RouteRecord, documentSchema, fallbackHomeRoutes, localeConfigSchema, localeUrlPath, mergeRouteRecords, redirectRecordSchema, resolveLocale, routeRecordSchema, splitLocalePath, textDirection } from '@elytracms/core/cms-core';
 import { ComponentNode } from '@elytracms/core/project-graph';
 export { ComponentNode } from '@elytracms/core/project-graph';
 import { AssetRecord, PersistenceAdapter } from '@elytracms/core/persistence';
@@ -16,12 +17,18 @@ 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
  * real React implementation that renders it (vision AD-2 — project components
  * are real code in the host repo, never generated).
+ *
+ * This is the STRICT shape — the one a hand-authored component module should
+ * export (`export const heroComponent: HostComponent = …`), so the compiler
+ * checks the implementation where it is written. It is assignable to the
+ * config's {@link HostComponentEntry}, which is what {@link defineHostComponents}
+ * accepts, so both hand-built lists and the config's own list register through
+ * the one signature (EC-541).
  */
 interface HostComponent {
     manifest: ComponentManifest;
@@ -36,7 +43,11 @@ interface HostComponent {
 interface HostComponents {
     registry: ComponentRegistry;
     implementations: ComponentImplementations;
-    /** Structural registration issues (duplicate ids, invalid namespaces). */
+    /**
+     * Structural registration issues: the registry's own (duplicate ids, invalid
+     * namespaces, …) plus `invalid-implementation` for an entry whose
+     * `implementation` is not a React component (EC-541).
+     */
     issues: readonly ComponentIssue[];
 }
 interface DefineHostComponentsOptions {
@@ -53,8 +64,29 @@ interface DefineHostComponentsOptions {
  * default. A host implementation registered under a primitive id replaces the
  * default implementation (the manifest of the first registration wins, which
  * is the primitive's — by design, so prop schemas stay canonical).
- */
-declare function defineHostComponents(components?: readonly HostComponent[], options?: DefineHostComponentsOptions): HostComponents;
+ *
+ * Accepts the CONFIG's entry shape (`implementation: unknown`) rather than the
+ * strict {@link HostComponent}: the config declares implementations opaquely,
+ * and EC-539 made `createElytraHost({ ...site })` the contract, so a
+ * compile-time check at this seam was already gone for the recommended path.
+ * The check is RUNTIME instead (EC-541): every implementation is tested with
+ * {@link isComponentImplementation}; a value that is not a component is
+ * recorded as an `invalid-implementation` issue naming the component id and
+ * the received kind, and is NOT put into `implementations` — so the renderer
+ * takes its missing-component path (a visible EC-015 fallback) instead of
+ * crashing the server render on `createElement` ("Element type is invalid")
+ * or, for a string, silently rendering an HTML tag. The manifest still
+ * registers, so the registry's own issues (duplicate id, invalid id) for that
+ * entry are reported alongside.
+ *
+ * One consequence of the `unknown` parameter: an INLINE
+ * `implementation: (props) => …` literal no longer gets `props` contextually
+ * typed (it is `noImplicitAny` under strict). Annotate the parameter, or
+ * author the entry as a {@link HostComponent} — which is the documented shape
+ * anyway. (An overload pair was tried and does not restore it: TypeScript
+ * resolves the context-sensitive literal against the wider overload.)
+ */
+declare function defineHostComponents(components?: readonly HostComponentEntry[], options?: DefineHostComponentsOptions): HostComponents;
 
 /**
  * Binding payloads for the embedded runtime (EC-144): one payload value per
@@ -598,6 +630,13 @@ interface CanvasCacheOptions {
      * Omit only when the emitter also emits unscoped tags (see `cache.ts`).
      */
     scope?: string;
+    /**
+     * Which content world `loadContent` reads — the delivery kit passes its
+     * `contentMode` (`'live' | 'fallback' | 'empty'`), so entries written in one
+     * world can never be served in another (EC-543, see `canvasCacheKey`). A host
+     * driving this helper directly with a single world may omit it.
+     */
+    mode?: string;
 }
 /**
  * What the route helper tells the content loader about the request it is
@@ -1503,13 +1542,16 @@ interface ElytraHostOptions {
      * / `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.
+     * What the widening costs, and where it is paid (EC-541): a list passed HERE
+     * gets no compile-time check that each `implementation` is really a
+     * component. The check is RUNTIME instead — `defineHostComponents` takes the
+     * same `HostComponentEntry` shape (no cast, one signature) and tests every
+     * implementation on registration; a value that is not a component becomes an
+     * `invalid-implementation` issue in `components.issues` and is withheld from
+     * the implementation map, so its nodes render the visible missing-component
+     * fallback rather than crashing the server render. Authoring a component
+     * module as the strict {@link HostComponent} keeps the compile-time check at
+     * the place the implementation is written.
      */
     components?: readonly HostComponentEntry[];
     /**
@@ -1533,8 +1575,10 @@ interface ElytraHostOptions {
      * The no-backend content fallback, used whenever `ELYTRA_CONVEX_URL` +
      * `ELYTRA_PROJECT_ID` are not both set. Default: a build-safe EMPTY source —
      * consumer CI builds green with no backend, and every URL is a clean 404
-     * until content exists. The starter template overrides this with its seeded
-     * in-memory world.
+     * until content exists — in every cache state, not only a cold one, because
+     * the content mode is part of the route's data-cache key (see
+     * {@link ElytraContentMode}). The starter template overrides this with its
+     * seeded in-memory world.
      */
     fallbackContent?: (request: CanvasContentRequest) => Promise<ContentSource>;
     /** Chrome-globals conventions (settings/navigation collection ids, items fields). */
@@ -1560,6 +1604,8 @@ interface HostCanvasRouteOptions {
      * Tagged data cache (instant publish). Default: enabled, scoped to the
      * kit's content scope so the studio's webhook tags match. `false` disables
      * caching entirely; an explicit `CanvasCacheOptions` overrides the scope.
+     * The kit's {@link ElytraHost.contentMode} is always part of the entry key
+     * (EC-543) — an override can replace the scope, never drop the mode.
      */
     cache?: CanvasCacheOptions | false;
 }
@@ -1584,6 +1630,15 @@ interface LoadGlobalsOptions {
  * §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.
+ *
+ * **The mode is also part of the route's data-cache key** (EC-543). A cache
+ * entry outlives the process that wrote it and a hit never runs the loader, so
+ * until 0.0.85 the "clean 404" above held only on a COLD cache: measured, a
+ * `next start` with both env vars blanked and a warm `.next/cache` from a live
+ * run answered `200` with the live world's bytes on every cached URL while
+ * reporting `empty` — the wrong-world failure EC-527 removed, one layer down.
+ * Keyed on the mode (`canvasCacheKey`, `cache.ts`), a world change is a cold
+ * miss per URL, never a stale hit, in either direction.
  */
 type ElytraContentMode = 'live' | 'fallback' | 'empty';
 /** The delivery host handle {@link createElytraHost} yields. */

package/dist/index.js

@@ -6,7 +6,7 @@ import { isBlockSequenceValueShape } from '@elytracms/core/rich-text';
 import { jsx, Fragment } from 'react/jsx-runtime';
 import { cacheTags, isSectionSourceId, parseCmsSourceQueryConfig, listQueryOfCmsConfig, isDocumentHistory, resolvedAsset, createContentClient, createContentContext } from '@elytracms/core/content';
 import { documentKey, splitLocalePath, hierarchyMount, composePath, localeUrlPath, mergeRouteRecords, fallbackHomeRoutes, presentationBodyFields, splitPath, documentSchema, redirectRecordSchema } from '@elytracms/core/cms-core';
-export { documentSchema, fallbackHomeRoutes, localeConfigSchema, localeUrlPath, mergeRouteRecords, redirectRecordSchema, routeRecordSchema, splitLocalePath } from '@elytracms/core/cms-core';
+export { documentSchema, fallbackHomeRoutes, localeConfigSchema, localeUrlPath, mergeRouteRecords, redirectRecordSchema, resolveLocale, routeRecordSchema, splitLocalePath, textDirection } from '@elytracms/core/cms-core';
 import { revalidateTag, unstable_cache } from 'next/cache';
 import { draftMode } from 'next/headers';
 import { redirect, notFound, permanentRedirect } from 'next/navigation';
@@ -15,6 +15,34 @@ import { z } from 'zod';
 export { z } from 'zod';
 import NextImage from 'next/image';
 
+// src/components.ts
+
+// src/is-component.ts
+var EXOTIC_COMPONENT_TYPES = /* @__PURE__ */ new Set([
+  /* @__PURE__ */ Symbol.for("react.memo"),
+  /* @__PURE__ */ Symbol.for("react.forward_ref"),
+  /* @__PURE__ */ Symbol.for("react.lazy")
+]);
+function isComponentImplementation(value) {
+  if (typeof value === "function") return true;
+  if (typeof value !== "object" || value === null) return false;
+  const marker = value.$$typeof;
+  return typeof marker === "symbol" && EXOTIC_COMPONENT_TYPES.has(marker);
+}
+function describeImplementation(value) {
+  if (value === null) return "null";
+  if (value === void 0) return "undefined";
+  if (typeof value === "string") {
+    return `the string ${JSON.stringify(value)} (which React would render silently as an HTML tag)`;
+  }
+  if (Array.isArray(value)) return "an array";
+  if (typeof value === "object") {
+    const marker = value.$$typeof;
+    return typeof marker === "symbol" ? `an object tagged ${String(marker)}` : "a plain object";
+  }
+  return `a ${typeof value}`;
+}
+
 // src/components.ts
 function defineHostComponents(components = [], options = {}) {
   const includeBase = options.includeBasePrimitives !== false;
@@ -25,10 +53,20 @@ function defineHostComponents(components = [], options = {}) {
     const implementation = getImplementation(base.implementations, manifest.id);
     if (implementation) implementations[manifest.id] = implementation;
   }
+  const implementationIssues = [];
   for (const component of components) {
-    implementations[component.manifest.id] = component.implementation;
+    const id = component.manifest.id;
+    if (isComponentImplementation(component.implementation)) {
+      implementations[id] = component.implementation;
+      continue;
+    }
+    implementationIssues.push({
+      code: "invalid-implementation",
+      componentId: id,
+      message: `Component "${id}": implementation is not a React component \u2014 received ${describeImplementation(component.implementation)}; expected a function or class component, or a React.memo / forwardRef / lazy wrapper. The entry is registered without an implementation, so its nodes render the missing-component fallback.`
+    });
   }
-  return { registry, implementations, issues: registry.issues };
+  return { registry, implementations, issues: [...registry.issues, ...implementationIssues] };
 }
 
 // src/payloads.ts
@@ -533,6 +571,9 @@ function nextCacheTags(tags, scope) {
   for (const assetId of tags.assets) all.add(assetCacheTag(assetId, scope));
   return [...all].sort();
 }
+function canvasCacheKey({ scope, mode, url }) {
+  return ["elytra-route", scope ?? "", mode ?? "", url];
+}
 var CacheDiscoveryBail = class extends Error {
   constructor() {
     super("elytra cache discovery bail (never user-visible)");
@@ -582,6 +623,9 @@ function resolveOgImage(value, assets) {
   if (looksLikeUrl(value)) return value;
   return assets.find((asset) => asset.id === value)?.url ?? null;
 }
+function openGraphLocale(locale) {
+  return locale.replace(/-/g, "_");
+}
 function canvasPageMetadata(result, assets = []) {
   const doc = result.document;
   const seoTitle = str(doc?.["seoTitle"]);
@@ -596,11 +640,12 @@ function canvasPageMetadata(result, assets = []) {
   if (title !== null) metadata.title = title;
   if (seoDescription) metadata.description = seoDescription;
   const ogTitle = seoOgTitle ?? title;
-  if (ogTitle !== null || seoDescription || seoOgImage) {
+  if (doc) {
     metadata.openGraph = {
       ...ogTitle !== null ? { title: ogTitle } : {},
       ...seoDescription ? { description: seoDescription } : {},
-      ...seoOgImage ? { images: [{ url: seoOgImage }] } : {}
+      ...seoOgImage ? { images: [{ url: seoOgImage }] } : {},
+      locale: openGraphLocale(result.tags.locale)
     };
   }
   if (seoNoindex) metadata.robots = { index: false };
@@ -630,7 +675,7 @@ function createCanvasRoute(options) {
     const scope = options.cache.scope;
     const entry = await loadCachedEntry(
       nextCacheWrapper,
-      ["elytra-route", scope ?? "", url],
+      canvasCacheKey({ scope, mode: options.cache.mode, url }),
       [projectSweepTag(scope)],
       async () => {
         const outcome = await resolveFresh();
@@ -1287,9 +1332,9 @@ function createElytraHost(options) {
     // 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.
+    // 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 emptySource = createStaticContentSource({
@@ -1336,7 +1381,9 @@ function createElytraHost(options) {
       components,
       // Tag scope = the project id the studio publishes under, so its webhook
       // tags match this site's cached entries.
-      ...cache === false ? {} : { cache: cache ?? { scope: contentScope } },
+      // EC-543: the mode is in the entry key so no world ever reads another's
+      // entries; an explicit override may replace the scope, not drop the mode.
+      ...cache === false ? {} : { cache: { mode: contentMode, ...cache ?? { scope: contentScope } } },
       ...rest
     });
   };