canopycms 0.0.62 → 0.0.64

package/dist/content-tree.js

@@ -8,7 +8,11 @@
  * metadata, entry metadata). Display concerns like labels are left to the
  * adopter via the `extract` callback.
  */
-import { listCollectionEntries, sortByOrder } from './content-listing.js';
+import { isIndexSlug } from './utils/entry-url.js';
+import { createReferenceResolver, listCollectionEntries, resolveCollectionItemReferences, sortByOrder, } from './content-listing.js';
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
 /** Group flat schema items by parentPath for O(1) child lookup. */
 const groupByParent = (flat) => {
     const map = new Map();
@@ -27,19 +31,31 @@ const groupByParent = (flat) => {
  * All URL paths are lowercased unconditionally for consistency with slug normalization.
  * Adopters with case-sensitive slugs (e.g., "API-Reference") will get lowercased URLs.
  *
- * Index entries (slug 'index') are collapsed to their parent collection path,
+ * Index entries (slug 'index', any case) are collapsed to their parent collection path,
  * matching the URL convention used by readByUrlPath and listEntries.
+ *
+ * Exported (also re-exported from `canopycms/server`) so adopters who want to
+ * EXTEND this behavior rather than replace it can call it from inside their own
+ * `buildPath` and post-process the result, instead of reimplementing the
+ * content-root-strip / index-collapse / lowercase logic verbatim.
  */
-const defaultBuildPath = (logicalPath, contentRootName, kind) => {
+export const defaultBuildPath = (logicalPath, contentRootName, kind) => {
     const prefix = contentRootName ? `${contentRootName}/` : '';
     const stripped = prefix && logicalPath.startsWith(prefix) ? logicalPath.slice(prefix.length) : logicalPath;
     // Collapse index entries: content/guides/index → /guides (not /guides/index)
     // Only for entries — a collection named "index" should keep its path.
-    const collapsed = kind === 'entry' && stripped.endsWith('/index')
-        ? stripped.slice(0, -6)
-        : kind === 'entry' && stripped === 'index'
+    //
+    // The index test runs on the LAST SEGMENT through the shared `isIndexSlug`, so it is
+    // case-insensitive and agrees with `computeEntryUrl`. A string `endsWith('/index')` test
+    // did not: for an adopter-supplied `content/docs/Index` this said `/docs/index` while
+    // `computeEntryUrl` said `/docs`, and `/docs/index` is the one that does NOT round-trip.
+    const lastSlash = stripped.lastIndexOf('/');
+    const lastSegment = lastSlash === -1 ? stripped : stripped.slice(lastSlash + 1);
+    const collapsed = kind === 'entry' && isIndexSlug(lastSegment)
+        ? lastSlash === -1
             ? ''
-            : stripped;
+            : stripped.slice(0, lastSlash)
+        : stripped;
     const urlPath = collapsed ? `/${collapsed}` : '/';
     return urlPath.toLowerCase();
 };
@@ -53,14 +69,35 @@ const defaultBuildPath = (logicalPath, contentRootName, kind) => {
  * @param flatSchema - Flattened schema items (from flattenSchema)
  * @param contentRootName - The content root name (e.g. "content")
  * @param options - Tree-building options
+ * @param visibility - Internal path-ACL predicate; see `ContentVisibilityOptions`
  */
-export async function buildContentTree(branchRoot, flatSchema, contentRootName, options) {
+export async function buildContentTree(branchRoot, flatSchema, contentRootName, options, visibility) {
     const childrenByParent = groupByParent(flatSchema);
     const extract = options?.extract;
     const filter = options?.filter;
     const buildPath = options?.buildPath ?? ((lp, kind) => defaultBuildPath(lp, contentRootName, kind));
     const customSort = options?.sort;
     const maxDepth = options?.maxDepth;
+    /**
+     * Every entry read in this tree goes through here, so a denied entry is invisible to
+     * BOTH the entry nodes and the `indexEntry` surfaced to a collection's `extract` —
+     * the latter would otherwise hand a denied index entry's full `data` to the caller
+     * even though no node for it is ever emitted.
+     */
+    const shouldInclude = visibility?.shouldInclude;
+    // One store + cache for the whole recursive walk, so a block shared across collections is
+    // read once for the entire tree rather than once per collection. Null unless opted in —
+    // see the `resolveReferences` option above.
+    const resolver = options?.resolveReferences
+        ? createReferenceResolver(branchRoot, flatSchema, contentRootName)
+        : null;
+    const listVisibleEntries = async (collection) => {
+        const entries = await listCollectionEntries(branchRoot, collection);
+        const visible = shouldInclude ? entries.filter((e) => shouldInclude(e.physicalPath)) : entries;
+        // Resolved here rather than at the two node-building sites so BOTH inherit it — the same
+        // reason the ACL filter lives here. A denied entry is filtered above and never resolved.
+        return resolver ? resolveCollectionItemReferences(visible, collection, resolver) : visible;
+    };
     // Find the starting collection(s)
     const rootPath = options?.rootPath ?? contentRootName;
     const rootCollection = flatSchema.find((item) => item.type === 'collection' && item.logicalPath === rootPath);
@@ -99,7 +136,7 @@ export async function buildContentTree(branchRoot, flatSchema, contentRootName,
         // if `filter` rejects this collection, returning early short-circuits all
         // descendant I/O — preserving the pre-existing "filter prunes whole subtree"
         // optimization that the directory-as-page reorder would otherwise lose.
-        const entries = await listCollectionEntries(branchRoot, collection);
+        const entries = await listVisibleEntries(collection);
         // Surface the 'index' entry (when present) to extract via meta.
         // 'index' is the same magic slug Canopy uses in defaultBuildPath to collapse
         // /foo/index URLs to /foo/, keeping conventions consistent. If a collection
@@ -143,7 +180,7 @@ export async function buildContentTree(branchRoot, flatSchema, contentRootName,
     // Also get entries directly in the root collection
     const [collectionNodes, rootEntries] = await Promise.all([
         Promise.all(topLevelCollections.map((child) => buildNode(child, 1))),
-        listCollectionEntries(branchRoot, rootCollection),
+        listVisibleEntries(rootCollection),
     ]);
     const rootEntryNodes = [];
     for (const entry of rootEntries) {
@@ -192,4 +229,3 @@ function interleaveChildren(collectionNodes, entryNodes, order, customSort) {
     }
     return sortByOrder(all, order, (item) => item.kind === 'collection' ? (item.collection?.name ?? '') : (item.entry?.slug ?? ''));
 }
-//# sourceMappingURL=content-tree.js.map

package/dist/context.d.ts

@@ -1,8 +1,8 @@
-import type { CanopyUser } from './user';
-import type { CanopyServices } from './services';
-import { type PhysicalPath } from './paths';
-import { type BuildContentTreeOptions, type ContentTreeNode, type DefaultEntryTypes } from './content-tree';
-import { type ListEntriesOptions, type ListEntriesItem } from './content-listing';
+import type { CanopyUser } from './user.js';
+import type { CanopyServices } from './services.js';
+import type { ContentReadMeta } from './content-reader.js';
+import { type BuildContentTreeOptions, type ContentTreeNode, type DefaultEntryTypes } from './content-tree.js';
+import { type ListEntriesOptions, type ListEntriesItem } from './content-listing.js';
 export interface CanopyContextOptions {
     services: CanopyServices;
     /**
@@ -33,9 +33,25 @@ export interface CanopyBuildContext {
      * Supply TEntryTypes (a map of entry type name → data shape, typically
      * derived via `TypeFromEntrySchema<typeof yourSchema>`) to get narrowed
      * access to `meta.indexEntry.data` inside the `extract` callback.
+     *
+     * Path ACLs: on the request-scoped context (`getCanopy()`), entries the current user
+     * cannot `read` are omitted — from the emitted nodes AND from the `meta.indexEntry`
+     * handed to `extract`. Collections whose children are all filtered out are pruned.
+     * On the build context, and on static deployments, nothing is filtered (synthetic admin).
      */
     buildContentTree: <T = unknown, TEntryTypes = DefaultEntryTypes>(options?: BuildContentTreeOptions<T, TEntryTypes>) => Promise<ContentTreeNode<T>[]>;
-    /** List all content entries as a flat array. */
+    /**
+     * List all content entries as a flat array.
+     *
+     * Path ACLs: on the request-scoped context (`getCanopy()`), entries the current user
+     * cannot `read` are omitted before `extract` runs. On the build context, and on static
+     * deployments, nothing is filtered (synthetic admin).
+     *
+     * Branch: unlike `read`/`readByUrlPath`, this takes no `branch` option — it always lists
+     * `defaultActiveBranch ?? defaultBaseBranch ?? 'main'`. In `dev` that tracks the git HEAD
+     * via `refreshActiveBranch()`; in `prod` that refresh is a no-op, so this always reads the
+     * base branch. See `.claude/future-tasks/context-listing-branch-pinning.md`.
+     */
     listEntries: <T = Record<string, unknown>>(options?: ListEntriesOptions<T>) => Promise<ListEntriesItem<T>[]>;
     /**
      * Content reader (auth context applied automatically — admin at build time).
@@ -54,9 +70,7 @@ export interface CanopyBuildContext {
     }) => Promise<{
         data: T;
         path: string;
-        meta: {
-            physicalPath: PhysicalPath;
-        };
+        meta: ContentReadMeta;
     }>;
     /**
      * Read content by URL path, resolving the collection/entry split automatically.
@@ -64,6 +78,10 @@ export interface CanopyBuildContext {
      * Tries direct entry match first (last segment = slug, rest = collection path),
      * then falls back to index entry (full path = collection, slug = 'index').
      * Root path '/' resolves to the content root's index entry.
+     *
+     * The direct-entry attempt is SKIPPED when the last segment is an index slug (any case), so
+     * `/x/index` returns null rather than a second URL for the entry that already answers at `/x`.
+     * A collection literally named `index` is unaffected — the fallback resolves it.
      * Returns null if no content matches the path — including collection URLs that have no
      * index entry (use buildContentTree for those) and non-entry/invalid paths such as
      * `/favicon.ico` or Next internals (the slug validator rejects them, treated as a miss).
@@ -76,6 +94,12 @@ export interface CanopyBuildContext {
      * in public output, as it reveals the deployment's filesystem layout (home dir / EFS
      * mount / branch name). Intended for build-time reads of colocated artifacts.
      *
+     * `meta.entryType` and `meta.entryId` are also resolved for free (path resolution
+     * already derives them) — useful for entry-type-based dispatch in a single
+     * catch-all route without a separate `listEntries` lookup or filename parse. See
+     * `ContentReadMeta` (content-reader.ts) before branching on `entryType` for a legacy
+     * file: `entryId === undefined` signals that `entryType` is a fallback, not a read.
+     *
      * @example
      * ```ts
      * // URL /docs/guides/getting-started → reads content/docs/guides + slug "getting-started"
@@ -84,8 +108,10 @@ export interface CanopyBuildContext {
      * const result = await canopy.readByUrlPath<DocContent>('/docs/guides/getting-started')
      * if (result) {
      *   const { data, path } = result
-     *   // Read a sibling artifact colocated with the entry (server-only):
-     *   const profile = path.join(path.dirname(result.meta.physicalPath), 'profile.json')
+     *   switch (result.meta.entryType) {
+     *     case 'home': return <HomePage data={data} />
+     *     default: return <DocView data={data} />
+     *   }
      * }
      * ```
      */
@@ -95,9 +121,7 @@ export interface CanopyBuildContext {
     }) => Promise<{
         data: T;
         path: string;
-        meta: {
-            physicalPath: PhysicalPath;
-        };
+        meta: ContentReadMeta;
     } | null>;
     /** Underlying services */
     services: CanopyServices;
@@ -121,4 +145,3 @@ export declare function createCanopyContext(options: CanopyContextOptions): {
     getContext: () => Promise<CanopyContext>;
     services: CanopyServices;
 };
-//# sourceMappingURL=context.d.ts.map

package/dist/context.js

@@ -1,7 +1,7 @@
 import { isDeployedStatic, isBuildMode, STATIC_DEPLOY_USER } from './build-mode.js';
 import { createContentReader } from './content-reader.js';
 import { ContentStoreError } from './content-store.js';
-import { createLogicalPath, parseSlug, resolveBranchPaths, } from './paths/index.js';
+import { createLogicalPath, parseSlug, resolveBranchPaths } from './paths/index.js';
 import { resolveUrlPathCandidates } from './url-path-resolver.js';
 import { loadOrCreateBranchContext } from './branch-workspace.js';
 import { buildContentTree as buildContentTreeImpl, } from './content-tree.js';
@@ -135,7 +135,7 @@ export function createCanopyContext(options) {
             const { branchRoot } = resolveBranchPaths(branchContext, operatingMode);
             const contentRootName = services.config.contentRoot || 'content';
             const { flatSchema } = await services.branchSchemaCache.getSchema(branchRoot, services.entrySchemaRegistry, contentRootName);
-            return { branchRoot, flatSchema, contentRootName };
+            return { branchContext, branchRoot, flatSchema, contentRootName };
         };
         const resolveSchemaContext = () => {
             if (!schemaContextPromise) {
@@ -143,13 +143,64 @@ export function createCanopyContext(options) {
             }
             return schemaContextPromise;
         };
+        /**
+         * Path-ACL predicate for the batch reads (listEntries / buildContentTree). Memoized
+         * per getContext call, like the schema context above.
+         *
+         * These two are the only content reads on this context that did NOT enforce path
+         * permissions: `read`/`readByUrlPath` go through the content reader, which checks per
+         * entry, while the listing primitives took no user at all. Since `CanopyContext` is the
+         * request-scoped, ACL-enforcing context that page code is told to use, an unfiltered
+         * listing there disclosed full entry `data` for paths the user cannot `read()` directly.
+         *
+         * `services.createContentAccessChecker` is the existing batch primitive (api/entries.ts
+         * uses the same one): it resolves the request-constant work — branch access, the
+         * settings/permissions root, and the rule set — exactly once, and returns a synchronous
+         * per-path check. So the per-entry cost here is an admin short-circuit or a minimatch
+         * per configured rule, with no additional I/O.
+         *
+         * Returns an empty object (no predicate → unfiltered, today's behavior) at build time,
+         * on static deployments, and for the synthetic admin user. All three short-circuits are
+         * load-bearing, not just an optimization: `createContentAccessChecker` grants that user
+         * unconditional access (path checks bypass entirely for an Admins-group user, see
+         * authorization/path.ts), so the predicate would always be a no-op — but building it
+         * still costs a getSettingsBranchRoot() call, which in modes with a separate settings
+         * branch (prod and dev) means provisioning/cloning that branch's git workspace. That is
+         * an EFS round trip in prod, and it is exactly the unwanted cost for `createBuildCanopy`
+         * (see build-canopy.ts): a standalone script's whole point is running outside a request
+         * or Next.js build phase, so neither of the other two guards fires for it, and without
+         * this one every such script paid for a settings-workspace clone it never needed and,
+         * in an environment where that workspace cannot be provisioned, would hard-fail on.
+         *
+         * Compared by reference to the exported STATIC_DEPLOY_USER singleton (not by group
+         * membership) so this stays scoped to the synthetic build/admin identity specifically —
+         * a real authenticated admin hitting `getCanopy()` at request time still goes through
+         * the real check, same as any other user.
+         *
+         * Deliberately NOT wrapped in a try/catch: createContentAccessChecker is fail-loud by
+         * contract, and swallowing here would silently serve an unfiltered listing.
+         */
+        let visibilityPromise = null;
+        const resolveVisibilityImpl = async () => {
+            if (isDeployedStatic(services.config) || isBuildMode() || user === STATIC_DEPLOY_USER)
+                return {};
+            const { branchContext, branchRoot } = await resolveSchemaContext();
+            const checkAccess = await services.createContentAccessChecker(branchContext, branchRoot, user);
+            return { shouldInclude: (physicalPath) => checkAccess(physicalPath, 'read').allowed };
+        };
+        const resolveVisibility = () => {
+            if (!visibilityPromise) {
+                visibilityPromise = resolveVisibilityImpl();
+            }
+            return visibilityPromise;
+        };
         const buildContentTree = async (options) => {
             const { branchRoot, flatSchema, contentRootName } = await resolveSchemaContext();
-            return buildContentTreeImpl(branchRoot, flatSchema, contentRootName, options);
+            return buildContentTreeImpl(branchRoot, flatSchema, contentRootName, options, await resolveVisibility());
         };
         const listEntries = async (options) => {
             const { branchRoot, flatSchema, contentRootName } = await resolveSchemaContext();
-            return listEntriesImpl(branchRoot, flatSchema, contentRootName, options);
+            return listEntriesImpl(branchRoot, flatSchema, contentRootName, options, await resolveVisibility());
         };
         return {
             read,
@@ -165,4 +216,3 @@ export function createCanopyContext(options) {
         services,
     };
 }
-//# sourceMappingURL=context.js.map

package/dist/dev-content-watcher.d.ts

@@ -16,8 +16,8 @@
  * All logic lives here in the core package; framework adapters just call startDevContentWatcher() once
  * at dev startup. See packages/canopycms-next/src/context-wrapper.ts for the Next wiring.
  */
-import type { CanopyServices } from './services';
-import type { DevContentSyncMode } from './config/types';
+import type { CanopyServices } from './services.js';
+import type { DevContentSyncMode } from './config/types.js';
 export interface StartDevContentWatcherOptions {
     /** 'warn' (default) | 'off'. */
     mode?: DevContentSyncMode;
@@ -34,4 +34,3 @@ export interface StartDevContentWatcherOptions {
  * not in dev mode, or when the working-tree content directory does not exist.
  */
 export declare function startDevContentWatcher(services: CanopyServices, options?: StartDevContentWatcherOptions): () => void;
-//# sourceMappingURL=dev-content-watcher.d.ts.map

package/dist/dev-content-watcher.js

@@ -122,4 +122,3 @@ export function startDevContentWatcher(services, options = {}) {
     activeWatchers.set(workingTreeContentDir, dispose);
     return dispose;
 }
-//# sourceMappingURL=dev-content-watcher.js.map

package/dist/editor/BranchManager.d.ts

@@ -1,8 +1,8 @@
 import React from 'react';
-import type { OperatingMode } from '../operating-mode';
-import type { ConflictStatus, PullRequestState, SyncStatus } from '../types';
-import type { CommentThread } from '../comment-store';
-import type { UserSearchResult } from '../auth/types';
+import type { OperatingMode } from '../operating-mode/index.js';
+import type { ConflictStatus, PullRequestState, SyncStatus } from '../types.js';
+import type { CommentThread } from '../comment-store.js';
+import type { UserSearchResult } from '../auth/types.js';
 export interface BranchSummary {
     name: string;
     status: string;
@@ -85,4 +85,3 @@ export interface BranchManagerProps {
     onGetUserMetadata?: (userId: string) => Promise<UserSearchResult | null>;
 }
 export declare const BranchManager: React.FC<BranchManagerProps>;
-//# sourceMappingURL=BranchManager.d.ts.map

package/dist/editor/BranchManager.js

@@ -152,4 +152,3 @@ export const BranchManager = ({ branches, mode, user, onSelect, onCreate, onDele
                                                             : 'Only Admin or branch creator can delete', disabled: perms.canDelete, children: _jsx(Button, { size: "xs", variant: "outline", color: "red", onClick: () => onDelete?.(b.name), disabled: !perms.canDelete, "data-testid": `delete-branch-button-${b.name}`, children: "Delete" }) })] })] }) }, b.name));
                     }) })) })] }));
 };
-//# sourceMappingURL=BranchManager.js.map

package/dist/editor/CanopyEditor.d.ts

@@ -1,10 +1,9 @@
 import React from 'react';
-import type { CanopyClientConfig } from '../config';
-import type { EditorProps } from './Editor';
+import type { CanopyClientConfig } from '../config/index.js';
+import type { EditorProps } from './Editor.js';
 export interface CanopyEditorProps extends Omit<EditorProps, 'collections' | 'previewBaseByCollection' | 'title' | 'subtitle' | 'themeOptions' | 'entries' | 'contentRoot' | 'operatingMode'> {
     config: CanopyClientConfig;
     entries?: EditorProps['entries'];
 }
 export declare const CanopyEditor: React.FC<CanopyEditorProps>;
 export default CanopyEditor;
-//# sourceMappingURL=CanopyEditor.d.ts.map

package/dist/editor/CanopyEditor.js

@@ -16,7 +16,6 @@ export const CanopyEditor = ({ config, entries = [], initialSelectedId, initialV
     const resolvedTitle = config.editor?.title ?? 'CanopyCMS Editor';
     const resolvedSubtitle = config.editor?.subtitle;
     const resolvedTheme = config.editor?.theme ?? undefined;
-    return (_jsx(SWRProvider, { children: _jsx(ApiClientProvider, { children: _jsx(Editor, { entries: entries, title: resolvedTitle, subtitle: resolvedSubtitle, branchName: resolvedBranchName, operatingMode: config.mode, initialSelectedId: initialSelectedId, initialValues: initialValues, renderPreview: renderPreview, onCreateEntry: onCreateEntry, customRenderers: customRenderers, collections: collections, contentRoot: config.contentRoot, entryLinkUrl: config.entryLinkUrl, previewBaseByCollection: previewBase, assetBaseUrl: config.assetBaseUrl, themeOptions: resolvedTheme, AccountComponent: config.editor?.AccountComponent, onAccountClick: config.editor?.onAccountClick, onLogoutClick: config.editor?.onLogoutClick }) }) }));
+    return (_jsx(SWRProvider, { children: _jsx(ApiClientProvider, { basePath: config.basePath, children: _jsx(Editor, { entries: entries, title: resolvedTitle, subtitle: resolvedSubtitle, branchName: resolvedBranchName, operatingMode: config.mode, initialSelectedId: initialSelectedId, initialValues: initialValues, renderPreview: renderPreview, onCreateEntry: onCreateEntry, customRenderers: customRenderers, collections: collections, contentRoot: config.contentRoot, entryLinkUrl: config.entryLinkUrl, previewBaseByCollection: previewBase, assetBaseUrl: config.assetBaseUrl, basePath: config.basePath, themeOptions: resolvedTheme, AccountComponent: config.editor?.AccountComponent, onAccountClick: config.editor?.onAccountClick, onLogoutClick: config.editor?.onLogoutClick }) }) }));
 };
 export default CanopyEditor;
-//# sourceMappingURL=CanopyEditor.js.map

package/dist/editor/CanopyEditorPage.d.ts

@@ -1,5 +1,5 @@
-import type { CanopyClientConfig } from '../config';
-import type { CustomFieldRenderers } from './FormRenderer';
+import type { CanopyClientConfig } from '../config/index.js';
+import type { CustomFieldRenderers } from './FormRenderer.js';
 /**
  * @param customRenderers Optional adopter overrides for how specific field
  * types render (see `FormRenderer`'s `customRenderers` prop). Threaded
@@ -17,4 +17,3 @@ export declare const CanopyEditorPage: (config: CanopyClientConfig, customRender
     displayName: string;
 };
 export default CanopyEditorPage;
-//# sourceMappingURL=CanopyEditorPage.d.ts.map

package/dist/editor/CanopyEditorPage.js

@@ -20,4 +20,3 @@ export const CanopyEditorPage = (config, customRenderers) => {
     return CanopyEditorPageInner;
 };
 export default CanopyEditorPage;
-//# sourceMappingURL=CanopyEditorPage.js.map

package/dist/editor/CommentsPanel.d.ts

@@ -1,6 +1,6 @@
 import React from 'react';
-import type { CommentThread } from '../comment-store';
-import type { UserSearchResult } from '../auth/types';
+import type { CommentThread } from '../comment-store.js';
+import type { UserSearchResult } from '../auth/types.js';
 export interface CommentsPanelProps {
     branchName: string;
     comments: CommentThread[];
@@ -18,4 +18,3 @@ export interface CommentsPanelProps {
     onGetUserMetadata?: (userId: string) => Promise<UserSearchResult | null>;
 }
 export declare const CommentsPanel: React.FC<CommentsPanelProps>;
-//# sourceMappingURL=CommentsPanel.d.ts.map

package/dist/editor/CommentsPanel.js

@@ -66,4 +66,3 @@ export const CommentsPanel = ({ branchName, comments, canResolve, onAddComment,
                                             setNewCommentText('');
                                         }, mt: "xs", children: "Reply" }))] }) }, thread.id))) })) })] }) }));
 };
-//# sourceMappingURL=CommentsPanel.js.map

package/dist/editor/Editor.d.ts

@@ -1,16 +1,15 @@
 import React from 'react';
-import type { ContentFormat, EntrySchema } from '../config';
-import type { CustomFieldRenderers, FormValue } from './FormRenderer';
-import type { OperatingMode } from '../operating-mode';
-import { type CanopyThemeOptions } from './theme';
-import type { LogicalPath, ContentId } from '../paths/types';
+import type { ContentFormat, EntrySchema } from '../config/index.js';
+import type { CustomFieldRenderers, FormValue } from './FormRenderer.js';
+import type { OperatingMode } from '../operating-mode/index.js';
+import { type CanopyThemeOptions } from './theme.js';
+import type { LogicalPath, ContentId } from '../paths/types.js';
 export interface EditorEntry {
     path: LogicalPath;
     contentId: ContentId;
     label: string;
     status?: string;
     schema: EntrySchema;
-    apiPath: string;
     previewSrc?: string;
     collectionPath?: LogicalPath;
     collectionName?: string;
@@ -52,7 +51,7 @@ export interface EditorProps {
     operatingMode: OperatingMode;
     collections?: EditorCollection[];
     contentRoot?: string;
-    entryLinkUrl?: import('../entry-link-resolver').EntryLinkUrlResolver;
+    entryLinkUrl?: import('../entry-link-resolver.js').EntryLinkUrlResolver;
     initialSelectedId?: string;
     initialValues?: Record<string, FormValue>;
     renderPreview?: (entry: EditorEntry, value: FormValue | undefined) => React.ReactNode;
@@ -63,6 +62,13 @@ export interface EditorProps {
     canResolveComments?: boolean;
     /** `media.publicBaseUrl` from config - prefixed onto asset URLs the editor builds (MediaLibrary/ImageField/MDX image dialog). Undefined means root-relative (editor and site share an origin). */
     assetBaseUrl?: string;
+    /**
+     * `CanopyClientConfig.basePath` - the deployment prefix the host Next.js app is served under
+     * (e.g. `/preview-123`). Prefixed onto every preview iframe `src` this component builds via
+     * `buildPreviewSrc`, so the iframe navigates to the entry's real served URL instead of the
+     * un-prefixed root. Undefined means the app is served at its origin's root (no-op).
+     */
+    basePath?: string;
     /**
      * Adopter-supplied overrides for how specific field types render, keyed by
      * field `type` (see `FormRenderer`'s `customRenderers` prop). Threaded
@@ -81,4 +87,3 @@ export interface EditorProps {
  */
 export declare const Editor: React.FC<EditorProps>;
 export default Editor;
-//# sourceMappingURL=Editor.d.ts.map

package/dist/editor/Editor.js

@@ -33,7 +33,7 @@ import { MediaLibrary } from './media/MediaLibrary.js';
  * High-level editor wrapper that wires entry navigation, form rendering,
  * saving/loading, and preview rendering using entry definitions.
  */
-export const Editor = ({ entries, title, subtitle, siteTitle = title, siteSubtitle = subtitle, branchName = '', collections, contentRoot, entryLinkUrl, initialSelectedId, initialValues, renderPreview, onCreateEntry, themeOptions, operatingMode, previewBaseByCollection, currentUser = 'current-user', canResolveComments = true, assetBaseUrl, AccountComponent, onAccountClick, onLogoutClick, customRenderers, }) => {
+export const Editor = ({ entries, title, subtitle, siteTitle = title, siteSubtitle = subtitle, branchName = '', collections, contentRoot, entryLinkUrl, initialSelectedId, initialValues, renderPreview, onCreateEntry, themeOptions, operatingMode, previewBaseByCollection, currentUser = 'current-user', canResolveComments = true, assetBaseUrl, basePath, AccountComponent, onAccountClick, onLogoutClick, customRenderers, }) => {
     // Per-resource loading states
     const [branchesLoading, setBranchesLoading] = useState(false);
     const [entriesLoading, setEntriesLoading] = useState(false);
@@ -117,9 +117,9 @@ export const Editor = ({ entries, title, subtitle, siteTitle = title, siteSubtit
             branchName: branchNameState,
             previewBaseByCollection,
             contentRoot,
+            basePath,
         }),
         setBusy: setEntriesLoading,
-        contentRoot,
     });
     // Keep the entry-type list referentially stable for as long as the create
     // modal is showing the same collection. Building it inline in the JSX handed
@@ -492,7 +492,7 @@ export const Editor = ({ entries, title, subtitle, siteTitle = title, siteSubtit
         // such collection" the same (correct) not-found outcome, so the guard
         // below is reachable again. See the correction to PR #196's "unreachable
         // with entries empty" claim in
-        // .claude/future-tasks/program-b-final-review-followups.md for the write
+        // .claude/future-tasks/resolved/program-b-final-review-followups.md for the write
         // hazard this closes -- found by the 2026-08-12 adversarial review.
         const collection = findCollection(collectionsFromApi, collectionPath);
         if (!collection) {
@@ -663,7 +663,7 @@ export const Editor = ({ entries, title, subtitle, siteTitle = title, siteSubtit
     const footerHeight = 40;
     const headerTitle = currentEntry?.label ?? currentEntry?.slug ?? title;
     const breadcrumbSegments = useMemo(() => buildBreadcrumbSegments(currentEntry, collectionLabels), [collectionLabels, currentEntry]);
-    return (_jsx(CanopyCMSProvider, { ...(themeOptions ?? {}), children: _jsx(AssetContextProvider, { baseUrl: assetBaseUrl, children: _jsxs(Box, { bg: "gray.0", style: { minHeight: '100vh', width: '100%' }, children: [_jsx(EditorHeader, { ref: headerRef, siteTitle: siteTitle, siteSubtitle: siteSubtitle, headerTitle: headerTitle, currentEntry: currentEntry, branchName: branchNameState, operatingMode: operatingMode, branchStatus: currentBranch?.status, busy: busy, breadcrumbSegments: breadcrumbSegments, editedFiles: editedFiles, modifiedCount: modifiedCount, unresolvedCommentCount: comments.filter((t) => !t.resolved).length, comments: comments, hasUnsavedChanges: isSelectedDirty(), userContext: userContext, branchCreatedBy: currentBranch?.createdBy, branchAccess: currentBranch?.access, 
+    return (_jsx(CanopyCMSProvider, { ...(themeOptions ?? {}), children: _jsx(AssetContextProvider, { baseUrl: assetBaseUrl, basePath: basePath, children: _jsxs(Box, { bg: "gray.0", style: { minHeight: '100vh', width: '100%' }, children: [_jsx(EditorHeader, { ref: headerRef, siteTitle: siteTitle, siteSubtitle: siteSubtitle, headerTitle: headerTitle, currentEntry: currentEntry, branchName: branchNameState, operatingMode: operatingMode, branchStatus: currentBranch?.status, busy: busy, breadcrumbSegments: breadcrumbSegments, editedFiles: editedFiles, modifiedCount: modifiedCount, unresolvedCommentCount: comments.filter((t) => !t.resolved).length, comments: comments, hasUnsavedChanges: isSelectedDirty(), userContext: userContext, branchCreatedBy: currentBranch?.createdBy, branchAccess: currentBranch?.access, 
                         // Fail-closed for the same reason branchContentLocked above is:
                         // isProtected/writeBlocked gate real actions in EditorHeader (hiding
                         // Submit, disabling Save), so a missing wire value must read as
@@ -753,4 +753,3 @@ export const Editor = ({ entries, title, subtitle, siteTitle = title, siteSubtit
                         }, loading: deleteInProgress })] }) }) }));
 };
 export default Editor;
-//# sourceMappingURL=Editor.js.map

package/dist/editor/EditorPanes.d.ts

@@ -8,4 +8,3 @@ export interface EditorPanesProps {
 }
 export declare const EditorPanes: React.FC<EditorPanesProps>;
 export default EditorPanes;
-//# sourceMappingURL=EditorPanes.d.ts.map

package/dist/editor/EditorPanes.js

@@ -96,4 +96,3 @@ export const EditorPanes = ({ layout: layoutProp = 'side', onLayoutChange: _, pr
                                 }, children: form ?? 'Form' }) })] }) }) }) }));
 };
 export default EditorPanes;
-//# sourceMappingURL=EditorPanes.js.map

package/dist/editor/EntryNavigator.d.ts

@@ -1,5 +1,5 @@
 import React from 'react';
-import type { ContentId, LogicalPath } from '../paths/types';
+import type { ContentId, LogicalPath } from '../paths/types.js';
 import { useTree } from '@mantine/core';
 type TreeController = ReturnType<typeof useTree>;
 export interface EntryNavItem {
@@ -54,4 +54,3 @@ export interface EntryNavigatorProps {
 }
 export declare const EntryNavigator: React.FC<EntryNavigatorProps>;
 export default EntryNavigator;
-//# sourceMappingURL=EntryNavigator.d.ts.map

package/dist/editor/EntryNavigator.js

@@ -340,4 +340,3 @@ export const EntryNavigator = ({ items, collections, selectedPath, onSelect, onT
     return (_jsx(Stack, { h: "100%", style: { display: 'flex', flexDirection: 'column' }, gap: 0, "data-testid": "entry-navigator", children: _jsx(ScrollArea, { type: "auto", offsetScrollbars: true, style: { flex: 1 }, children: treeData.length === 0 ? (loading ? (_jsxs(Group, { gap: "xs", py: "sm", children: [_jsx(Loader, { size: "xs" }), _jsx(Text, { size: "xs", c: "dimmed", children: "Loading content\u2026" })] })) : (_jsx(Text, { size: "xs", c: "dimmed", py: "sm", children: "No content" }))) : (_jsx(Box, { py: "sm", children: _jsx(Tree, { data: treeData, tree: tree, renderNode: renderNode, selectOnClick: false, levelOffset: "sm" }) })) }) }));
 };
 export default EntryNavigator;
-//# sourceMappingURL=EntryNavigator.js.map

package/dist/editor/FormRenderer.d.ts

@@ -1,6 +1,6 @@
 import React from 'react';
-import type { EntrySchema, FieldConfig } from '../config';
-import type { CommentThread } from '../comment-store';
+import type { EntrySchema, FieldConfig } from '../config/index.js';
+import type { CommentThread } from '../comment-store.js';
 export type FormValue = Record<string, unknown>;
 export interface CustomFieldRenderProps {
     field: FieldConfig;
@@ -38,4 +38,3 @@ export interface FormRendererProps {
 }
 export declare const FormRenderer: React.FC<FormRendererProps>;
 export default FormRenderer;
-//# sourceMappingURL=FormRenderer.d.ts.map

package/dist/editor/FormRenderer.js

@@ -139,13 +139,33 @@ export const FormRenderer = ({ fields, value, onChange, customRenderers, branch
                     const items = Array.isArray(currentValue)
                         ? currentValue
                         : [];
-                    return (_jsx(Paper, { withBorder: true, radius: "md", p: "md", shadow: "xs", children: _jsxs(Stack, { gap: "sm", children: [_jsxs(Group, { justify: "space-between", children: [_jsx(Text, { size: "sm", fw: 600, children: label }), _jsx(Button, { size: "xs", variant: "light", onClick: () => update([...items, {}]), children: "Add item" })] }), _jsxs(Stack, { gap: "sm", children: [items.map((item, idx) => (_jsx(Paper, { withBorder: true, radius: "md", p: "sm", shadow: "xs", children: _jsxs(Stack, { gap: "xs", children: [_jsxs(Group, { justify: "space-between", children: [_jsxs(Text, { size: "xs", fw: 700, children: [label, " #", idx + 1] }), _jsx(Button, { size: "xs", variant: "subtle", color: "red", onClick: () => update(items.filter((_, i) => i !== idx)), children: "Remove" })] }), _jsx(ObjectField, { label: objectField.label, fields: objectField.fields, value: item, onChange: (next) => {
+                    return wrapWithComments(_jsx(Paper, { withBorder: true, radius: "md", p: "md", shadow: "xs", children: _jsxs(Stack, { gap: "sm", children: [_jsxs(Group, { justify: "space-between", children: [_jsx(Text, { size: "sm", fw: 600, children: label }), _jsx(Button, { size: "xs", variant: "light", onClick: () => update([...items, {}]), children: "Add item" })] }), _jsxs(Stack, { gap: "sm", children: [items.map((item, idx) => (_jsx(Paper, { withBorder: true, radius: "md", p: "sm", shadow: "xs", children: _jsxs(Stack, { gap: "xs", children: [_jsxs(Group, { justify: "space-between", children: [_jsxs(Text, { size: "xs", fw: 700, children: [label, " #", idx + 1] }), _jsx(Button, { size: "xs", variant: "subtle", color: "red", onClick: () => update(items.filter((_, i) => i !== idx)), children: "Remove" })] }), _jsx(ObjectField, { label: objectField.label, fields: objectField.fields, value: item, onChange: (next) => {
                                                             const nextItems = [...items];
                                                             nextItems[idx] = next;
                                                             update(nextItems);
                                                         }, renderField: renderField, path: [...path, idx], dataCanopyField: normalizeCanopyPath([...path, idx]) })] }) }, fieldKey([...path, idx])))), items.length === 0 && (_jsx(Text, { size: "xs", c: "dimmed", children: "No items yet. Add one to get started." }))] })] }) }, fieldKey(path)));
                 }
-                return (_jsx(ObjectField, { label: label, fields: objectField.fields, value: currentValue, onChange: (next) => update(next), renderField: renderField, path: path, dataCanopyField: normalizeCanopyPath(path) }, fieldKey(path)));
+                // Non-list object: unlike the list branch above (where each item has
+                // its own Remove button), this field had no way to return to
+                // `undefined` once given a value. That mattered because a required
+                // child field inside it can be filled and then cleared back to `''`,
+                // which `isEmptyForRequired` treats as empty (entry-validator.ts) --
+                // but the object as a whole only reads as "absent" when it is
+                // `undefined`/`null`, not when its children are individually empty.
+                // Without a way to unset the object, that state was permanently
+                // invalid. The Clear button (wired through ObjectField's onRemove)
+                // fixes that by resetting to `undefined`, never `{}` (which would
+                // still carry a required-but-empty child into validation).
+                //
+                // Shown only when the field is optional (a required object should
+                // not be clearable back to a missing state) and only once it
+                // actually has a value (nothing to clear otherwise). Labeled
+                // "Clear" rather than "Remove" so it doesn't read as deleting the
+                // field from the schema, the way "Remove" correctly does for a list
+                // item above.
+                const hasValue = currentValue !== undefined && currentValue !== null;
+                const canClear = objectField.required !== true && hasValue;
+                return wrapWithComments(_jsx(ObjectField, { label: label, fields: objectField.fields, value: currentValue, onChange: (next) => update(next), onRemove: canClear ? () => update(undefined) : undefined, renderField: renderField, path: path, dataCanopyField: normalizeCanopyPath(path) }, fieldKey(path)));
             }
             case 'code':
                 return wrapWithComments(_jsx(CodeField, { id: fieldId, label: label, value: typeof currentValue === 'string' ? currentValue : '', onChange: (v) => update(v), dataCanopyField: normalizeCanopyPath(path) }, fieldKey(path)));
@@ -165,4 +185,3 @@ export const FormRenderer = ({ fields, value, onChange, customRenderers, branch
             })] }));
 };
 export default FormRenderer;
-//# sourceMappingURL=FormRenderer.js.map

package/dist/editor/GroupManager.d.ts

@@ -2,6 +2,5 @@
  * GroupManager - Re-exports from the group-manager module.
  * This file maintains backward compatibility with existing imports.
  */
-export { GroupManager, useGroupState, useUserSearch, useExternalGroupSearch } from './group-manager';
-export type { GroupManagerProps, InternalGroup } from './group-manager';
-//# sourceMappingURL=GroupManager.d.ts.map
+export { GroupManager, useGroupState, useUserSearch, useExternalGroupSearch } from './group-manager/index.js';
+export type { GroupManagerProps, InternalGroup } from './group-manager/index.js';

package/dist/editor/GroupManager.js

@@ -4,4 +4,3 @@
  * This file maintains backward compatibility with existing imports.
  */
 export { GroupManager, useGroupState, useUserSearch, useExternalGroupSearch } from './group-manager/index.js';
-//# sourceMappingURL=GroupManager.js.map