canopycms-next 0.0.67 → 0.0.68-int.94

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.
@@ -108,6 +108,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/client.d.ts

@@ -1,3 +1,5 @@
+import { type ReactElement, type ReactNode } from 'react';
+import { useCanopyPreview } from 'canopycms/client';
 import type { CanopyClientConfig, CustomFieldRenderers } from 'canopycms/client';
 /**
  * Next.js-specific wrapper for CanopyEditorPage that automatically reads
@@ -24,3 +26,26 @@ import type { CanopyClientConfig, CustomFieldRenderers } from 'canopycms/client'
  * ```
  */
 export declare const NextCanopyEditorPage: (config: CanopyClientConfig, customRenderers?: CustomFieldRenderers) => () => import("react/jsx-runtime").JSX.Element;
+/** 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> {
+    /** 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;
+}
+/**
+ * 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 editor 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>(View: (props: CanopyPreviewViewProps<T>) => ReactNode): (props: CanopyPreviewProps<T>) => ReactElement;

package/dist/client.js

@@ -2,7 +2,7 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { Suspense } from 'react';
 import { useSearchParams } from 'next/navigation';
-import { CanopyEditorPage } from 'canopycms/client';
+import { CanopyEditorPage, useCanopyPreview } from 'canopycms/client';
 /**
  * Next.js-specific wrapper for CanopyEditorPage that automatically reads
  * URL search params (branch, entry) using Next.js's useSearchParams hook.
@@ -44,3 +44,22 @@ export const NextCanopyEditorPage = (config, customRenderers) => {
         return (_jsx(Suspense, { fallback: null, children: _jsx(EditorWithSearchParams, {}) }));
     };
 };
+/**
+ * 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 editor 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 }) {
+        const preview = useCanopyPreview({ initialData, editorOrigin });
+        return _jsx(View, { ...preview });
+    };
+}

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,20 @@ 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/client`) 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 anything not readable is a 404.
+     */
+    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 type { CreatePreviewPageOptions, PreviewPageProps } 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/preview-page.d.ts

@@ -0,0 +1,35 @@
+import type { ReactElement, ReactNode } from 'react';
+import type { CanopyConfig } from 'canopycms';
+import type { CanopyContext } from 'canopycms/server';
+import type { CanopyPreviewProps } from './client.js';
+export interface CreatePreviewPageOptions {
+    /**
+     * The view for each entry type the preview route serves, keyed by entry type name, each made by
+     * `withCanopyPreview` (`canopycms-next/client`) in a `'use client'` module. An entry whose type
+     * has no view is a 404.
+     */
+    views: Record<string, (props: CanopyPreviewProps<never>) => ReactNode>;
+    /** Editor origin to trust, for an editor on another origin. Defaults to the page's own. */
+    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. 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>;

package/dist/preview-page.js

@@ -0,0 +1,36 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { notFound } from 'next/navigation';
+/**
+ * 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. 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();
+        const result = await canopy.readByUrlPath(`/${path.join('/')}`, { branch });
+        if (!result)
+            notFound();
+        const { entryType } = result.meta;
+        const View = Object.prototype.hasOwnProperty.call(options.views, entryType)
+            ? options.views[entryType]
+            : undefined;
+        if (!View)
+            notFound();
+        return _jsx(View, { initialData: result.data, editorOrigin: options.editorOrigin });
+    };
+}

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.94",
   "description": "Next.js adapter for CanopyCMS",
   "license": "MIT",
   "repository": {
@@ -38,7 +38,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.94"
   },
   "devDependencies": {
     "@types/node": "^22.9.0",
@@ -48,7 +48,7 @@
     "react": "^18.3.1",
     "typescript": "^5.6.3",
     "vitest": "^4.1.0",
-    "canopycms": "0.0.67"
+    "canopycms": "0.0.68-int.94"
   },
   "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",