canopycms-next 0.0.67-int.90 → 0.0.67-int.91

package/dist/adapter.d.ts

@@ -1,23 +1,15 @@
 import { type CanopyHandlerOptions, type CanopyRequest } from 'canopycms/http';
 /**
- * Options for creating a Canopy Next.js handler.
  * Same as core CanopyHandlerOptions - re-exported for convenience.
  */
 export type CanopyNextOptions = CanopyHandlerOptions;
 /**
- * Wrap a standard Request (or NextRequest) to implement the CanopyRequest interface.
  * Only uses standard Request methods, so any Request subclass works.
  */
 export declare function wrapNextRequest(req: Request): CanopyRequest;
 /**
  * Catch-all Next.js handler for a single API route (e.g., /api/canopycms/[...canopycms]).
  *
- * This is a thin adapter that:
- * 1. Converts NextRequest to CanopyRequest
- * 2. Extracts path segments from Next.js params
- * 3. Delegates to the core handler
- * 4. Converts CanopyResponse to NextResponse
- *
  * @example
  * ```ts
  * // app/api/canopycms/[...canopycms]/route.ts

package/dist/adapter.js

@@ -2,7 +2,6 @@ import { NextResponse } from 'next/server';
 import { createCanopyRequestHandler, isCanopyBinaryResponse, } from 'canopycms/http';
 import { getErrorMessage, redactCredentials, sanitizeErrorMessage } from 'canopycms/utils/error';
 /**
- * Wrap a standard Request (or NextRequest) to implement the CanopyRequest interface.
  * Only uses standard Request methods, so any Request subclass works.
  */
 export function wrapNextRequest(req) {
@@ -30,10 +29,6 @@ export function wrapNextRequest(req) {
         },
     };
 }
-/**
- * Map a CanopyBinaryResponse's framework-agnostic header fields onto the
- * real HTTP header names, omitting any that weren't set.
- */
 function toBinaryHeaders(headers) {
     const result = {};
     if (headers.contentType)
@@ -46,17 +41,12 @@ function toBinaryHeaders(headers) {
         result['ETag'] = headers.etag;
     return result;
 }
-/**
- * Convert a CanopyResponse (or CanopyBinaryResponse) to a NextResponse.
- */
 function toNextResponse(response) {
     if (isCanopyBinaryResponse(response)) {
-        // A Uint8Array can be backed by an arbitrary ArrayBufferLike (e.g. a
-        // Node Buffer), which doesn't structurally satisfy the DOM lib's
-        // BodyInit/ArrayBufferView (specifically ArrayBuffer-backed). Copying
-        // through the typed-array constructor yields a plain ArrayBuffer-backed
-        // view so this type-checks without an unsafe cast; ReadableStream
-        // bodies pass through unchanged.
+        // A Uint8Array can be backed by an arbitrary ArrayBufferLike (e.g. a Node Buffer), which
+        // doesn't structurally satisfy the DOM lib's BodyInit/ArrayBufferView. Copying through the
+        // typed-array constructor yields a plain ArrayBuffer-backed view that type-checks without an
+        // unsafe cast; ReadableStream bodies pass through unchanged.
         const body = response.body instanceof Uint8Array ? new Uint8Array(response.body) : response.body;
         return new NextResponse(body, {
             status: response.status,
@@ -69,7 +59,6 @@ function toNextResponse(response) {
     });
 }
 /**
- * Extract path segments from Next.js catch-all route params.
  * Handles both Next.js 14 (direct object) and Next.js 15 (Promise) params.
  */
 async function extractPathSegments(ctx) {
@@ -81,12 +70,6 @@ async function extractPathSegments(ctx) {
 /**
  * Catch-all Next.js handler for a single API route (e.g., /api/canopycms/[...canopycms]).
  *
- * This is a thin adapter that:
- * 1. Converts NextRequest to CanopyRequest
- * 2. Extracts path segments from Next.js params
- * 3. Delegates to the core handler
- * 4. Converts CanopyResponse to NextResponse
- *
  * @example
  * ```ts
  * // app/api/canopycms/[...canopycms]/route.ts
@@ -116,17 +99,14 @@ export const createCanopyCatchAllHandler = (options) => {
             return toNextResponse(response);
         }
         catch (err) {
-            // Defense-in-depth (API-C1): coreHandler already guards itself with a
-            // top-level try/catch, but this adapter also wraps request conversion
-            // (wrapNextRequest/extractPathSegments/toNextResponse) so a failure there
-            // can never escape as Next's generic unhandled-error 500, which would
-            // break the uniform { ok, status, error } envelope the editor expects.
+            // Defense-in-depth (API-C1): coreHandler already guards itself with a top-level try/catch,
+            // but this adapter also wraps request conversion, so a failure there can never escape as
+            // Next's generic unhandled-error 500, which would break the uniform { ok, status, error }
+            // envelope the editor expects.
             const message = getErrorMessage(err);
-            // Redacted before logging, not just before responding. The HTTP body was
-            // already sanitized, but this line went to the server log verbatim -- and
-            // a git failure message can embed a token-bearing clone URL, which is the
-            // one thing that must not reach a log aggregator. Every failure surface
-            // in the worker already redacts; this was the outlier.
+            // Redacted before logging, not just before responding: the HTTP body is already sanitized,
+            // 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));
             return toNextResponse({
                 status: 500,

package/dist/client.d.ts

@@ -3,13 +3,11 @@ import type { CanopyClientConfig, CustomFieldRenderers } from 'canopycms/client'
  * Next.js-specific wrapper for CanopyEditorPage that automatically reads
  * URL search params (branch, entry) using Next.js's useSearchParams hook.
  *
- * @param customRenderers Optional per-field-type render overrides, forwarded
- * to `CanopyEditorPage`. Forwarded rather than dropped for a specific reason:
- * Next is the primary target, so this wrapper is the entrypoint adopters
- * actually import (it is what the README's Quick Start scaffolds). Accepting
- * the argument only on the core `CanopyEditorPage` made the extension point
- * unreachable from the path every adopter uses, which is an extension point
- * in name only.
+ * @param customRenderers Optional per-field-type render overrides, forwarded to
+ * `CanopyEditorPage`. Forwarded (not dropped) because Next is the primary target: this wrapper
+ * is the entrypoint every adopter imports (the README's Quick Start scaffolds it), so accepting
+ * the argument only on core `CanopyEditorPage` would make the extension point unreachable from
+ * the path adopters actually use.
  *
  * @example
  * ```tsx

package/dist/client.js

@@ -7,13 +7,11 @@ import { CanopyEditorPage } from 'canopycms/client';
  * Next.js-specific wrapper for CanopyEditorPage that automatically reads
  * URL search params (branch, entry) using Next.js's useSearchParams hook.
  *
- * @param customRenderers Optional per-field-type render overrides, forwarded
- * to `CanopyEditorPage`. Forwarded rather than dropped for a specific reason:
- * Next is the primary target, so this wrapper is the entrypoint adopters
- * actually import (it is what the README's Quick Start scaffolds). Accepting
- * the argument only on the core `CanopyEditorPage` made the extension point
- * unreachable from the path every adopter uses, which is an extension point
- * in name only.
+ * @param customRenderers Optional per-field-type render overrides, forwarded to
+ * `CanopyEditorPage`. Forwarded (not dropped) because Next is the primary target: this wrapper
+ * is the entrypoint every adopter imports (the README's Quick Start scaffolds it), so accepting
+ * the argument only on core `CanopyEditorPage` would make the extension point unreachable from
+ * the path adopters actually use.
  *
  * @example
  * ```tsx
@@ -31,10 +29,9 @@ import { CanopyEditorPage } from 'canopycms/client';
  */
 export const NextCanopyEditorPage = (config, customRenderers) => {
     const CorePage = CanopyEditorPage(config, customRenderers);
-    // Reads URL search params. Next.js 15 requires useSearchParams() consumers to
-    // sit under a <Suspense> boundary, otherwise static rendering errors with
-    // "useSearchParams() should be wrapped in a suspense boundary". We provide the
-    // boundary here so adopters don't have to wrap their /edit page themselves.
+    // Next.js 15 requires useSearchParams() consumers to sit under a <Suspense> boundary, or static
+    // rendering errors with "useSearchParams() should be wrapped in a suspense boundary" — provided
+    // here so adopters don't have to wrap their /edit page themselves.
     function EditorWithSearchParams() {
         const urlSearchParams = useSearchParams();
         const searchParams = {

package/dist/context-wrapper.d.ts

@@ -21,6 +21,7 @@ import { type EntryToMetadataOptions, type GenerateContentSitemapOptions, type G
  * keys, so a caller who omits them still produces an object whose `fields`/`group` are present but
  * `undefined`, and spreading that would silently clobber the default. Checking each key explicitly
  * avoids that trap. Exported for direct unit testing.
+ * @internal Exported for tests.
  */
 export declare function mergeSeoFieldLocation(contextDefault: SeoFieldLocation | undefined, callOverride: SeoFieldLocation | undefined): SeoFieldLocation;
 export interface NextCanopyOptions {
@@ -29,13 +30,11 @@ export interface NextCanopyOptions {
     authPlugin?: AuthPlugin;
     entrySchemaRegistry: Record<string, readonly FieldConfig[]>;
     /**
-     * Where the SEO fields live (`fields` name overrides, and/or a nested `group`). Set once here
-     * and it is shared by BOTH the returned `generateContentSitemap`'s `noindex` exclusion and the
-     * returned `entryToMetadata`'s field extraction, so the two surfaces cannot independently forget
-     * or mis-set it and drift apart — see `mergeSeoFieldLocation`. Omit for the flat (inline-group)
-     * convention, which is the default on both the schema side (`defineSeoFieldGroup()`) and here.
-     * A per-call `seo`/`fields`/`group` option on either helper still overrides this default for
-     * that one call.
+     * Where the SEO fields live (`fields` name overrides, and/or a nested `group`) — shared by both
+     * `generateContentSitemap`'s `noindex` exclusion and `entryToMetadata`'s field extraction; see
+     * `mergeSeoFieldLocation` for why one shared default matters. Omit for the flat (inline-group)
+     * convention, the default on both the schema side (`defineSeoFieldGroup()`) and here. A per-call
+     * `seo`/`fields`/`group` option on either helper overrides this default for that one call.
      */
     seo?: SeoFieldLocation;
 }
@@ -55,6 +54,7 @@ export interface NextCanopyOptions {
  * that ambiguity is gone (generateStaticParams is build-only; request-time build-context use is the
  * footgun). Why not on `static` deployments: they skip ACLs everywhere by design, so there's nothing
  * to leak. `CANOPY_BUILD_MODE=true` marks non-Next static generation as build phase.
+ * @internal Exported for tests.
  */
 export declare function guardBuildContext(buildCtx: CanopyBuildContext, config: CanopyConfig): CanopyBuildContext;
 export interface NextCanopyContextResult {
@@ -125,13 +125,11 @@ export interface NextCanopyContextResult {
     generateContentSitemap: (options: GenerateContentSitemapOptions) => Promise<MetadataRoute.Sitemap>;
     /**
      * Map an entry's SEO fields onto a Next `Metadata` for `generateMetadata`. Re-exposed here so a
-     * page module has one CanopyCMS import (your `lib/canopy.ts`) rather than two.
+     * page module has one CanopyCMS import (your `lib/canopy.ts`) rather than two. Pure mapping —
+     * touches no context.
      *
-     * Reads the SAME SEO field location as `generateContentSitemap` above by default (the
-     * `createNextCanopyContext({ seo })` value); the two are bound from one context-wide default so
-     * they cannot silently disagree about where `noindex` (or a renamed field) lives. Pass
-     * `fields`/`group` on a given call to override just that call. This is a pure
-     * mapping and touches no context.
+     * Shares its SEO field location with `generateContentSitemap` above via `mergeSeoFieldLocation`
+     * (see that function's doc); pass `fields`/`group` on a given call to override just that call.
      */
     entryToMetadata: (entryData: unknown, options?: EntryToMetadataOptions) => Metadata;
     /** API catch-all route handler */
@@ -140,12 +138,8 @@ export interface NextCanopyContextResult {
     services: CanopyServices;
 }
 /**
- * Create Next.js-specific wrapper around core context.
- * Adds React cache() for per-request memoization and API handler.
- * This function is async because it needs to load .collection.json meta files.
- *
- * In prod/dev mode, if the provided authPlugin implements verifyTokenOnly(),
- * it is automatically wrapped with CachingAuthPlugin + FileBasedAuthCache so that
- * auth works without network access (Lambda in prod, local in dev). The cache is populated by the worker daemon.
+ * Create the Next.js-specific wrapper around the core context: React `cache()` per-request
+ * memoization plus the API handler. Async because it loads .collection.json meta files (see the
+ * authPlugin auto-wrap below for how prod/dev sets up networkless auth).
  */
 export declare function createNextCanopyContext(options: NextCanopyOptions): Promise<NextCanopyContextResult>;

package/dist/context-wrapper.js

@@ -24,6 +24,7 @@ import { collectStaticParams, entryToMetadata as entryToMetadataCore, generateCo
  * keys, so a caller who omits them still produces an object whose `fields`/`group` are present but
  * `undefined`, and spreading that would silently clobber the default. Checking each key explicitly
  * avoids that trap. Exported for direct unit testing.
+ * @internal Exported for tests.
  */
 export function mergeSeoFieldLocation(contextDefault, callOverride) {
     const merged = { ...contextDefault };
@@ -35,7 +36,6 @@ export function mergeSeoFieldLocation(contextDefault, callOverride) {
 }
 let warnedStaticMode = false;
 /**
- * Stub auth plugin for static deployments where no real auth is needed.
  * Returns unauthenticated for all requests — API routes will return 401.
  *
  * `verifiesCredentials: true` is set here even though this plugin verifies nothing: it is an
@@ -78,6 +78,7 @@ const staticDeployAuthPlugin = {
  * that ambiguity is gone (generateStaticParams is build-only; request-time build-context use is the
  * footgun). Why not on `static` deployments: they skip ACLs everywhere by design, so there's nothing
  * to leak. `CANOPY_BUILD_MODE=true` marks non-Next static generation as build phase.
+ * @internal Exported for tests.
  */
 export function guardBuildContext(buildCtx, config) {
     const assertBuildPhase = (method) => {
@@ -98,8 +99,8 @@ export function guardBuildContext(buildCtx, config) {
             assertBuildPhase('listEntries');
             return buildCtx.listEntries(options);
         },
-        // Return types inferred from the core build context (which now carries
-        // meta.physicalPath); the returned object is validated against CanopyBuildContext.
+        // Return types inferred from the core build context, which carries meta.physicalPath;
+        // the returned object is validated against CanopyBuildContext.
         read: (input) => {
             assertBuildPhase('read');
             return buildCtx.read(input);
@@ -111,16 +112,11 @@ export function guardBuildContext(buildCtx, config) {
     };
 }
 /**
- * Create Next.js-specific wrapper around core context.
- * Adds React cache() for per-request memoization and API handler.
- * This function is async because it needs to load .collection.json meta files.
- *
- * In prod/dev mode, if the provided authPlugin implements verifyTokenOnly(),
- * it is automatically wrapped with CachingAuthPlugin + FileBasedAuthCache so that
- * auth works without network access (Lambda in prod, local in dev). The cache is populated by the worker daemon.
+ * Create the Next.js-specific wrapper around the core context: React `cache()` per-request
+ * memoization plus the API handler. Async because it loads .collection.json meta files (see the
+ * authPlugin auto-wrap below for how prod/dev sets up networkless auth).
  */
 export async function createNextCanopyContext(options) {
-    // Fail fast: authPlugin is required for server deployments
     if (options.config.deployedAs !== 'static' && !options.authPlugin) {
         throw new Error('CanopyCMS: authPlugin is required when deployedAs is "server". ' +
             'Set deployedAs: "static" in your canopy config, or provide an authPlugin.');
@@ -136,10 +132,10 @@ export async function createNextCanopyContext(options) {
             'Do not set deployedAs: "static" in a server deployment.');
         warnedStaticMode = true;
     }
-    // Resolve the auth plugin: auto-wrap with CachingAuthPlugin for prod/dev when
-    // the plugin supports token-only verification. This keeps auth networkless (required for
-    // Lambda in prod, consistent in dev) without exposing caching internals to adopters.
-    // For static deployments, use the stub that returns 401 for all requests.
+    // Auto-wrap with CachingAuthPlugin + FileBasedAuthCache in prod/dev when the plugin implements
+    // verifyTokenOnly(), so auth stays networkless (required for Lambda in prod, consistent in dev)
+    // without exposing caching internals to adopters; the cache is populated by the worker daemon.
+    // Static deployments use the stub above, which always returns 401.
     const { mode } = options.config;
     const authPlugin = (() => {
         if (!options.authPlugin)
@@ -156,7 +152,6 @@ export async function createNextCanopyContext(options) {
         }
         return options.authPlugin;
     })();
-    // Create services ONCE at initialization
     const services = await createCanopyServices(options.config, {
         entrySchemaRegistry: options.entrySchemaRegistry,
     });
@@ -172,22 +167,16 @@ export async function createNextCanopyContext(options) {
     if (options.config.mode === 'dev' && !isBuildMode()) {
         startDevContentWatcher(services, { mode: options.config.dev?.contentSync });
     }
-    // User extractor: passes Next.js headers to auth plugin, resolves internal
-    // groups, applies authorization. Delegates to the shared
-    // "authenticate -> load internal groups -> merge" pipeline
-    // (resolveCanopyUser, in canopycms core) so this stays in lockstep with
-    // http/handler.ts's API-layer equivalent rather than re-implementing it —
-    // a previous copy here loaded groups from the base branch content clone
-    // (via loadBranchContext), which nothing in the product ever writes
-    // groups.json into, so group-based privileges never took effect.
+    // Passes Next.js headers to the auth plugin, then resolves internal groups and authorization
+    // through the shared "authenticate -> load internal groups -> merge" pipeline (resolveCanopyUser,
+    // in canopycms core), keeping this in lockstep with http/handler.ts's API-layer equivalent rather
+    // than re-implementing it. Must not source groups from a base-branch content clone — nothing in
+    // the product writes groups.json there, so group-based privileges depend on this shared pipeline.
     //
-    // No base-branch context resolution here (unlike the previous copy):
-    // that call existed only to source groups.json from the (wrong) content
-    // branch. Actual request-time content reads (buildContentTree/listEntries/
-    // read) already provision the base/active branch themselves via
-    // loadOrCreateBranchContext (see context.ts's resolveSchemaContext; build-time
-    // reads never provision, they read the checkout), so dropping it here removes
-    // a redundant per-request EFS round-trip rather than losing provisioning.
+    // 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
+    // provision, they read the checkout.
     const extractUser = async () => {
         const headersList = await headers();
         const authResult = await authPlugin.authenticate(headersList);
@@ -197,12 +186,10 @@ export async function createNextCanopyContext(options) {
             bootstrapAdminIds: services.bootstrapAdminIds,
         });
     };
-    // Create core context with pre-created services (framework-agnostic)
     const coreContext = createCanopyContext({
         services,
         extractUser,
     });
-    // Wrap with React cache() for per-request caching
     const getCanopy = cache(() => {
         return coreContext.getContext();
     });
@@ -228,7 +215,7 @@ export async function createNextCanopyContext(options) {
         return buildContextPromise;
     };
     // Phase-selecting helpers: build context during static generation, branch-aware runtime at request
-    // time. Lets page code resolve content without hand-picking the admin build context (see item #5).
+    // time. Lets page code resolve content without hand-picking the admin build context.
     const readByUrlPath = async (urlPath, opts) => {
         const ctx = isBuildMode() ? await getCanopyForBuild() : await getCanopy();
         return ctx.readByUrlPath(urlPath, opts);
@@ -251,9 +238,7 @@ export async function createNextCanopyContext(options) {
     // static export, and on a prod `server` deployment guardBuildContext throws if it is reached at
     // request time. Binding it here keeps the admin context out of the route module either way.
     //
-    // Both this and boundEntryToMetadata below feed options.seo (the context-wide default set on
-    // createNextCanopyContext) through the SAME mergeSeoFieldLocation call, so the noindex exclusion
-    // here and entryToMetadata's noindex/field read cannot independently drift out of sync.
+    // SEO field location is shared with boundEntryToMetadata via mergeSeoFieldLocation — see its doc.
     const boundGenerateContentSitemap = async (callOptions) => {
         return generateContentSitemap(await getCanopyForBuild(), {
             ...callOptions,
@@ -267,7 +252,6 @@ export async function createNextCanopyContext(options) {
         });
         return entryToMetadataCore(entryData, { ...callOptions, ...seoLocation });
     };
-    // Create API handler using same services
     const handler = createCanopyCatchAllHandler({
         ...options,
         authPlugin,

package/dist/sharp-tracing.d.ts

@@ -16,7 +16,12 @@ export interface SharpTracingInput {
     lockfileRoot?: 'outermost' | 'closest';
 }
 export interface SharpTracingResult {
-    /** Project-relative POSIX globs, one per native-library `lib/` directory found. */
+    /**
+     * Project-relative POSIX globs, one per native-library `lib/` directory found. Turbopack matches
+     * includes in unanchored "contains" mode and follows symlinked directories rather than confining
+     * its walk to the include's own directory, so this costs roughly 5 s of compile time on one
+     * measured build.
+     */
     includes: string[];
     /** Why nothing was found. Set exactly when `includes` is empty. */
     problem?: string;
@@ -28,6 +33,7 @@ export interface SharpTracingResult {
  * of the packages this module needs defeat it:
  * - a `canopycms` published without a `require` condition throws ERR_PACKAGE_PATH_NOT_EXPORTED;
  * - sharp exports no `./package.json` at all.
+ * @internal Exported for tests.
  */
 export declare function findInstalledPackage(fromDir: string, name: string): string | null;
 /** The major version of the `next` installed for `projectDir`, or null if it cannot be read. */
@@ -46,6 +52,7 @@ export declare function hasNextConfig(dir: string): boolean;
  *
  * Next resolves a relative configured root against the working directory; `withCanopy` only calls
  * this when that directory is the project dir.
+ * @internal Exported for tests.
  */
 export declare function resolveTracingRoot(input: SharpTracingInput): string;
 /**

package/dist/sharp-tracing.js

@@ -1,57 +1,30 @@
 /**
  * Finds sharp's libvips shared library so `withCanopy` can add it to Next.js output file tracing.
  *
- * **The gap.** sharp loads libvips with `dlopen`, through its native binding's rpath. Nothing
- * `require`s the library, so a tracer that follows imports never sees it. Next's JS tracer
- * (`next/dist/compiled/@vercel/nft`) covers that with a sharp-specific handler, but the handler only
- * fires on a path ending in `sharp/lib/index.js`, which is sharp 0.34's entry point. sharp 0.35
- * ships `dist/index.{cjs,mjs}` instead.
+ * **The gap.** sharp loads libvips with `dlopen` through its native binding's rpath, so a tracer
+ * that follows imports never sees it. Next's JS tracer has a sharp-specific handler, but it only
+ * fires on sharp 0.34's entry point `sharp/lib/index.js`; sharp 0.35 ships `dist/index.{cjs,mjs}`
+ * instead, so it's missed — on a Next 16.1.7 Turbopack standalone build this leaves
+ * `lib/libvips-cpp.so.*` untraced, and the built server fails to load sharp with ERR_DLOPEN_FAILED
+ * (`.claude/future-tasks/resolved/cms-image-build-epic.md`, "The tracer misses the `.so`"). A
+ * webpack build under pnpm fails differently: Next 15.5.21's webpack bundles sharp's JS into a
+ * server chunk, so the bundled copy cannot reach its native binding regardless of this include
+ * (root cause in `.claude/future-tasks/webpack-standalone-sharp-bundled.md`). An npm install and
+ * Next 16's `next build --webpack` have not been checked. Where the JS tracer does trace the
+ * library itself, this include merges into one Set rather than duplicating it (upstream:
+ * next.js#97973, sharp #4567/#4543 — fixed there, this module goes).
  *
- * Measured on a Next 16.1.7 Turbopack `output: 'standalone'` build (`.claude/future-tasks/`
- * `cms-image-build-epic.md`, "The tracer misses the `.so`"): the route traces list libvips's
- * `package.json` and the binding's rpath symlink, but not `lib/libvips-cpp.so.*`. Every load of
- * sharp in the resulting server then fails with ERR_DLOPEN_FAILED.
- *
- * A webpack build under pnpm has a different problem. On Next 15.5.21, Next's webpack externals
- * resolution bundles sharp's JavaScript into a server chunk, so no sharp 0.35 package is traced and
- * the bundled copy cannot reach its native binding, whether or not this include ships libvips (root
- * cause in `.claude/future-tasks/webpack-standalone-sharp-bundled.md`). An npm install and Next
- * 16's `next build --webpack` have not been checked. Where Next's JS tracer does trace the library
- * itself, the include adds no duplicate: it merges traced and included files into one `Set`
- * (`next/dist/build/collect-build-traces.js:505` in 16.1.7).
- *
- * Upstream: https://github.com/vercel/next.js/issues/97973 (open). On sharp's side, see
- * https://github.com/lovell/sharp/issues/4567 and https://github.com/lovell/sharp/issues/4543.
- * Once a Next release traces the library itself, this module and its call in `withCanopy` should go.
- *
- * **Finding the directory.** Packages are located by walking up the `node_modules` hierarchy, the
- * way a bundler resolves a bare specifier, never by globbing one package manager's layout. The walk:
- * - start from the `canopycms` the project resolves;
- * - find that copy's `sharp`, and also any `sharp` the project resolves directly;
- * - find each `@img/sharp-libvips-*` optional dependency, from sharp and from each installed native
- *   binding (the binding's rpath looks for libvips beside the binding, so that is the copy it loads);
- * - an installed binding that lists no libvips package has to carry its native library itself, so
- *   take the binding instead (sharp 0.35.3's win32-x64 and win32-arm64 bindings list none, and ship
- *   `libvips-42.dll` and `libvips-cpp-8.18.3.dll` in their own `lib/`);
- * - take each package's real `lib/` directory.
- *
- * **Real paths, not symlinks.** The includes name real directories. Under pnpm, the binding's rpath
- * reaches libvips through a sibling symlink whose target is that real directory, and the images
- * this was verified on load the library from there.
- *
- * **What the include does NOT cover.** Under pnpm, the binding reaches the library only through its
- * sibling symlink `.pnpm/@img+sharp-<platform>@<version>/node_modules/@img/sharp-libvips-<platform>`.
- * (Checked with `otool` on sharp 0.35.3's darwin-arm64 binding: none of its other rpath entries
- * resolves in a pnpm layout.) Next 16.1.7's Turbopack traces that symlink already, and the
- * standalone copy recreates it. If a Next upgrade stops tracing it, the library is present but
- * unreachable. Only a smoke test that loads sharp inside the built image would notice.
- *
- * **Cost.** Turbopack matches includes in "contains" mode (`crates/next-api/src/nft_json.rs:312` at
- * v16.1.7), which leaves the pattern unanchored (`turbo-tasks-fs/src/globset.rs:104-114`). Its
- * directory walk is therefore not confined to the directory an include names, and it follows
- * symlinked directories (`read_glob.rs:87-99`). Measured on one Next 16.1.7 app's standalone build,
- * the include added about 5 s of compile time (12.8 s to 17.9 s, mean of three runs; recorded in
- * `.claude/future-tasks/upstream-next-sharp-tracing-recheck.md`).
+ * **Locating the directory.** Walk up the `node_modules` hierarchy the way a bundler resolves a
+ * bare specifier, never glob one package manager's layout: from the `canopycms` the project
+ * resolves (and any `sharp` it resolves directly), find each `@img/sharp-libvips-*` dependency of
+ * sharp and of each installed native binding — a binding's rpath looks for libvips beside itself,
+ * so that sibling copy is the one it loads. A binding with no libvips dependency carries its own
+ * native library instead (true of sharp 0.35.3's win32 bindings). Each package's real `lib/`
+ * directory becomes one include — never the `.pnpm` symlink beside it, which is the only path a
+ * binding's rpath actually resolves in a pnpm layout (checked with `otool`), and which Next
+ * 16.1.7's Turbopack already traces (the standalone build recreates it). If a future Next stops
+ * tracing that symlink, the library stays present but unreachable — only a smoke test that loads
+ * sharp inside the built image would notice.
  */
 import { readFileSync, realpathSync, statSync } from 'node:fs';
 import path from 'node:path';
@@ -102,8 +75,6 @@ function messageOf(err) {
     return String(err);
 }
 /**
- * Whether `candidate` is a regular file.
- *
  * Any failed stat answers false instead of throwing: a missing path, a race with a delete, or a
  * permission error. `hasNextConfig` calls this outside any `try`, and it runs inside the adopter's
  * `next.config`.
@@ -172,6 +143,7 @@ function nodeModulesLookupDirs(fromDir) {
  * of the packages this module needs defeat it:
  * - a `canopycms` published without a `require` condition throws ERR_PACKAGE_PATH_NOT_EXPORTED;
  * - sharp exports no `./package.json` at all.
+ * @internal Exported for tests.
  */
 export function findInstalledPackage(fromDir, name) {
     for (const lookupDir of nodeModulesLookupDirs(fromDir)) {
@@ -221,6 +193,7 @@ function findLockFileUpwards(startDir, names) {
  *
  * Next resolves a relative configured root against the working directory; `withCanopy` only calls
  * this when that directory is the project dir.
+ * @internal Exported for tests.
  */
 export function resolveTracingRoot(input) {
     const configured = input.outputFileTracingRoot || input.turbopackRoot;

package/dist/static.d.ts

@@ -55,28 +55,19 @@ type SitemapItem = MetadataRoute.Sitemap[number];
  * `generateContentSitemap` applies `isNoindexEntry` and a default `lastModified` only while
  * walking real entries; this list is appended afterwards and passes through both:
  *
- * - **No `noindex` gate.** Nothing checks the SEO flag for an extra URL, because there is no
- *   entry data to check. If you are using `extraUrls` to re-advertise a real entry under a
- *   different path (the usual reason — an entry whose structural `urlPath` no route serves),
- *   you are responsible for not listing it when that entry is marked `noindex`. Marking the
- *   entry does not remove the extra URL.
+ * - **No `noindex` gate.** There is no entry data to check it against — if you use `extraUrls`
+ *   to re-advertise a real entry under a different path, you are responsible for not listing it
+ *   when that entry is `noindex`; marking the entry does not remove the extra URL.
  * - **No `lastModified` fallback.** The per-entry branch defaults to `entry.updatedAt`; here,
- *   omitting `lastModified` means the URL simply ships without a date.
- *
- * Both are easy to get wrong in exactly the same direction, and both used to be unavoidable:
- * `extraUrls` was once the only way to advertise a real entry at a different URL, so every such
- * use re-derived `noindex` and `lastModified` by hand — this repo's own reference app among them,
- * and it got `lastModified` wrong.
- *
- * It is no longer the only way, so it should no longer be that way:
- *
- * 1. **Model the entry so its natural `urlPath` IS the URL you serve.** An `index` entry collapses
- *    onto its collection's path, and a root `index` entry onto `/`. Nothing to keep in sync. This
- *    is what the reference app does now, which is why its sitemap passes neither option.
- * 2. **Failing that, use `pathFor`** (see `GenerateContentSitemapOptions`), which overrides the
- *    URL while keeping the entry inside the walk — so the `noindex` gate, the `lastModified`
- *    default and `priority` all still apply.
- * 3. **Keep `extraUrls` for what its name says:** URLs with no entry behind them at all.
+ *   omitting `lastModified` means the URL ships with no date at all.
+ *
+ * Prefer, in order: (1) model the entry so its natural `urlPath` IS the URL you serve — an
+ * `index` entry collapses onto its collection's path, a root `index` onto `/`, nothing to keep
+ * in sync; (2) failing that, use `pathFor` (see `GenerateContentSitemapOptions`), which overrides
+ * the URL while keeping the entry inside the walk, so the `noindex` gate, `lastModified` default
+ * and `priority` all still apply; (3) reach for `extraUrls` only for URLs with no entry behind
+ * them at all — re-deriving `noindex`/`lastModified` by hand for a REAL entry is easy to get
+ * wrong in both places at once.
  */
 export interface SitemapExtraUrl {
     /** Site-relative path ('/blog') or an absolute URL. Trailing-slash rules apply to the former. */
@@ -126,44 +117,27 @@ export interface GenerateContentSitemapOptions {
     /**
      * Override the URL an entry is advertised at, keeping it INSIDE the entry walk.
      *
-     * Return a path to advertise the entry at instead of its structural `urlPath`; return `null`
-     * (or `undefined`) to leave it alone.
-     *
-     * **`null` means "no opinion", not "drop it".** So the obvious shape — handle the one entry
-     * type you care about, return `null` for the rest — advertises every other entry at its own
-     * path rather than silently emitting a one-URL sitemap. Dropping an entry stays `exclude`'s
-     * job, and keeping the two separate is the whole reason for this choice: a `pathFor` whose
-     * natural-looking callback silently omitted everything else would re-introduce exactly the
-     * quietly-short sitemap this module exists to prevent.
-     *
-     * This is the principled alternative to reaching for `extraUrls` to reroute a REAL entry.
-     * Because the entry stays in the walk, it keeps the `isNoindexEntry` gate, the `updatedAt`
-     * `lastModified` default and its `priority` automatically — all three of which an `extraUrls`
-     * entry makes you re-derive by hand, and get wrong independently (see {@link SitemapExtraUrl}).
-     *
-     * **It changes what is ADVERTISED, not what is BUILT.** `generateContentStaticParams` still
-     * enumerates the entry at its structural path, so the URL returned here must be one your app
-     * actually routes — otherwise you have advertised a 404, the same hazard `extraUrls` carries.
-     *
-     * Return a **site-relative path**. The value is trimmed, and an empty or off-site return (an
-     * absolute `https://…` or a protocol-relative `//host/…`) throws rather than being emitted:
-     * the first silently claims `/`, and the second lands in the sitemap as a non-absolute `<loc>`,
-     * which invalidates the whole file. `extraUrls` is where an off-origin URL is legitimate.
+     * Return a path to advertise the entry at instead of its structural `urlPath`; `null`/`undefined`
+     * means "no opinion", not "drop it" — a callback that returns `null` for entries it doesn't
+     * handle must still advertise them at their own path, or it silently reintroduces the
+     * quietly-short sitemap this module exists to prevent. Dropping stays `exclude`'s job.
      *
-     * Reach for it only when the URL is fixed by something OUTSIDE the content tree: published URLs
-     * you cannot change, or a route prefix that deliberately differs from the content layout. When
-     * you control the modelling, model the entry so its natural `urlPath` is already the URL you
-     * serve — an `index` entry collapses onto its collection's path, and a root `index` entry onto
-     * `/` — which needs no option at all. That ordering is not advice we only give: it is what the
-     * reference app in this repo does, which is why its sitemap passes neither this nor `extraUrls`.
+     * Because the entry stays in the walk, it keeps the `isNoindexEntry` gate and the `updatedAt`
+     * `lastModified`/`priority` defaults that `extraUrls` makes you re-derive by hand (see
+     * {@link SitemapExtraUrl}). It changes what is ADVERTISED, not what is BUILT:
+     * `generateContentStaticParams` still enumerates the entry at its structural path, so the URL
+     * returned here must be one your app actually routes, or you have advertised a 404.
      *
-     * Runs AFTER the `noindex` and `exclude` gates (a dropped entry needs no URL). `exclude`,
-     * `lastModified` and `priority` receive the entry as ENUMERATED, so `entry.urlPath` there is
-     * always the structural path and never your override — branch on the entry, not on the URL.
+     * Return a **site-relative path**; it is trimmed. An empty or off-site return (absolute
+     * `https://…` or protocol-relative `//host/…`) throws: an empty string would silently claim `/`,
+     * and a protocol-relative value lands as a non-absolute `<loc>` that invalidates the whole file
+     * (`extraUrls` is where an off-origin URL belongs). Use this only when the URL is fixed by
+     * something OUTSIDE the content tree; otherwise model the entry so its `urlPath` is that URL.
      *
-     * Two entries rewritten onto one URL are NOT caught by the build's `assertNoDuplicateUrlPaths`
-     * guard, which runs on the raw listing and never sees these rewrites; `dedupeSitemapItems`
-     * warns and keeps the first.
+     * Runs AFTER the `noindex`/`exclude` gates; `exclude`, `lastModified` and `priority` see the
+     * entry as ENUMERATED, so branch on the entry, not on `entry.urlPath` (always structural there).
+     * A collision this creates is NOT caught by the build's `assertNoDuplicateUrlPaths` guard, which
+     * runs before this rewrite; `dedupeSitemapItems` warns and keeps the first instead.
      *
      * @example
      * // Content lives under content/articles/*, but this site has always published /blog/*.

package/dist/static.js

@@ -109,8 +109,6 @@ export async function generateContentSitemap(buildCtx, options) {
     return dedupeSitemapItems(items).sort((a, b) => a.url === root ? -1 : b.url === root ? 1 : a.url.localeCompare(b.url));
 }
 /**
- * Resolve the path an entry is advertised at, applying the caller's `pathFor` override.
- *
  * `null`/`undefined` mean "no opinion" and keep the entry's own `urlPath` — see the `pathFor`
  * doc for why that is not "drop it".
  *
@@ -128,9 +126,8 @@ export async function generateContentSitemap(buildCtx, options) {
  *   reject the whole file for it. Refused whatever the origin — including one matching `siteUrl` —
  *   so the rule is "return a site-relative path" with no host comparison to get subtly wrong.
  *
- * The returned path is TRIMMED. Surrounding whitespace is never intended and survives into the
- * URL otherwise (`' /blog'` → `<siteUrl>/ /blog`) — which this function would previously detect
- * while checking for emptiness and then hand back untrimmed anyway.
+ * The returned path is TRIMMED before use: surrounding whitespace is never intended and would
+ * otherwise survive into the URL (`' /blog'` → `<siteUrl>/ /blog`).
  */
 function resolveEntrySitemapPath(entry, pathFor) {
     if (!pathFor)
@@ -157,8 +154,6 @@ function resolveEntrySitemapPath(entry, pathFor) {
     return trimmed;
 }
 /**
- * Drop duplicate `<loc>` entries, keeping the first occurrence and warning about each collision.
- *
  * A duplicate URL isn't fatal to a crawler, but it usually means two URLs are unintentionally
  * sharing one `<loc>` — an index entry collapsing onto a sibling's path, two `urlPath`s that only
  * differ by case (`urlPath` is lowercased — see `content-listing.ts`), an `extraUrls` path

package/dist/test-utils.d.ts

@@ -1,11 +1,7 @@
 import type { AuthPlugin } from 'canopycms/auth';
 import type { AuthenticatedUser } from 'canopycms';
 /**
- * Create a mock AuthPlugin for testing.
  * Returns a valid user by default (as Admin), or can be configured to return specific users.
  */
 export declare const createMockAuthPlugin: (user?: AuthenticatedUser) => AuthPlugin;
-/**
- * Create a mock AuthPlugin that rejects all authentication.
- */
 export declare const createRejectingAuthPlugin: (error?: string) => AuthPlugin;

package/dist/test-utils.js

@@ -1,6 +1,5 @@
 const ADMINS = 'Admins';
 /**
- * Create a mock AuthPlugin for testing.
  * Returns a valid user by default (as Admin), or can be configured to return specific users.
  */
 export const createMockAuthPlugin = (user = {
@@ -23,9 +22,6 @@ export const createMockAuthPlugin = (user = {
     getGroupMetadata: async () => null,
     listGroups: async () => [],
 });
-/**
- * Create a mock AuthPlugin that rejects all authentication.
- */
 export const createRejectingAuthPlugin = (error = 'Unauthorized') => ({
     authenticate: async () => ({ success: false, error }),
     searchUsers: async () => [],

package/dist/with-canopy.d.ts

@@ -23,58 +23,32 @@ export interface WithCanopyOptions {
     staticBuild?: boolean;
 }
 /**
- * Wrap your Next.js config to set up module transpilation and React
- * resolution for CanopyCMS packages.
+ * Wrap your Next.js config for CanopyCMS: module transpilation and React resolution. Always
+ * recommended — replaces manual `transpilePackages` config and is harmless without aliases.
  *
  * **What it does:**
- * - Auto-detects installed Canopy packages and adds them to `transpilePackages`
- *   (they export raw TypeScript). Only packages found in your node_modules are
- *   added, so you don't need to worry about optional packages you haven't installed.
- * - Adds `server.ts`/`server.tsx` (or, when `staticBuild: true`, `static.ts`/`static.tsx`)
- *   to `pageExtensions` for dual-build support. CMS-only files (e.g., `route.server.ts`)
- *   are included in dev/CMS builds but excluded when `staticBuild: true` is set, in favor
- *   of the static-export-only page variants (e.g. `page.static.tsx`).
- * - Resolves React to a single copy from your project root, preventing
- *   dual-instance crashes when using `file:` symlinks for local development
- * - With `staticBuild: true`, honors `CANOPY_BUILD_ID` as Next's build id (Next's default is
- *   random, which puts two builds of one source tree in different `_next/static/` directories).
- *   Unset, or on a non-static build, Next's default is used unchanged.
- * - Outside a static export, adds sharp's libvips directory to `outputFileTracingIncludes['/**']`,
- *   so a Turbopack `output: 'standalone'` server can load sharp. Next's file tracing can miss that
- *   library for sharp 0.35. This does not fix a webpack build: under pnpm, Next 15.5.21 bundles
- *   sharp into a server chunk that cannot load its native binding.
- *   - The key follows your Next version (under `experimental` on 13 and 14) and any legacy
- *     `experimental` spelling you already use.
- *   - Your own includes are kept.
- *   - A standalone build warns if the directory cannot be found, or if the Next version cannot be
- *     read and the entry went under the top-level key.
- * - On Next 16 and later, sets `turbopack: {}` when your config has neither `turbopack` nor
- *   `webpack` and the installed Next version can be read (an unreadable version gets no key).
- *   Next 16 builds and runs `next dev` with Turbopack by default, and exits when the
- *   config has a `webpack` function (the React aliases above add one) but no `turbopack` config.
- *   A `turbopack` you already set, `turbopack: {}` included, is kept as it is.
- *
- * **When you need this:**
- * - Always recommended — it replaces manual `transpilePackages` configuration
- *   and is harmless when React aliases aren't strictly needed.
- *
- * **When React aliases matter:**
- * - When consuming canopycms packages via `file:` references or `npm link`
- *   during local development. Without the aliases, the bundler follows
- *   symlinks and may resolve a second copy of React from the linked
- *   package's node_modules, causing "Invalid hook call" crashes.
- * - When installing from npm (not symlinked), the aliases are still safe
- *   — they simply resolve to the same React your project already uses.
+ * - Adds installed Canopy packages to `transpilePackages` (they export raw TypeScript), auto-detected
+ *   so an optional package you haven't installed is never added.
+ * - Adds `server.ts`/`server.tsx` (or, with `staticBuild: true`, `static.ts`/`static.tsx`) to
+ *   `pageExtensions`, so CMS-only files build in dev/CMS and static-only variants build instead.
+ * - Resolves React to one copy from your project root, avoiding "Invalid hook call" crashes when
+ *   canopycms packages are linked via `file:`/`npm link` (the bundler would otherwise follow the
+ *   symlink to a second React copy); a no-op otherwise, since it resolves to the React you already use.
+ * - With `staticBuild: true`, honors `CANOPY_BUILD_ID` as a reproducible build id (Next
+ *   defaults to a random one); unset, or off a static build, Next's default stands.
+ * - Outside a static export, adds sharp's libvips directory to `outputFileTracingIncludes['/**']`
+ *   (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.
+ * - 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
+ *   left alone.
  *
  * @example
  * ```ts
- * // next.config.ts
  * import { withCanopy } from 'canopycms-next/config'
- *
- * export default withCanopy({
- *   reactStrictMode: true,
- *   // ...your config
- * })
+ * export default withCanopy({ reactStrictMode: true })
  * ```
  */
 export declare function withCanopy(nextConfig?: NextConfig, options?: WithCanopyOptions): NextConfig;

package/dist/with-canopy.js

@@ -226,8 +226,6 @@ function unknownNextVersionWarning(projectDir) {
         'experimental.outputFileTracingIncludes.');
 }
 /**
- * Whether the warning has fired in this module instance.
- *
  * A Turbopack build evaluates the config in the main process and again in a worker thread with its
  * own module registry (`next/dist/build/turbopack-build/index.js:26` and `impl.js:209` in 16.1.7).
  * So "once" means once per process or thread, not once per build.
@@ -322,58 +320,32 @@ function sharpTracingConfig(nextConfig, options) {
     return { experimental: legacyExperimental };
 }
 /**
- * Wrap your Next.js config to set up module transpilation and React
- * resolution for CanopyCMS packages.
+ * Wrap your Next.js config for CanopyCMS: module transpilation and React resolution. Always
+ * recommended — replaces manual `transpilePackages` config and is harmless without aliases.
  *
  * **What it does:**
- * - Auto-detects installed Canopy packages and adds them to `transpilePackages`
- *   (they export raw TypeScript). Only packages found in your node_modules are
- *   added, so you don't need to worry about optional packages you haven't installed.
- * - Adds `server.ts`/`server.tsx` (or, when `staticBuild: true`, `static.ts`/`static.tsx`)
- *   to `pageExtensions` for dual-build support. CMS-only files (e.g., `route.server.ts`)
- *   are included in dev/CMS builds but excluded when `staticBuild: true` is set, in favor
- *   of the static-export-only page variants (e.g. `page.static.tsx`).
- * - Resolves React to a single copy from your project root, preventing
- *   dual-instance crashes when using `file:` symlinks for local development
- * - With `staticBuild: true`, honors `CANOPY_BUILD_ID` as Next's build id (Next's default is
- *   random, which puts two builds of one source tree in different `_next/static/` directories).
- *   Unset, or on a non-static build, Next's default is used unchanged.
- * - Outside a static export, adds sharp's libvips directory to `outputFileTracingIncludes['/**']`,
- *   so a Turbopack `output: 'standalone'` server can load sharp. Next's file tracing can miss that
- *   library for sharp 0.35. This does not fix a webpack build: under pnpm, Next 15.5.21 bundles
- *   sharp into a server chunk that cannot load its native binding.
- *   - The key follows your Next version (under `experimental` on 13 and 14) and any legacy
- *     `experimental` spelling you already use.
- *   - Your own includes are kept.
- *   - A standalone build warns if the directory cannot be found, or if the Next version cannot be
- *     read and the entry went under the top-level key.
- * - On Next 16 and later, sets `turbopack: {}` when your config has neither `turbopack` nor
- *   `webpack` and the installed Next version can be read (an unreadable version gets no key).
- *   Next 16 builds and runs `next dev` with Turbopack by default, and exits when the
- *   config has a `webpack` function (the React aliases above add one) but no `turbopack` config.
- *   A `turbopack` you already set, `turbopack: {}` included, is kept as it is.
- *
- * **When you need this:**
- * - Always recommended — it replaces manual `transpilePackages` configuration
- *   and is harmless when React aliases aren't strictly needed.
- *
- * **When React aliases matter:**
- * - When consuming canopycms packages via `file:` references or `npm link`
- *   during local development. Without the aliases, the bundler follows
- *   symlinks and may resolve a second copy of React from the linked
- *   package's node_modules, causing "Invalid hook call" crashes.
- * - When installing from npm (not symlinked), the aliases are still safe
- *   — they simply resolve to the same React your project already uses.
+ * - Adds installed Canopy packages to `transpilePackages` (they export raw TypeScript), auto-detected
+ *   so an optional package you haven't installed is never added.
+ * - Adds `server.ts`/`server.tsx` (or, with `staticBuild: true`, `static.ts`/`static.tsx`) to
+ *   `pageExtensions`, so CMS-only files build in dev/CMS and static-only variants build instead.
+ * - Resolves React to one copy from your project root, avoiding "Invalid hook call" crashes when
+ *   canopycms packages are linked via `file:`/`npm link` (the bundler would otherwise follow the
+ *   symlink to a second React copy); a no-op otherwise, since it resolves to the React you already use.
+ * - With `staticBuild: true`, honors `CANOPY_BUILD_ID` as a reproducible build id (Next
+ *   defaults to a random one); unset, or off a static build, Next's default stands.
+ * - Outside a static export, adds sharp's libvips directory to `outputFileTracingIncludes['/**']`
+ *   (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.
+ * - 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
+ *   left alone.
  *
  * @example
  * ```ts
- * // next.config.ts
  * import { withCanopy } from 'canopycms-next/config'
- *
- * export default withCanopy({
- *   reactStrictMode: true,
- *   // ...your config
- * })
+ * export default withCanopy({ reactStrictMode: true })
  * ```
  */
 export function withCanopy(nextConfig = {}, options = {}) {
@@ -387,7 +359,6 @@ export function withCanopy(nextConfig = {}, options = {}) {
             return false;
         }
     });
-    // Merge transpilePackages (deduped)
     const existingPackages = nextConfig.transpilePackages ?? [];
     const allPackages = [
         ...new Set([
@@ -398,7 +369,6 @@ export function withCanopy(nextConfig = {}, options = {}) {
         ]),
     ];
     const reactAlias = resolveReactAliases(resolve);
-    // Scope React aliases to only canopycms files using module.rules[].resolve.
     // A global resolve.alias would also override Next.js's own internal React
     // (bundled at next/dist/compiled/react/), breaking its devtools and internals.
     const existingWebpack = nextConfig.webpack;
@@ -414,7 +384,6 @@ export function withCanopy(nextConfig = {}, options = {}) {
                     alias: reactAlias,
                 },
             });
-            // Chain consumer's existing webpack config
             if (typeof existingWebpack === 'function') {
                 return existingWebpack(config, ctx);
             }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "canopycms-next",
-  "version": "0.0.67-int.90",
+  "version": "0.0.67-int.91",
   "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-int.90"
+    "canopycms": "0.0.67-int.91"
   },
   "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-int.90"
+    "canopycms": "0.0.67-int.91"
   },
   "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",