canopycms 0.0.67-int.90 → 0.0.67

package/dist/editor/hooks/useCommentSystem.js

@@ -7,31 +7,6 @@ import { resolveMessageOrigin } from '../preview-bridge.js';
 import { commentsKey, fetchComments, useCommentsData } from './useCommentsData.js';
 /**
  * Custom hook for managing the comment system.
- *
- * Handles:
- * - Loading comments from API
- * - Adding comments to threads
- * - Resolving comment threads
- * - Field focus highlighting from preview frame
- * - Active comment context tracking
- *
- * @example
- * ```tsx
- * const {
- *   comments,
- *   activeThreads,
- *   handleAddComment,
- *   handleResolveThread,
- *   loadComments
- * } = useCommentSystem({
- *   branchName,
- *   selectedPath,
- *   currentEntry,
- *   currentUser,
- *   canResolveComments,
- *   onReloadBranches
- * })
- * ```
  */
 export function useCommentSystem(options) {
     const apiClient = useApiClient();
@@ -44,7 +19,7 @@ export function useCommentSystem(options) {
     // Automatic load, keyed per branch and deduped by SWR (e.g. React Strict
     // Mode's double effect invoke collapses to a single request). Switching
     // branches re-keys automatically, so no manual branch-change effect is
-    // needed the way there used to be.
+    // needed.
     const { data: commentsData } = useCommentsData(apiClient, options.branchName);
     const comments = commentsData?.threads ?? [];
     // Deliberately omits `options.onCommentsChange` from the deps: it's a
@@ -98,7 +73,6 @@ export function useCommentSystem(options) {
             if (!result.ok)
                 throw new Error('Failed to resolve thread');
             await loadComments(options.branchName);
-            // Branch summaries auto-update via useMemo watching comments
             notifications.show({ message: 'Thread resolved', color: 'green' });
         }
         catch {
@@ -174,20 +148,15 @@ export function useCommentSystem(options) {
         window.addEventListener('message', handleFocus);
         return () => window.removeEventListener('message', handleFocus);
     }, [options.currentEntry]);
-    // Jump-to handlers for navigating from CommentsPanel
     const handleJumpToField = (entryPath, canopyPath, threadId) => {
-        // Switch to the correct entry if needed
         if (entryPath !== options.selectedPath) {
             options.setSelectedPath(entryPath);
         }
-        // Wait for entry to load, then scroll and highlight
         window.setTimeout(() => {
-            // Find and scroll to the field element
             const fieldElement = document.querySelector(`[data-canopy-field="${canopyPath}"]`);
             if (fieldElement) {
                 fieldElement.scrollIntoView({ behavior: 'smooth', block: 'center' });
             }
-            // Set focused field path and highlight thread
             setFocusedFieldPath(canopyPath);
             setHighlightThreadId(threadId);
             window.setTimeout(() => {
@@ -197,18 +166,15 @@ export function useCommentSystem(options) {
         }, entryPath !== options.selectedPath ? 300 : 0); // Delay if switching entries
     };
     const handleJumpToEntry = (entryPath, threadId) => {
-        // Switch to the correct entry if needed
         if (entryPath !== options.selectedPath) {
             options.setSelectedPath(entryPath);
         }
-        // Wait for entry to load, then scroll and highlight
         window.setTimeout(() => {
             // Scroll to top of form (where EntryComments renders)
             const formElement = document.querySelector('[data-form-renderer]');
             if (formElement) {
                 formElement.scrollIntoView({ behavior: 'smooth', block: 'start' });
             }
-            // Set highlight thread
             setHighlightThreadId(threadId);
             window.setTimeout(() => {
                 setHighlightThreadId(undefined);
@@ -216,7 +182,6 @@ export function useCommentSystem(options) {
         }, entryPath !== options.selectedPath ? 300 : 0); // Delay if switching entries
     };
     const handleJumpToBranch = (threadId) => {
-        // Open branch manager and highlight thread
         options.setBranchManagerOpen(true);
         setHighlightThreadId(threadId);
         window.setTimeout(() => {

package/dist/editor/hooks/useDraftManager.d.ts

@@ -1,13 +1,6 @@
 import type { EditorEntry } from '../Editor.js';
 import type { LogicalPath } from '../../paths/types.js';
 import type { FormValue } from '../FormRenderer.js';
-/**
- * True when two field-error maps have the same keys and values (order
- * independent). Used to bail out of a state update with the same object
- * reference when a recompute produces an equal-but-newly-allocated map, so
- * consumers that memo on `fieldErrors` identity don't churn.
- */
-export declare const shallowEqualRecord: (a: Record<string, string>, b: Record<string, string>) => boolean;
 export interface UseDraftManagerOptions {
     branchName: string;
     selectedPath: string;
@@ -18,8 +11,8 @@ export interface UseDraftManagerOptions {
     saveEntry: (entry: EditorEntry, value: FormValue) => Promise<FormValue>;
     /**
      * The OCC version token currently held for an entry on the branch being
-     * shown (useEntryManager's `getEntryVersion`). Used to stamp each draft with
-     * the version it was based on, and to detect at save time that the token has
+     * shown (useEntryManager's `getEntryVersion`). Stamps each draft with the
+     * version it was based on, and detects at save time that the token has
      * since moved on. Optional: without it no base versions are recorded and
      * conflict detection falls back entirely to the server's 409.
      */
@@ -64,31 +57,5 @@ export interface UseDraftManagerReturn {
 }
 /**
  * Custom hook for managing draft state (localStorage persistence, save/discard).
- *
- * Handles:
- * - Draft state management
- * - localStorage persistence (restore on mount, persist on change)
- * - Save/discard operations
- * - Reload from server
- * - Computed values (selectedValue, effectiveValue, modifiedCount, editedFiles)
- *
- * @example
- * ```tsx
- * const {
- *   drafts,
- *   effectiveValue,
- *   modifiedCount,
- *   handleSave,
- *   handleDiscardDrafts
- * } = useDraftManager({
- *   branchName,
- *   selectedPath,
- *   currentEntry,
- *   entries,
- *   loadEntry,
- *   saveEntry,
- *   setBusy
- * })
- * ```
  */
 export declare function useDraftManager(options: UseDraftManagerOptions): UseDraftManagerReturn;

package/dist/editor/hooks/useDraftManager.js

@@ -16,11 +16,11 @@ const toFieldErrorMap = (errors) => {
 };
 /**
  * True when two field-error maps have the same keys and values (order
- * independent). Used to bail out of a state update with the same object
- * reference when a recompute produces an equal-but-newly-allocated map, so
- * consumers that memo on `fieldErrors` identity don't churn.
+ * independent). Bails a state update out with the same object reference
+ * when a recompute produces an equal-but-newly-allocated map, so consumers
+ * that memo on `fieldErrors` identity don't churn.
  */
-export const shallowEqualRecord = (a, b) => {
+const shallowEqualRecord = (a, b) => {
     const aKeys = Object.keys(a);
     const bKeys = Object.keys(b);
     if (aKeys.length !== bKeys.length)
@@ -65,32 +65,6 @@ const parsePersistedDrafts = (raw) => {
 };
 /**
  * Custom hook for managing draft state (localStorage persistence, save/discard).
- *
- * Handles:
- * - Draft state management
- * - localStorage persistence (restore on mount, persist on change)
- * - Save/discard operations
- * - Reload from server
- * - Computed values (selectedValue, effectiveValue, modifiedCount, editedFiles)
- *
- * @example
- * ```tsx
- * const {
- *   drafts,
- *   effectiveValue,
- *   modifiedCount,
- *   handleSave,
- *   handleDiscardDrafts
- * } = useDraftManager({
- *   branchName,
- *   selectedPath,
- *   currentEntry,
- *   entries,
- *   loadEntry,
- *   saveEntry,
- *   setBusy
- * })
- * ```
  */
 export function useDraftManager(options) {
     const [drafts, setDrafts] = useState(() => options.initialValues ?? {});
@@ -287,32 +261,27 @@ export function useDraftManager(options) {
             console.warn('Failed to persist drafts', err);
         }
     }, [drafts, storageKey]);
-    // While field errors are showing, recompute them as the user edits — or as
-    // the selected entry's schema/format changes while it stays open — so each
-    // error clears when its field is fixed or no longer required. Errors for a
-    // different entry are simply not visible (see the `fieldErrors` derivation
-    // above), so this effect only needs to keep `errorState` itself correct.
-    //
-    // Three things here are load-bearing against render loops/churn — see
-    // PR #106 review follow-up item 9:
+    // Recomputes field errors as the user edits, or as the selected entry's
+    // schema/format changes while it stays open, so each error clears when its
+    // field is fixed or no longer required. Errors for a different entry are
+    // simply not visible (see the `fieldErrors` derivation above), so this
+    // effect only needs to keep `errorState` itself correct. Server-only
+    // errors (e.g. reference existence) can't be recomputed client-side and
+    // clear on edit; the server re-reports them on save.
     //
+    // Three things keep this from causing render loops/churn:
     // 1. `options.currentEntry?.schema`/`.format` are in the deps (not just
-    //    `effectiveValue`/`currentId`) so a schema change while the same entry
-    //    stays open re-validates instead of leaving stale errors.
-    // 2. The updater is FUNCTIONAL (reads/writes via the `prev` argument), so
-    //    `errorState` itself stays out of the dep array. Depending on
-    //    `errorState` would mean every write below re-triggers this effect.
-    // 3. `shallowEqualRecord` bails out by returning `prev` (the same object
-    //    reference) when the recomputed map is equal to the last one. This
-    //    matters because `options.currentEntry` is a NEW reference whenever
-    //    useEntryManager's `entriesState` is replaced (its `currentEntry` is a
-    //    `useMemo` over `entriesState.find(...)`), which would otherwise re-run
-    //    this effect on every entries refresh and allocate a new-but-equal
-    //    errors object each time — churning any consumer that memoizes on
-    //    `fieldErrors` identity.
-    //
-    // Note: server-only errors (e.g. reference existence) cannot be recomputed
-    // client-side and clear on edit; the server re-reports them on save.
+    //    `effectiveValue`/`currentId`), so a schema change while the same
+    //    entry stays open re-validates instead of leaving stale errors.
+    // 2. The updater is FUNCTIONAL (via the `prev` argument), keeping
+    //    `errorState` itself out of the dep array -- depending on it would
+    //    mean every write below re-triggers this effect.
+    // 3. `shallowEqualRecord` returns `prev` unchanged when the recomputed map
+    //    is equal, which matters because `options.currentEntry` is a NEW
+    //    reference on every entries refresh (`currentEntry` is a `useMemo`
+    //    over `entriesState.find(...)`) -- without it, every refresh would
+    //    allocate a new-but-equal errors object and churn any consumer
+    //    memoizing on `fieldErrors` identity.
     useEffect(() => {
         const entry = options.currentEntry;
         const value = effectiveValue;
@@ -361,13 +330,6 @@ export function useDraftManager(options) {
      * One-time upgrade prompt for a draft carried across the pre-v2 -> v2
      * storage change.
      *
-     * `null` (unknown base) used to be treated exactly like a known-stale
-     * draft: blocked, with Reload and Discard the only exits -- both of which
-     * destroy the draft. And nothing ever re-stamped it, because the reconcile
-     * effect only fills ids NOT already in `bases` and `null` is present. So a
-     * legacy draft was visible, permanently unsaveable, and the only advice
-     * offered destroyed it: "kept" meant "kept and unusable".
-     *
      * A bounded, one-time population deserves a decision, not a dead end. On
      * confirm the base is re-stamped to the version currently held, so the
      * draft rejoins the ordinary flow and this is never asked again -- and the
@@ -658,9 +620,7 @@ export function useDraftManager(options) {
             },
         });
     };
-    // Compute dirty state for a given entry
     const isDirtyForEntry = (entryPath) => {
-        // Find entry by path to get its content ID
         const entry = options.entries.find((e) => e.path === entryPath);
         if (!entry)
             return false;
@@ -669,7 +629,6 @@ export function useDraftManager(options) {
             return false;
         return !loadedValues[id] || !equal(drafts[id], loadedValues[id]);
     };
-    // Convenience helper for checking current selection
     const isSelectedDirty = () => {
         if (!currentId)
             return false;

package/dist/editor/hooks/useEditorLayout.d.ts

@@ -9,25 +9,5 @@ export interface UseEditorLayoutReturn {
 }
 /**
  * Custom hook for managing Editor layout state and measurements.
- *
- * Manages:
- * - Pane layout (side-by-side or stacked)
- * - Preview highlight toggle
- * - Header height measurement via ResizeObserver
- *
- * @example
- * ```tsx
- * const { layout, setLayout, highlightEnabled, setHighlightEnabled, headerRef, headerHeight } = useEditorLayout()
- *
- * // Toggle layout
- * setLayout(layout === 'side' ? 'stacked' : 'side')
- *
- * // Toggle highlights
- * setHighlightEnabled(!highlightEnabled)
- *
- * // Use header ref and height
- * <Paper ref={headerRef}>...</Paper>
- * <Box style={{ paddingTop: headerHeight }}>...</Box>
- * ```
  */
 export declare function useEditorLayout(): UseEditorLayoutReturn;

package/dist/editor/hooks/useEditorLayout.js

@@ -1,41 +1,18 @@
 import { useEffect, useRef, useState } from 'react';
 /**
  * Custom hook for managing Editor layout state and measurements.
- *
- * Manages:
- * - Pane layout (side-by-side or stacked)
- * - Preview highlight toggle
- * - Header height measurement via ResizeObserver
- *
- * @example
- * ```tsx
- * const { layout, setLayout, highlightEnabled, setHighlightEnabled, headerRef, headerHeight } = useEditorLayout()
- *
- * // Toggle layout
- * setLayout(layout === 'side' ? 'stacked' : 'side')
- *
- * // Toggle highlights
- * setHighlightEnabled(!highlightEnabled)
- *
- * // Use header ref and height
- * <Paper ref={headerRef}>...</Paper>
- * <Box style={{ paddingTop: headerHeight }}>...</Box>
- * ```
  */
 export function useEditorLayout() {
     const [layout, setLayout] = useState('side');
     const [highlightEnabled, setHighlightEnabled] = useState(false);
     const [headerHeight, setHeaderHeight] = useState(80);
     const headerRef = useRef(null);
-    // Measure header height using ResizeObserver
     useEffect(() => {
         if (!headerRef.current)
             return;
         const node = headerRef.current;
         const updateHeight = () => setHeaderHeight(node.getBoundingClientRect().height || 80);
-        // Initial measurement
         updateHeight();
-        // Watch for size changes
         const observer = new ResizeObserver(updateHeight);
         observer.observe(node);
         return () => observer.disconnect();

package/dist/editor/hooks/useEntriesData.d.ts

@@ -18,6 +18,7 @@ export interface FetchEntriesParams {
  * repeat across pages if content changes between requests.
  *
  * Exported for direct unit testing.
+ * @internal Exported for tests.
  */
 export declare function listAllEntries(apiClient: {
     entries: Pick<ApiClient['entries'], 'list'>;

package/dist/editor/hooks/useEntriesData.js

@@ -11,9 +11,7 @@
  * EditorCollection objects requires the hydrated flatSchema either way (see
  * `fetchEntriesAndSchema`). This is also the single source of truth for
  * `availableSchemas` (the entry-type schema names, keyed off the same
- * schema response) -- Editor.tsx used to fetch schema a second time on its
- * own just to compute this list; it now reads it off useEntryManager's
- * return value instead, eliminating that duplicate request.
+ * schema response).
  */
 import { notifications } from '@mantine/notifications';
 import { MAX_ENTRIES_PER_PAGE } from '../../api/entries-constants.js';
@@ -30,6 +28,7 @@ export const entriesKey = (branch) => `canopy:entries:${branch}`;
  * repeat across pages if content changes between requests.
  *
  * Exported for direct unit testing.
+ * @internal Exported for tests.
  */
 export async function listAllEntries(apiClient, branch) {
     const byPath = new Map();

package/dist/editor/hooks/useEntryLinkResolution.d.ts

@@ -3,8 +3,8 @@
  *
  * Builds a Map<contentId, urlPath> from the loaded editor entries,
  * then provides a function to resolve entry:ID patterns in text.
- * Used to transform body content before it reaches the PreviewFrame,
- * so the preview iframe receives fully-resolved URLs.
+ * Transforms body content before it reaches the PreviewFrame, so the
+ * preview iframe receives fully-resolved URLs.
  */
 import type { EditorEntry } from '../Editor.js';
 import { type EntryLinkUrlResolver } from '../../entry-link-resolver.js';

package/dist/editor/hooks/useEntryLinkResolution.js

@@ -3,8 +3,8 @@
  *
  * Builds a Map<contentId, urlPath> from the loaded editor entries,
  * then provides a function to resolve entry:ID patterns in text.
- * Used to transform body content before it reaches the PreviewFrame,
- * so the preview iframe receives fully-resolved URLs.
+ * Transforms body content before it reaches the PreviewFrame, so the
+ * preview iframe receives fully-resolved URLs.
  */
 import { useMemo } from 'react';
 import { computeEntryUrl } from '../../utils/entry-url.js';

package/dist/editor/hooks/useEntryManager.d.ts

@@ -2,6 +2,7 @@ import type { EditorEntry, EditorCollection } from '../Editor.js';
 import type { LogicalPath } from '../../paths/types.js';
 import type { FormValue } from '../FormRenderer.js';
 import type { EntryFieldError } from '../../validation/entry-validator.js';
+/** @internal Exported for tests. */
 export { listAllEntries } from './useEntriesData.js';
 /**
  * Thrown by saveEntry when the API returns a non-200 response. Carries the
@@ -69,7 +70,7 @@ export interface UseEntryManagerReturn {
      * Slugs already taken in `createModalCollection`, derived from the
      * already-loaded `entries` list. Lets the create modal reject an obvious
      * collision client-side with a clear message, before ever hitting the
-     * server's authoritative 409 guard (August 2026 baseline review).
+     * server's authoritative 409 guard.
      */
     createModalExistingSlugs: Set<string>;
     handleCreateModalSubmit: (slug: string, entryTypeName: string) => Promise<void>;
@@ -77,31 +78,5 @@ export interface UseEntryManagerReturn {
 }
 /**
  * Custom hook for managing editor entries (CRUD operations).
- *
- * Handles:
- * - Entry selection and navigation
- * - Loading and saving entry data
- * - Refreshing entry list from API
- * - Creating new entries
- * - URL synchronization for selected entry
- *
- * @example
- * ```tsx
- * const {
- *   selectedPath,
- *   entries,
- *   currentEntry,
- *   refreshEntries,
- *   handleCreateEntry,
- *   loadEntry,
- *   saveEntry
- * } = useEntryManager({
- *   initialEntries: entries,
- *   branchName,
- *   collections,
- *   resolvePreviewSrc,
- *   setBusy
- * })
- * ```
  */
 export declare function useEntryManager(options: UseEntryManagerOptions): UseEntryManagerReturn;

package/dist/editor/hooks/useEntryManager.js

@@ -9,6 +9,7 @@ import { entriesKey, fetchEntriesAndSchema } from './useEntriesData.js';
 // Re-exported so existing imports of `listAllEntries` from this module keep
 // working -- the implementation lives in useEntriesData.ts alongside the
 // other fetch/key/type pieces useEntryManager shares with the SWR layer.
+/** @internal Exported for tests. */
 export { listAllEntries } from './useEntriesData.js';
 /**
  * Thrown by saveEntry when the API returns a non-200 response. Carries the
@@ -33,32 +34,6 @@ const EMPTY_COLLECTIONS = [];
 const EMPTY_SCHEMAS = [];
 /**
  * Custom hook for managing editor entries (CRUD operations).
- *
- * Handles:
- * - Entry selection and navigation
- * - Loading and saving entry data
- * - Refreshing entry list from API
- * - Creating new entries
- * - URL synchronization for selected entry
- *
- * @example
- * ```tsx
- * const {
- *   selectedPath,
- *   entries,
- *   currentEntry,
- *   refreshEntries,
- *   handleCreateEntry,
- *   loadEntry,
- *   saveEntry
- * } = useEntryManager({
- *   initialEntries: entries,
- *   branchName,
- *   collections,
- *   resolvePreviewSrc,
- *   setBusy
- * })
- * ```
  */
 export function useEntryManager(options) {
     const apiClient = useApiClient();
@@ -115,45 +90,33 @@ export function useEntryManager(options) {
     const versionKey = (branch, contentId) => `${branch}:${contentId}`;
     // PER-BRANCH monotonic tokens guarding every commit of the fetched
     // `BranchView` record above, shared by BOTH the automatic SWR-backed load
-    // (below) and explicit `refreshEntries()` calls. Two maps, keyed by branch:
+    // (below) and explicit `refreshEntries()` calls. `claimed` bumps the
+    // moment an attempt's request starts (baked into that attempt's result
+    // tag); `committed` is the tag seq currently reflected in state, per
+    // branch.
     //
-    // - `claimed`: bumped the moment an attempt's request starts; the value is
-    //   baked into that attempt's result tag.
-    // - `committed`: the tag seq currently REFLECTED IN STATE for that branch.
+    // Commit rule: `tag.seq >= committed(tag.branch)` -- never move a branch's
+    // view backwards -- NOT `tag.seq === claimed(tag.branch)` ("newest attempt
+    // wins"). Two reasons:
     //
-    // The commit rule is `tag.seq >= committed(tag.branch)` -- "never move a
-    // branch's view backwards" -- NOT `tag.seq === claimed(tag.branch)`
-    // ("newest attempt wins"). The difference matters twice:
+    // 1. SWR replays a branch's cached tagged result on a switch back, and
+    //    that tag carries the seq claimed when it was originally fetched --
+    //    older than the newest claim by then. A newest-attempt rule would fail
+    //    that valid cache hit and never commit it, and when the switch back
+    //    also lands inside SWR's dedupingInterval no revalidation follows
+    //    either, leaving the previous branch's entries on screen indefinitely.
+    //    The committed-seq rule always accepts a replayed tag.
+    // 2. On remount these refs reset to empty maps while SWR's own cache
+    //    (owned by the `SWRProvider` above this component) survives, so a
+    //    replayed tag can carry a seq higher than anything this instance ever
+    //    claimed, yet still be the newest data known for that branch.
     //
-    // 1. SWR replays a branch's CACHED tagged result when the user switches
-    //    back to it, and the cached tag necessarily carries the seq claimed
-    //    when that data was originally fetched. Under a newest-attempt rule
-    //    (or a single GLOBAL counter, as originally shipped), any newer claim
-    //    -- another branch's load with a global counter, or the switch-back's
-    //    own revalidation with a per-branch one -- made the replayed,
-    //    perfectly valid cache hit fail the check and never commit; when the
-    //    switch back also landed inside SWR's dedupingInterval, no
-    //    revalidation followed either, so the editor kept showing the
-    //    PREVIOUS branch's entries under the new branch indefinitely. A
-    //    replayed tag always passes the committed-seq rule (it was committed
-    //    before, or is newer than what was).
-    // 2. On remount these refs reset to empty maps while SWR's cache (owned by
-    //    the provider above this component) survives, so a replayed tag can
-    //    carry a seq higher than anything this instance ever claimed -- still
-    //    the newest data known for that branch, and still committable. Note the
-    //    cache now belongs to `SWRProvider`'s own `provider` Map rather than
-    //    SWR's module global, so "survives" means across remounts BELOW
-    //    `CanopyEditor`; remounting `CanopyEditor` itself starts a fresh cache,
-    //    which is the same empty-cache path as a first load.
-    //
-    // What the committed-seq rule gives up: when two same-branch attempts race
-    // and the OLDER response arrives second while the newer is still in
-    // flight, the older commits transiently and the newer overwrites it on
-    // settle (a sub-second flash of slightly-stale data, converging to the
-    // newest). A response older than what's already displayed is still
-    // rejected outright. Cross-branch bleed is prevented separately: every
-    // commit site checks the tag's branch against options.branchName at
-    // settle time.
+    // Trade-off: when two same-branch attempts race and the older response
+    // settles second, it commits transiently before the newer overwrites it on
+    // settle. An older response than what's already displayed is still
+    // rejected outright; every commit site also checks the tag's branch
+    // against options.branchName at settle time to keep cross-branch bleed
+    // out.
     const refreshSeqRef = useRef({
         claimed: new Map(),
         committed: new Map(),
@@ -325,9 +288,6 @@ export function useEntryManager(options) {
         }
         return fetched.entries;
     };
-    /**
-     * Open the create entry modal for the specified collection
-     */
     const handleCreateEntry = async (collectionPath, _) => {
         const col = collectionByPath.get(collectionPath);
         if (!col || col.type === 'entry') {
@@ -337,9 +297,6 @@ export function useEntryManager(options) {
         setCreateModalError(null);
         setCreateModalOpen(true);
     };
-    /**
-     * Handle entry creation from the modal
-     */
     const handleCreateModalSubmit = async (slug, entryTypeName) => {
         if (!createModalCollection)
             return;
@@ -351,9 +308,9 @@ export function useEntryManager(options) {
             // expectedVersion: null is the create-intent signal the server
             // enforces authoritatively (see content-store.ts's write() OCC block
             // and api/content.ts's writeContentHandler) -- "this slug must not
-            // already exist yet". Without it a create is indistinguishable from a
-            // blind update, which used to let a same-slug create silently
-            // overwrite existing content (August 2026 baseline review).
+            // already exist yet". The client always sends create intent here,
+            // never a blind update, so a same-slug create cannot silently
+            // overwrite existing content.
             const payload = isDataOnlyFormat(format)
                 ? { format: format, data: {}, expectedVersion: null }
                 : { format, data: {}, body: '', expectedVersion: null };
@@ -394,18 +351,12 @@ export function useEntryManager(options) {
             setCreateModalCreating(false);
         }
     };
-    /**
-     * Close the create entry modal
-     */
     const closeCreateModal = () => {
         setCreateModalOpen(false);
         setCreateModalCollection(null);
         setCreateModalError(null);
         setCreateModalCreating(false);
     };
-    /**
-     * Rename an entry's slug
-     */
     const renameEntry = async (path, newSlug) => {
         options.setBusy(true);
         try {
@@ -483,7 +434,7 @@ export function useEntryManager(options) {
         }).then((fetched) => ({ fetched, seq, branch }));
     });
     // Commit the current branch's tagged data -- both fresh settles AND SWR
-    // cache replays on a switch back to a previously visited branch (the
+    // cache replays on a switch back to an earlier-visited branch (the
     // effect re-runs on options.branchName so the replayed tag, whose object
     // identity didn't change, still gets (re)committed). The seq comparison is
     // the per-branch committed-seq rule -- see refreshSeqRef's doc comment for

package/dist/editor/hooks/useGroupManager.d.ts

@@ -2,7 +2,6 @@ import type { InternalGroup } from '../../authorization/index.js';
 import type { UserSearchResult, GroupMetadata } from '../../auth/types.js';
 export interface UseGroupManagerOptions {
     /**
-     * Whether the group manager is currently open.
      * Groups are loaded when this becomes true.
      */
     isOpen: boolean;
@@ -18,25 +17,5 @@ export interface UseGroupManagerReturn {
 }
 /**
  * Custom hook for managing internal groups (CRUD operations).
- *
- * Handles:
- * - Loading groups from API
- * - Saving groups to API
- * - Searching for users to add to groups
- * - Searching for external groups
- *
- * @example
- * ```tsx
- * const { groupsData, groupsLoading, handleSaveGroups, handleSearchUsers } = useGroupManager({
- *   isOpen: groupManagerOpen
- * })
- *
- * // Groups are automatically loaded when isOpen becomes true
- * // Save groups
- * await handleSaveGroups(updatedGroups)
- *
- * // Search users
- * const users = await handleSearchUsers('john', 10)
- * ```
  */
 export declare function useGroupManager(options: UseGroupManagerOptions): UseGroupManagerReturn;