canopycms-next 0.0.67 → 0.0.68-int.101

package/dist/adapter.js

@@ -1,5 +1,5 @@
 import { NextResponse } from 'next/server';
-import { createCanopyRequestHandler, isCanopyBinaryResponse, } from 'canopycms/http';
+import { createCanopyRequestHandler, isCanopyBinaryResponse, workerNotReadyResponse, } from 'canopycms/http';
 import { getErrorMessage, redactCredentials, sanitizeErrorMessage } from 'canopycms/utils/error';
 /**
  * Only uses standard Request methods, so any Request subclass works.
@@ -39,6 +39,8 @@ function toBinaryHeaders(headers) {
         result['Cache-Control'] = headers.cacheControl;
     if (headers.etag)
         result['ETag'] = headers.etag;
+    if (headers.location)
+        result['Location'] = headers.location;
     return result;
 }
 function toNextResponse(response) {
@@ -108,6 +110,9 @@ export const createCanopyCatchAllHandler = (options) => {
             // but this line reaches the server log verbatim, and a git failure message can embed a
             // token-bearing clone URL — the one thing that must not reach a log aggregator.
             console.error('CanopyCMS: Unhandled error in Next.js catch-all handler:', redactCredentials(message));
+            const notReady = workerNotReadyResponse(err);
+            if (notReady)
+                return toNextResponse(notReady);
             return toNextResponse({
                 status: 500,
                 body: { ok: false, status: 500, error: sanitizeErrorMessage(message) },

package/dist/config.cjs

@@ -399,6 +399,7 @@ function withCanopy(nextConfig = {}, options = {}) {
     ])
   ];
   const generateBuildId = nextConfig.generateBuildId ?? (options.staticBuild ? resolveStaticBuildId : void 0);
+  const env = nextConfig.trailingSlash ? { CANOPY_TRAILING_SLASH: "true", ...nextConfig.env } : void 0;
   return {
     ...nextConfig,
     transpilePackages: allPackages,
@@ -409,7 +410,8 @@ function withCanopy(nextConfig = {}, options = {}) {
     // Spread conditionally: emitting `generateBuildId: undefined` would be a key Next has to
     // reason about, where absence is unambiguous.
     ...generateBuildId ? { generateBuildId } : {},
-    ...answerTurbopackGuard ? { turbopack: {} } : {}
+    ...answerTurbopackGuard ? { turbopack: {} } : {},
+    ...env ? { env } : {}
   };
 }
 // Annotate the CommonJS export names for ESM import in node:

package/dist/config.mjs

@@ -363,6 +363,7 @@ function withCanopy(nextConfig = {}, options = {}) {
     ])
   ];
   const generateBuildId = nextConfig.generateBuildId ?? (options.staticBuild ? resolveStaticBuildId : void 0);
+  const env = nextConfig.trailingSlash ? { CANOPY_TRAILING_SLASH: "true", ...nextConfig.env } : void 0;
   return {
     ...nextConfig,
     transpilePackages: allPackages,
@@ -373,7 +374,8 @@ function withCanopy(nextConfig = {}, options = {}) {
     // Spread conditionally: emitting `generateBuildId: undefined` would be a key Next has to
     // reason about, where absence is unambiguous.
     ...generateBuildId ? { generateBuildId } : {},
-    ...answerTurbopackGuard ? { turbopack: {} } : {}
+    ...answerTurbopackGuard ? { turbopack: {} } : {},
+    ...env ? { env } : {}
   };
 }
 export {

package/dist/context-wrapper.d.ts

@@ -1,7 +1,9 @@
 import { type CanopyContext, type CanopyBuildContext, type CanopyServices, type SeoFieldLocation } from 'canopycms/server';
 import type { CanopyConfig, AuthPlugin, FieldConfig } from 'canopycms';
 import type { Metadata, MetadataRoute } from 'next';
+import type { ReactElement } from 'react';
 import { createCanopyCatchAllHandler } from './adapter.js';
+import { type CreatePreviewPageOptions, type PreviewPageProps } from './preview-page.js';
 import { type EntryToMetadataOptions, type GenerateContentSitemapOptions, type GenerateContentStaticParamsOptions } from './static.js';
 /**
  * Merge a context-wide default SEO field location (`createNextCanopyContext({ seo })`) with a
@@ -101,8 +103,8 @@ export interface NextCanopyContextResult {
      *
      * At build time this reads filesystem-direct; at request time it uses the branch-aware,
      * **ACL-enforced** runtime context, so entries the current user cannot read are omitted.
-     * Note it takes no `branch` option — see `CanopyContext['listEntries']` for the
-     * base-branch pinning caveat in prod.
+     * Pass the preview iframe's `?branch=` as `branch` on an index page so a content
+     * branch's entries show in preview — see `CanopyContext['listEntries']`.
      */
     listEntries: CanopyContext['listEntries'];
     /**
@@ -132,6 +134,23 @@ export interface NextCanopyContextResult {
      * (see that function's doc); pass `fields`/`group` on a given call to override just that call.
      */
     entryToMetadata: (entryData: unknown, options?: EntryToMetadataOptions) => Metadata;
+    /**
+     * The page for the preview route the editor's `previewPrefix` names, for a site whose public
+     * pages are a static export. Mount it as `app/<prefix>/[[...path]]/page.server.tsx`, so only the
+     * CMS build has it:
+     *
+     * ```tsx
+     * export default createPreviewPage({ views: { post: PostPreview, doc: DocPreview } })
+     * ```
+     *
+     * Each view is made by `withCanopyPreview` (`canopycms-next/preview`) in a `'use client'` module.
+     * It renders each entry from the `?branch=` the editor names, through `views[entryType]` with
+     * the live draft. Reads are request-scoped and ACL-checked, and an anonymous request or anything
+     * not readable is a 404.
+     * A view that needs more server reads is `previewView({ view, load })`: `load` runs after the
+     * entry is read and its result arrives as the view's `extras` prop.
+     */
+    createPreviewPage: (options: CreatePreviewPageOptions) => (props: PreviewPageProps) => Promise<ReactElement>;
     /** API catch-all route handler */
     handler: ReturnType<typeof createCanopyCatchAllHandler>;
     /** Underlying services (rarely needed directly) */

package/dist/context-wrapper.js

@@ -5,6 +5,7 @@ import { createCanopyContext, isBuildMode, startDevContentWatcher, createCanopyS
 import { assertAuthPluginAllowedForMode } from 'canopycms/auth';
 import { CachingAuthPlugin, FileBasedAuthCache } from 'canopycms/auth/cache';
 import { createCanopyCatchAllHandler } from './adapter.js';
+import { createPreviewPageFor, } from './preview-page.js';
 import { collectStaticParams, entryToMetadata as entryToMetadataCore, generateContentSitemap, } from './static.js';
 /**
  * Merge a context-wide default SEO field location (`createNextCanopyContext({ seo })`) with a
@@ -175,8 +176,12 @@ export async function createNextCanopyContext(options) {
     //
     // No base-branch context resolution needed here: request-time content reads
     // (buildContentTree/listEntries/read) already provision the base/active branch via
-    // loadOrCreateBranchContext (see context.ts's resolveSchemaContext); build-time reads never
+    // loadOrCreateBranchContext (see context.ts's resolveListingSource); build-time reads never
     // provision, they read the checkout.
+    //
+    // Failures propagate to the page's error boundary and never degrade to a user: a
+    // RemoteNotReadyError (the worker has not created the remote yet) names the cause in the
+    // server log, and only an HTTP route can answer it with a 503.
     const extractUser = async () => {
         const headersList = await headers();
         const authResult = await authPlugin.authenticate(headersList);
@@ -267,6 +272,7 @@ export async function createNextCanopyContext(options) {
         generateContentStaticParams,
         generateContentSitemap: boundGenerateContentSitemap,
         entryToMetadata: boundEntryToMetadata,
+        createPreviewPage: (previewOptions) => createPreviewPageFor(getCanopy, previewOptions, options.config.deployedAs),
         handler,
         services,
     };

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 export { createCanopyCatchAllHandler, wrapNextRequest, type CanopyNextOptions } from './adapter.js';
 export { createNextCanopyContext, type NextCanopyOptions, type NextCanopyContextResult, } from './context-wrapper.js';
+export { previewView, type CreatePreviewPageOptions, type PreviewEntry, type PreviewLoadContext, type PreviewPageProps, type PreviewViewWithLoader, } from './preview-page.js';
 export { collectStaticParams, generateContentSitemap, entryToMetadata, type GenerateContentStaticParamsOptions, type GenerateContentSitemapOptions, type EntryToMetadataOptions, type SitemapExtraUrl, } from './static.js';
 export { createMockAuthPlugin, createRejectingAuthPlugin } from './test-utils.js';

package/dist/index.js

@@ -1,4 +1,5 @@
 export { createCanopyCatchAllHandler, wrapNextRequest } from './adapter.js';
 export { createNextCanopyContext, } from './context-wrapper.js';
+export { previewView, } from './preview-page.js';
 export { collectStaticParams, generateContentSitemap, entryToMetadata, } from './static.js';
 export { createMockAuthPlugin, createRejectingAuthPlugin } from './test-utils.js';

package/dist/preview-page.d.ts

@@ -0,0 +1,94 @@
+import type { ReactElement, ReactNode } from 'react';
+import type { CanopyConfig } from 'canopycms';
+import type { CanopyContext } from 'canopycms/server';
+import type { CanopyPreviewProps } from './preview.js';
+type ReadEntry = NonNullable<Awaited<ReturnType<CanopyContext['readByUrlPath']>>>;
+/**
+ * The entry a `load` receives. It carries no `meta.physicalPath`, so a loader that returns its
+ * whole `entry` cannot send the server's filesystem layout to the browser.
+ */
+export interface PreviewEntry {
+    data: unknown;
+    path: string;
+    entryType: string;
+    entryId?: ReadEntry['meta']['entryId'];
+}
+/** What a `load` receives. */
+export interface PreviewLoadContext {
+    /** The entry the route is rendering, as read from the requested branch. */
+    entry: PreviewEntry;
+    /** The request-scoped context the entry was read through: authenticated and ACL-checked. */
+    canopy: CanopyContext;
+    /** The `?branch=` the editor named, to pass on to further reads. */
+    branch: string | undefined;
+}
+/**
+ * A view and the server loader that feeds its `extras` prop. Make one with `previewView`.
+ *
+ * `load` runs on the server, once per request, after the entry is read and its view found, so an
+ * entry type with no view is a 404 without running it. It may throw, or call `notFound()`: either
+ * rejects the page rather than rendering.
+ *
+ * Its result reaches the browser like any RSC prop, so it must be RSC-serializable: plain data
+ * or React elements. A server-rendered element such as `<RelatedPosts />` is fine, which lets a
+ * view reuse a server component for a section that need not update live. The result is a
+ * snapshot of the request and does not follow the editor's live draft; only `data` does.
+ */
+export interface PreviewViewWithLoader<X> {
+    view: (props: CanopyPreviewProps<never, X>) => ReactNode;
+    load: (ctx: PreviewLoadContext) => X | Promise<X>;
+}
+/**
+ * The form `views` holds, with `X` erased. `view` takes `extras?: never`, so a view of any `X`
+ * is assignable (its parameter is only wider), and `load` returns `unknown`, so any loader is
+ * too. That drops the check that `load`'s result is what `view` expects, which `previewView`
+ * restores where each pair is written.
+ */
+interface ErasedPreviewViewWithLoader {
+    view: (props: CanopyPreviewProps<never, never>) => ReactNode;
+    load: (ctx: PreviewLoadContext) => unknown;
+}
+type PreviewView = (props: CanopyPreviewProps<never>) => ReactNode;
+/**
+ * Pairs a view with its loader, so TypeScript checks that `load`'s result is what the view's
+ * `extras` prop expects. A record of views cannot infer a distinct `X` per key, so this identity
+ * function infers it for each entry on its own.
+ */
+export declare function previewView<X>(entry: PreviewViewWithLoader<X>): PreviewViewWithLoader<X>;
+export interface CreatePreviewPageOptions {
+    /**
+     * The view for each entry type the preview route serves, keyed by entry type name, each made by
+     * `withCanopyPreview` (`canopycms-next/preview`) in a `'use client'` module, or a
+     * `previewView({ view, load })` pair when the view needs more than the entry. An entry whose
+     * type has no view is a 404.
+     */
+    views: Record<string, PreviewView | ErasedPreviewViewWithLoader>;
+    /**
+     * Editor origin to trust, for an editor on another origin. Defaults to the page's own. A
+     * request without the viewer's session is a 404, and a `SameSite=Lax` session cookie reaches a
+     * framed page only from an editor on the same site, so a cross-site editor previews nothing.
+     */
+    editorOrigin?: string;
+}
+/** The props Next passes a `[[...path]]` page. */
+export interface PreviewPageProps {
+    params: Promise<{
+        path?: string[];
+    }>;
+    searchParams: Promise<Record<string, string | string[] | undefined>>;
+}
+/**
+ * The page for a `[[...path]]` route mounted at `editor.previewPrefix`: it reads the entry at
+ * the route's path from the `?branch=` the editor names and renders its view.
+ *
+ * The read goes through the request-scoped `getCanopy()`, never the build context: it is
+ * authenticated and ACL-checked, and a branch other than the active one is only loaded, never
+ * created. An anonymous request, a missing, unreadable or malformed branch, and a path no entry
+ * publishes, are all a 404, so a hidden branch looks the same as a missing one.
+ *
+ * On a `deployedAs: 'static'` deployment every request is a 404: reads there skip access checks,
+ * so the route would show any branch to anyone.
+ * @internal Exported for tests.
+ */
+export declare function createPreviewPageFor(getCanopy: () => Promise<CanopyContext>, options: CreatePreviewPageOptions, deployedAs?: CanopyConfig['deployedAs']): (props: PreviewPageProps) => Promise<ReactElement>;
+export {};

package/dist/preview-page.js

@@ -0,0 +1,68 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { notFound } from 'next/navigation';
+/**
+ * Pairs a view with its loader, so TypeScript checks that `load`'s result is what the view's
+ * `extras` prop expects. A record of views cannot infer a distinct `X` per key, so this identity
+ * function infers it for each entry on its own.
+ */
+export function previewView(entry) {
+    return entry;
+}
+function hasLoader(entry) {
+    return (typeof entry === 'object' &&
+        entry !== null &&
+        Object.prototype.hasOwnProperty.call(entry, 'load'));
+}
+/**
+ * The page for a `[[...path]]` route mounted at `editor.previewPrefix`: it reads the entry at
+ * the route's path from the `?branch=` the editor names and renders its view.
+ *
+ * The read goes through the request-scoped `getCanopy()`, never the build context: it is
+ * authenticated and ACL-checked, and a branch other than the active one is only loaded, never
+ * created. An anonymous request, a missing, unreadable or malformed branch, and a path no entry
+ * publishes, are all a 404, so a hidden branch looks the same as a missing one.
+ *
+ * On a `deployedAs: 'static'` deployment every request is a 404: reads there skip access checks,
+ * so the route would show any branch to anyone.
+ * @internal Exported for tests.
+ */
+export function createPreviewPageFor(getCanopy, options, deployedAs = 'server') {
+    return async function CanopyPreviewPage({ params, searchParams }) {
+        if (deployedAs === 'static')
+            notFound();
+        const [{ path = [] }, query] = await Promise.all([params, searchParams]);
+        const branch = query.branch;
+        if (Array.isArray(branch))
+            notFound();
+        const canopy = await getCanopy();
+        // Branch ACLs can grant an anonymous user the base branch, and this route is deployed like the
+        // editor's routes (canopycms-cdk's `attachTo` `previewPrefix`), outside any site-wide gate.
+        if (canopy.user.type === 'anonymous')
+            notFound();
+        const result = await canopy.readByUrlPath(`/${path.join('/')}`, { branch });
+        if (!result)
+            notFound();
+        const { entryType } = result.meta;
+        const viewEntry = Object.prototype.hasOwnProperty.call(options.views, entryType)
+            ? options.views[entryType]
+            : undefined;
+        if (!viewEntry)
+            notFound();
+        if (!hasLoader(viewEntry)) {
+            const View = viewEntry;
+            return _jsx(View, { initialData: result.data, editorOrigin: options.editorOrigin });
+        }
+        const { meta } = result;
+        const entry = {
+            data: result.data,
+            path: result.path,
+            entryType: meta.entryType,
+            entryId: meta.entryId,
+        };
+        const extras = await viewEntry.load({ entry, canopy, branch });
+        // The record erases `view` to `extras?: never`, so it cannot check `load`'s result against the
+        // view; `previewView` does, where a pair is written.
+        const View = viewEntry.view;
+        return _jsx(View, { initialData: result.data, editorOrigin: options.editorOrigin, extras: extras });
+    };
+}

package/dist/preview.d.ts

@@ -0,0 +1,32 @@
+import type { ReactElement, ReactNode } from 'react';
+import { useCanopyPreview } from 'canopycms/preview';
+/** What a preview view renders from: the editor's live draft, plus `useCanopyPreview`'s helpers. */
+export type CanopyPreviewViewProps<T> = ReturnType<typeof useCanopyPreview<T>>;
+/** The props of a view wrapped by `withCanopyPreview`. */
+export interface CanopyPreviewProps<T, X = undefined> {
+    /** The saved entry data, rendered until the editor sends a draft. */
+    initialData: T;
+    /** Editor origin to trust, for an editor on another origin. Defaults to this page's own. */
+    editorOrigin?: string;
+    /**
+     * What the route's `load` returned (see `previewView`), handed to the view untouched as its
+     * `extras` prop. Absent on a public page and for a view with no loader.
+     */
+    extras?: X;
+}
+/**
+ * Wraps a view so it renders the editor's live draft of `initialData`, through `useCanopyPreview`;
+ * outside an editor frame it renders `initialData` unchanged.
+ *
+ * Call it in your own `'use client'` module and pass the result to `createPreviewPage`'s `views`,
+ * or render it on a public page. The wrapping lives in your module, not in `createPreviewPage`,
+ * because Next ships every client module a page's server code imports: one imported by the
+ * context would put the preview bridge in every page that reads content.
+ *
+ * The returned type is a call signature rather than `ComponentType`, whose `propTypes` would make
+ * a view for one content type unassignable to a map of views for many. It returns `ReactElement`,
+ * which JSX accepts on every supported TypeScript, where `ReactNode` needs `JSX.ElementType`.
+ */
+export declare function withCanopyPreview<T, X = undefined>(View: (props: CanopyPreviewViewProps<T> & {
+    extras: X | undefined;
+}) => ReactNode): (props: CanopyPreviewProps<T, X>) => ReactElement;

package/dist/preview.js

@@ -0,0 +1,24 @@
+'use client';
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useCanopyPreview } from 'canopycms/preview';
+/**
+ * Wraps a view so it renders the editor's live draft of `initialData`, through `useCanopyPreview`;
+ * outside an editor frame it renders `initialData` unchanged.
+ *
+ * Call it in your own `'use client'` module and pass the result to `createPreviewPage`'s `views`,
+ * or render it on a public page. The wrapping lives in your module, not in `createPreviewPage`,
+ * because Next ships every client module a page's server code imports: one imported by the
+ * context would put the preview bridge in every page that reads content.
+ *
+ * The returned type is a call signature rather than `ComponentType`, whose `propTypes` would make
+ * a view for one content type unassignable to a map of views for many. It returns `ReactElement`,
+ * which JSX accepts on every supported TypeScript, where `ReactNode` needs `JSX.ElementType`.
+ */
+export function withCanopyPreview(View) {
+    return function CanopyPreview({ initialData, editorOrigin, extras }) {
+        const preview = useCanopyPreview({ initialData, editorOrigin });
+        // `extras` is a prop of its own, never spread into the hook's result, so it cannot shadow
+        // `data` or `fieldProps`.
+        return _jsx(View, { ...preview, extras: extras });
+    };
+}

package/dist/with-canopy.d.ts

@@ -40,6 +40,7 @@ export interface WithCanopyOptions {
  *   (kept under `experimental` on Next 13/14 or legacy spellings; your own includes stay), so a
  *   Turbopack `output: 'standalone'` server can load sharp — Next's tracing misses that library
  *   for sharp 0.35 (doesn't fix webpack builds); warns if the directory or version can't be found.
+ * - `trailingSlash: true` sets `env.CANOPY_TRAILING_SLASH`, so the editor's requests skip Next's 308.
  * - On Next 16+, sets `turbopack: {}` when your config has neither `turbopack` nor `webpack` and
  *   the Next version can be read — Next 16 defaults to Turbopack and exits when a config exports
  *   `webpack` (the React aliases above add one) with no `turbopack` key; a `turbopack` you set is

package/dist/with-canopy.js

@@ -337,6 +337,7 @@ function sharpTracingConfig(nextConfig, options) {
  *   (kept under `experimental` on Next 13/14 or legacy spellings; your own includes stay), so a
  *   Turbopack `output: 'standalone'` server can load sharp — Next's tracing misses that library
  *   for sharp 0.35 (doesn't fix webpack builds); warns if the directory or version can't be found.
+ * - `trailingSlash: true` sets `env.CANOPY_TRAILING_SLASH`, so the editor's requests skip Next's 308.
  * - On Next 16+, sets `turbopack: {}` when your config has neither `turbopack` nor `webpack` and
  *   the Next version can be read — Next 16 defaults to Turbopack and exits when a config exports
  *   `webpack` (the React aliases above add one) with no `turbopack` key; a `turbopack` you set is
@@ -448,6 +449,11 @@ export function withCanopy(nextConfig = {}, options = {}) {
     // verbatim (`next/dist/build/generate-build-id.js`) — which is what makes a hex tree hash usable
     // as a build id at all. Do not "helpfully" route this through the fallback.
     const generateBuildId = nextConfig.generateBuildId ?? (options.staticBuild ? resolveStaticBuildId : undefined);
+    // Next substitutes `env` into every bundle at build time, where the API client and the editor's
+    // preview URLs read it (`readTrailingSlashEnv` in canopycms's `utils/url-prefix.ts`).
+    const env = nextConfig.trailingSlash
+        ? { CANOPY_TRAILING_SLASH: 'true', ...nextConfig.env }
+        : undefined;
     return {
         ...nextConfig,
         transpilePackages: allPackages,
@@ -459,5 +465,6 @@ export function withCanopy(nextConfig = {}, options = {}) {
         // reason about, where absence is unambiguous.
         ...(generateBuildId ? { generateBuildId } : {}),
         ...(answerTurbopackGuard ? { turbopack: {} } : {}),
+        ...(env ? { env } : {}),
     };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "canopycms-next",
-  "version": "0.0.67",
+  "version": "0.0.68-int.101",
   "description": "Next.js adapter for CanopyCMS",
   "license": "MIT",
   "repository": {
@@ -23,6 +23,11 @@
       "import": "./dist/client.js",
       "require": "./dist/client.js"
     },
+    "./preview": {
+      "types": "./dist/preview.d.ts",
+      "import": "./dist/preview.js",
+      "require": "./dist/preview.js"
+    },
     "./config": {
       "types": "./dist/config.d.ts",
       "import": "./dist/config.mjs",
@@ -38,7 +43,7 @@
   "peerDependencies": {
     "next": "^13.5.7 || ^14.2.25 || ^15.5.21 || >=16.0.0 <16.2.0 || >=16.3.0 <17.0.0",
     "react": "^18.0.0 || ^19.0.0",
-    "canopycms": "0.0.67"
+    "canopycms": "0.0.68-int.101"
   },
   "devDependencies": {
     "@types/node": "^22.9.0",
@@ -48,7 +53,7 @@
     "react": "^18.3.1",
     "typescript": "^5.6.3",
     "vitest": "^4.1.0",
-    "canopycms": "0.0.67"
+    "canopycms": "0.0.68-int.101"
   },
   "scripts": {
     "build": "rm -rf dist && tsc -p tsconfig.build.json && node ../../scripts/add-js-extensions.mjs dist && esbuild src/config.ts --bundle --platform=node --packages=external --external:next --format=cjs --outfile=dist/config.cjs && esbuild src/config.ts --bundle --platform=node --packages=external --external:next --format=esm --outfile=dist/config.mjs",