canopycms 0.12.0 → 0.13.0

package/dist/editor/hooks/useConflictChoices.js

@@ -0,0 +1,75 @@
+'use client';
+/**
+ * The choices made on conflict cards that no save has sent yet, per entry of the open branch
+ * (conflict-choices.ts). A decided choice makes its entry count as unsaved, so a save writes it,
+ * and that save sends the conflict's key in `resolvedConflicts`. Choices belong to the branch they
+ * were made on, and go with a discard of the entry's drafts.
+ */
+import { useCallback, useMemo, useRef, useState } from 'react';
+const NONE = {};
+export function useConflictChoices(branch) {
+    const [state, setState] = useState({
+        branch,
+        choices: {},
+    });
+    const choices = state.branch === branch ? state.choices : {};
+    const latest = useRef({ branch, choices });
+    latest.current = { branch, choices };
+    // Choices are held for the open branch only: one made after a switch starts its branch afresh,
+    // and a late answer about another branch leaves them alone.
+    const update = useCallback((forBranch, change, starts = false) => setState((prev) => {
+        if (prev.branch !== forBranch) {
+            return starts ? { branch: forBranch, choices: change({}) } : prev;
+        }
+        const next = change(prev.choices);
+        return next === prev.choices ? prev : { branch: forBranch, choices: next };
+    }), []);
+    const choose = useCallback((contentId, key, mergeSha, choice, decided) => update(latest.current.branch, (current) => {
+        const { [key]: _old, ...rest } = current[contentId] ?? {};
+        const entry = choice ? { ...rest, [key]: { mergeSha, choice, decided } } : rest;
+        const { [contentId]: _entry, ...others } = current;
+        return Object.keys(entry).length > 0 ? { ...others, [contentId]: entry } : others;
+    }, true), [update]);
+    const pendingIds = useMemo(() => new Set(Object.entries(choices)
+        .filter(([, entry]) => Object.values(entry).some((c) => c.decided))
+        .map(([id]) => id)), [choices]);
+    const pending = useCallback((forBranch, contentId) => {
+        if (forBranch !== latest.current.branch)
+            return [];
+        return Object.entries(latest.current.choices[contentId] ?? {})
+            .filter(([, c]) => c.decided)
+            .map(([key, c]) => ({ mergeSha: c.mergeSha, key }));
+    }, []);
+    const sent = useCallback((forBranch, contentId, resolved) => update(forBranch, (current) => {
+        const entry = current[contentId];
+        if (!entry)
+            return current;
+        const left = Object.fromEntries(Object.entries(entry).filter(([key, c]) => !resolved.some((r) => r.key === key && r.mergeSha === c.mergeSha)));
+        const { [contentId]: _sent, ...others } = current;
+        return Object.keys(left).length > 0 ? { ...others, [contentId]: left } : others;
+    }), [update]);
+    const clear = useCallback((contentId) => update(latest.current.branch, (current) => {
+        if (contentId === undefined)
+            return Object.keys(current).length > 0 ? {} : current;
+        if (!(contentId in current))
+            return current;
+        const { [contentId]: _cleared, ...others } = current;
+        return others;
+    }), [update]);
+    const retain = useCallback((contentId, open) => update(latest.current.branch, (current) => {
+        const entry = current[contentId];
+        if (!entry)
+            return current;
+        const kept = Object.entries(entry).filter(([key, c]) => open.some((o) => o.key === key && o.mergeSha === c.mergeSha));
+        if (kept.length === Object.keys(entry).length)
+            return current;
+        const { [contentId]: _stale, ...others } = current;
+        return kept.length > 0 ? { ...others, [contentId]: Object.fromEntries(kept) } : others;
+    }), [update]);
+    const keepEntries = useCallback((open) => update(latest.current.branch, (current) => {
+        const kept = Object.entries(current).filter(([id]) => open.has(id));
+        return kept.length === Object.keys(current).length ? current : Object.fromEntries(kept);
+    }), [update]);
+    const choicesFor = useCallback((contentId) => choices[contentId] ?? NONE, [choices]);
+    return { choicesFor, choose, pendingIds, pending, sent, clear, retain, keepEntries };
+}

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

@@ -0,0 +1,26 @@
+import type { ApiClient } from '../context/index.js';
+import type { EntryConflictData, MergeConflictsData } from '../../api/merge-conflicts.js';
+export interface EntryConflictTarget {
+    logicalPath: string;
+    /** The entry's content id, which tells it from a collection at the same path. */
+    id?: string;
+}
+export interface ConflictsState<T> {
+    data: T | undefined;
+    /** Why the last read failed, in the server's words where it gave some. */
+    error: string | undefined;
+    isValidating: boolean;
+    reload: () => Promise<void>;
+}
+/**
+ * The branch's open conflicts, read while its listing names any (`conflictFiles`); undefined
+ * otherwise, which means none.
+ */
+export declare function useBranchConflictsData(apiClient: Pick<ApiClient, 'conflicts'>, branch: string, conflictFiles: readonly string[] | undefined, 
+/** Read even with no entry named, as the editor does to learn of a hold on the branch. */
+always?: boolean): ConflictsState<MergeConflictsData>;
+/**
+ * One entry's conflicts, read while `target` is set (its drawer is open): null when it has none,
+ * which the API answers with a 404.
+ */
+export declare function useEntryConflictData(apiClient: Pick<ApiClient, 'conflicts'>, branch: string, target: EntryConflictTarget | undefined): ConflictsState<EntryConflictData | null>;

package/dist/editor/hooks/useConflictsData.js

@@ -0,0 +1,89 @@
+'use client';
+/**
+ * SWR-backed reads of the conflicts a merge left on a branch (api/merge-conflicts.ts): the list,
+ * for Submit's reason, the bar's badge and an entry's notice, and one entry's conflicts for its
+ * "Show changes" drawer. A null key fetches nothing.
+ */
+import { useCallback, useEffect, useRef } from 'react';
+import useSWR, { useSWRConfig } from 'swr';
+const KEY_PREFIX = 'canopy:conflicts:';
+/**
+ * The list's key, one per branch, so a re-read keeps the last answer showing until it lands: a
+ * branch's hold must not blink off while its list is read again.
+ */
+const listKey = (branch) => `${KEY_PREFIX}${branch}|`;
+/** An entry's key, under its branch's prefix and a `:`, which no branch name holds. */
+const entryKey = (branch, target) => `${KEY_PREFIX}${branch}:${target.logicalPath}${target.id ? `#${target.id}` : ''}`;
+class ConflictsLoadError extends Error {
+}
+/**
+ * The branch's open conflicts, read while its listing names any (`conflictFiles`); undefined
+ * otherwise, which means none.
+ */
+export function useBranchConflictsData(apiClient, branch, conflictFiles, 
+/** Read even with no entry named, as the editor does to learn of a hold on the branch. */
+always = false) {
+    const key = branch && (always || conflictFiles?.length) ? listKey(branch) : null;
+    const swr = useSWR(key, async () => {
+        const result = await apiClient.conflicts.list({ branch });
+        if (result.ok && result.data && Array.isArray(result.data.conflicts))
+            return result.data;
+        throw new ConflictsLoadError(result.error ?? `HTTP ${result.status}`);
+    });
+    const { mutate } = swr;
+    // A listing that changes what is open (`conflictFiles`) reads the list again.
+    const open = (conflictFiles ?? []).join(',');
+    const lastOpen = useRef(open);
+    useEffect(() => {
+        if (lastOpen.current === open)
+            return;
+        lastOpen.current = open;
+        if (key)
+            void mutate();
+    }, [open, key, mutate]);
+    const { mutate: mutateKeys } = useSWRConfig();
+    const reload = useCallback(async () => {
+        const prefix = `${KEY_PREFIX}${branch}`;
+        await Promise.all([
+            mutate(),
+            mutateKeys((k) => typeof k === 'string' && (k.startsWith(`${prefix}:`) || k.startsWith(`${prefix}|`))),
+        ]);
+    }, [mutate, mutateKeys, branch]);
+    return {
+        data: key ? swr.data : undefined,
+        error: key && swr.error instanceof Error ? swr.error.message : undefined,
+        isValidating: swr.isValidating,
+        reload,
+    };
+}
+/**
+ * One entry's conflicts, read while `target` is set (its drawer is open): null when it has none,
+ * which the API answers with a 404.
+ */
+export function useEntryConflictData(apiClient, branch, target) {
+    const key = branch && target ? entryKey(branch, target) : null;
+    const swr = useSWR(key, async () => {
+        if (!target)
+            return null;
+        const result = await apiClient.conflicts.entry({
+            branch,
+            entryPath: target.logicalPath,
+            ...(target.id && { id: target.id }),
+        });
+        if (result.ok && result.data && Array.isArray(result.data.fields))
+            return result.data;
+        if (result.status === 404)
+            return null;
+        throw new ConflictsLoadError(result.error ?? `HTTP ${result.status}`);
+    });
+    const { mutate } = swr;
+    const reload = useCallback(async () => {
+        await mutate();
+    }, [mutate]);
+    return {
+        data: key ? swr.data : undefined,
+        error: key && swr.error instanceof Error ? swr.error.message : undefined,
+        isValidating: swr.isValidating,
+        reload,
+    };
+}

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

@@ -25,7 +25,7 @@ export interface UseDraftManagerOptions {
     currentEntry: EditorEntry | undefined;
     entries: EditorEntry[];
     initialValues?: Record<string, FormValue>;
-    loadEntry: (entry: EditorEntry) => Promise<FormValue>;
+    loadEntry: (entry: EditorEntry, isCurrent?: () => boolean) => Promise<FormValue>;
     /**
      * Server read that records no OCC token (useEntryManager's `readEntryValue`),
      * for checking restored drafts of unopened entries. Without it they stay
@@ -63,6 +63,11 @@ export interface UseDraftManagerOptions {
     followMovedEntry?: (entry: EditorEntry) => Promise<EditorEntry | undefined>;
     /** Creates a deleted entry again from its draft (useEntryManager's `recreateEntry`). */
     recreateEntry?: (entry: EditorEntry, value: FormValue) => Promise<EditorEntry | undefined>;
+    /**
+     * Entries with a conflict choice a save has yet to send (useConflictChoices.ts): unsaved even
+     * when the choice left the value as it was, such as "Keep your version".
+     */
+    pendingIds?: ReadonlySet<string>;
 }
 /** The unsaved work a branch-level action would leave behind. `labels` names the entries (it may be shorter than `count`). */
 export interface UnsavedSummary {
@@ -74,6 +79,13 @@ export interface UseDraftManagerReturn {
     setDrafts: React.Dispatch<React.SetStateAction<Record<string, FormValue>>>;
     loadedValues: Record<string, FormValue>;
     setLoadedValues: React.Dispatch<React.SetStateAction<Record<string, FormValue>>>;
+    /**
+     * Drops the saved copies `keep` doesn't name, so each is read again; a read already in flight
+     * then lands nothing, as it can predate the head the branch is pinned to.
+     */
+    forgetLoadedValues: (keep: (contentId: string) => boolean) => void;
+    /** Bumped by {@link forgetLoadedValues}: a read whose generation is gone writes nothing. */
+    readGeneration: React.MutableRefObject<number>;
     selectedValue: FormValue | undefined;
     loadedValue: FormValue | undefined;
     effectiveValue: FormValue | undefined;

package/dist/editor/hooks/useDraftManager.js

@@ -100,6 +100,11 @@ const VERIFY_WAIT_CAP_MS = 3000;
 export function useDraftManager(options) {
     const [drafts, setDrafts] = useState(() => options.initialValues ?? {});
     const [loadedValues, setLoadedValues] = useState({});
+    const readGeneration = useRef(0);
+    const forgetLoadedValues = (keep) => {
+        readGeneration.current += 1;
+        setLoadedValues((prev) => Object.fromEntries(Object.entries(prev).filter(([id]) => keep(id))));
+    };
     // Per-field validation errors from a blocked/rejected save (ED-H1), keyed by
     // the entry they belong to. Keying by entry id — and deriving the exposed
     // `fieldErrors` map below instead of clearing it in a separate effect after
@@ -187,12 +192,19 @@ export function useDraftManager(options) {
     //
     // 3. The comparison is `fast-deep-equal`, so key insertion order of a
     //    rehydrated draft does not make it dirty.
-    const dirtyIds = useMemo(() => Object.keys(drafts).filter((id) => {
-        if (entriesKnown && !entryById.has(id))
-            return false;
-        const baseline = loadedValues[id] ?? verifiedBaselines[id];
-        return baseline === undefined || !equal(drafts[id], baseline);
-    }), [drafts, loadedValues, verifiedBaselines, entriesKnown, entryById]);
+    //
+    // 4. An entry with a conflict choice to send counts, draft or not (`pendingIds`).
+    const pendingIds = options.pendingIds;
+    const dirtyIds = useMemo(() => {
+        const dirty = Object.keys(drafts).filter((id) => {
+            if (entriesKnown && !entryById.has(id))
+                return false;
+            const baseline = loadedValues[id] ?? verifiedBaselines[id];
+            return baseline === undefined || !equal(drafts[id], baseline);
+        });
+        const pending = [...(pendingIds ?? [])].filter((id) => !dirty.includes(id) && (!entriesKnown || entryById.has(id)));
+        return pending.length > 0 ? [...dirty, ...pending] : dirty;
+    }, [drafts, loadedValues, verifiedBaselines, entriesKnown, entryById, pendingIds]);
     const modifiedCount = dirtyIds.length;
     const editedFiles = useMemo(() => dirtyIds
         .map((id) => {
@@ -963,7 +975,10 @@ export function useDraftManager(options) {
      */
     const saveOneOfAll = async (entry, branch) => {
         const id = entry.contentId;
-        const sent = latestRef.current.drafts[id];
+        const sent = latestRef.current.drafts[id] ??
+            (latestOptionsRef.current.pendingIds?.has(id)
+                ? latestRef.current.loadedValues[id]
+                : undefined);
         if (sent === undefined)
             return undefined;
         const onBranch = () => latestOptionsRef.current.branchName === branch;
@@ -1137,7 +1152,9 @@ export function useDraftManager(options) {
             // Discarded, refreshed or saved mid-run, so neither saved nor failed by this run.
             const { drafts: remaining } = latestRef.current;
             const settled = settledDuringRunRef.current;
-            result.failed = result.failed.filter((failure) => failure.contentId in remaining && !settled.has(failure.contentId));
+            const pendingNow = latestOptionsRef.current.pendingIds;
+            result.failed = result.failed.filter((failure) => (failure.contentId in remaining || !!pendingNow?.has(failure.contentId)) &&
+                !settled.has(failure.contentId));
             result.total = result.saved.length + result.failed.length;
             if (result.saved.length > 0)
                 latestOptionsRef.current.onSaved?.();
@@ -1263,9 +1280,17 @@ export function useDraftManager(options) {
         if (!options.currentEntry || !currentId)
             return;
         const branch = options.branchName;
+        const entry = options.currentEntry;
         options.setBusy(true);
         try {
-            const loaded = await options.loadEntry(options.currentEntry);
+            // A read the branch's re-read overtakes is read again, as the reload was asked for.
+            let loaded;
+            let generation;
+            do {
+                generation = readGeneration.current;
+                const read = generation;
+                loaded = await options.loadEntry(entry, () => readGeneration.current === read);
+            } while (readGeneration.current !== generation);
             // Content ids repeat across branches; the next branch's state is not this read's.
             if (latestOptionsRef.current.branchName !== branch)
                 return;
@@ -1351,6 +1376,8 @@ export function useDraftManager(options) {
         if (!entry)
             return false;
         const id = entry.contentId;
+        if (pendingIds?.has(id))
+            return true;
         if (!drafts[id])
             return false;
         const baseline = loadedValues[id] ?? verifiedBaselines[id];
@@ -1359,6 +1386,8 @@ export function useDraftManager(options) {
     const isSelectedDirty = () => {
         if (!currentId)
             return false;
+        if (pendingIds?.has(currentId))
+            return true;
         if (!drafts[currentId])
             return false;
         return !loadedValues[currentId] || !equal(drafts[currentId], loadedValues[currentId]);
@@ -1438,6 +1467,8 @@ export function useDraftManager(options) {
         setDrafts,
         loadedValues,
         setLoadedValues,
+        forgetLoadedValues,
+        readGeneration,
         selectedValue,
         loadedValue,
         effectiveValue,

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

@@ -1,3 +1,4 @@
+import type { ResolvedFieldConflict } from '../../merge-conflicts.js';
 import type { ApiErrorCode } from '../../api/types.js';
 import type { EditorEntry, EditorCollection } from '../Editor.js';
 import type { LogicalPath } from '../../paths/types.js';
@@ -62,6 +63,18 @@ export interface UseEntryManagerOptions {
      * refreshes the entries, so what reads the same branch state reloads here.
      */
     onContentRefresh?: (branch: string) => void;
+    /**
+     * The conflicts a save of an entry resolves (useConflictChoices.ts): `pending` names them as the
+     * save sends them, and `onSaved` hears which the save sent and which the server cleared.
+     */
+    conflictResolutions?: {
+        pending: (branch: string, contentId: string) => ResolvedFieldConflict[];
+        onSaved: (branch: string, contentId: string, sent: ResolvedFieldConflict[], cleared: ResolvedFieldConflict[]) => void;
+    };
+}
+/** `withChanges: false` leaves the branch's changes to the caller, who reads them itself. */
+interface RefreshOptions {
+    withChanges?: boolean;
 }
 export interface UseEntryManagerReturn {
     selectedPath: string;
@@ -86,15 +99,16 @@ export interface UseEntryManagerReturn {
     entriesLoadFailed: boolean;
     navigatorOpen: boolean;
     setNavigatorOpen: (open: boolean) => void;
-    refreshEntries: (branch?: string) => Promise<EditorEntry[]>;
+    refreshEntries: (branch?: string, refresh?: RefreshOptions) => Promise<EditorEntry[]>;
     /** `refreshEntries`, resolving to the collections it read too. */
-    refreshContent: (branch?: string) => Promise<{
+    refreshContent: (branch?: string, refresh?: RefreshOptions) => Promise<{
         entries: EditorEntry[];
         collections: EditorCollection[];
     }>;
     handleCreateEntry: (collectionPath: LogicalPath, entryTypeName?: string) => Promise<void>;
     renameEntry: (path: string, newSlug: string) => Promise<void>;
-    loadEntry: (entry: EditorEntry) => Promise<FormValue>;
+    /** `isCurrent`, asked once the read lands, says whether to record its OCC token. */
+    loadEntry: (entry: EditorEntry, isCurrent?: () => boolean) => Promise<FormValue>;
     /** Reads an entry's server value without recording the OCC token that `loadEntry` records. */
     readEntryValue: (entry: EditorEntry) => Promise<FormValue>;
     saveEntry: (entry: EditorEntry, value: FormValue) => Promise<FormValue>;

package/dist/editor/hooks/useEntryManager.js

@@ -293,14 +293,14 @@ export function useEntryManager(options) {
         }
         return result.data;
     };
-    const loadEntry = async (entry) => {
+    const loadEntry = async (entry, isCurrent = () => true) => {
         // Pin the branch this request targets: if the user switches branches
         // while the read is in flight, the token must be recorded under the
         // branch that actually served it, not the current one.
         const requestBranch = options.branchName;
         const data = await readEntryPayload(entry, requestBranch);
         // Capture OCC version token for next save
-        if (entry.contentId && typeof data?.version === 'number') {
+        if (entry.contentId && typeof data?.version === 'number' && isCurrent()) {
             entryVersionsRef.current.set(versionKey(requestBranch, entry.contentId), data.version);
         }
         return normalizeContentPayload(data);
@@ -339,15 +339,20 @@ export function useEntryManager(options) {
         if (expectedVersion === undefined) {
             throw new SaveApiError(409, "This entry hasn't finished loading, so it can't be saved yet. Reload it and try again (your unsaved edits will be lost).");
         }
+        const resolving = options.conflictResolutions?.pending(requestBranch, entry.contentId) ?? [];
         const writeBody = {
             ...payload,
             expectedVersion,
+            ...(resolving.length > 0 && { resolvedConflicts: resolving }),
         };
         const result = await apiClient.content.write(writeParams, writeBody);
         if (isGatewayFailure(result))
             throw new UnansweredError();
         if (!result.ok)
             throw new SaveApiError(result.status, result.error, result.fieldErrors, result.code);
+        if (resolving.length > 0) {
+            options.conflictResolutions?.onSaved(requestBranch, entry.contentId, resolving, result.data?.resolvedConflicts ?? []);
+        }
         // Update stored version token from write response
         if (typeof result.data?.version === 'number') {
             entryVersionsRef.current.set(versionKey(requestBranch, entry.contentId), result.data.version);
@@ -454,10 +459,11 @@ export function useEntryManager(options) {
     // refreshSeqRef doc comment above; also warms the SWR cache for `branch`
     // so a later automatic re-fetch of the same key (e.g. switching away and
     // back) can reuse it instead of refetching.
-    const refreshContent = async (branch = options.branchName) => {
+    const refreshContent = async (branch = options.branchName, { withChanges = true } = {}) => {
         if (!branch)
             return { entries: [], collections: [] };
-        options.onContentRefresh?.(branch);
+        if (withChanges)
+            options.onContentRefresh?.(branch);
         const seq = claimRefreshSeq(branch);
         const fetched = await fetchEntriesAndSchema(apiClient, branch, {
             resolvePreviewSrc: options.resolvePreviewSrc,
@@ -477,7 +483,7 @@ export function useEntryManager(options) {
         }
         return fetched;
     };
-    const refreshEntries = async (branch = options.branchName) => (await refreshContent(branch)).entries;
+    const refreshEntries = async (branch = options.branchName, refresh) => (await refreshContent(branch, refresh)).entries;
     const handleCreateEntry = async (collectionPath, _) => {
         const col = collectionByPath.get(collectionPath);
         if (!col || col.type === 'entry') {

package/dist/editor/release-hold.d.ts

@@ -0,0 +1,12 @@
+/**
+ * An admin's release of a branch held as its record of conflicts was set aside
+ * (api/merge-conflicts.ts `releaseHold`). An unanswered request is settled by reading the record
+ * again, as the release may have landed.
+ */
+import type { ApiClient } from './context/index.js';
+import type { ReleaseOutcome } from './components/ReleaseHoldButton.js';
+/** A release's outcome, and on release whether it found the branch held, when that is known. */
+export type ReleaseResult = ReleaseOutcome & {
+    wasHeld?: boolean;
+};
+export declare function releaseConflictsHold(apiClient: Pick<ApiClient, 'conflicts'>, branch: string): Promise<ReleaseResult>;

package/dist/editor/release-hold.js

@@ -0,0 +1,39 @@
+/**
+ * An admin's release of a branch held as its record of conflicts was set aside
+ * (api/merge-conflicts.ts `releaseHold`). An unanswered request is settled by reading the record
+ * again, as the release may have landed.
+ */
+import { isGatewayFailure, isUnanswered } from './unanswered.js';
+import { getErrorMessage } from '../utils/error.js';
+const UNKNOWN = {
+    error: "The release may have gone through even though the server didn't answer. Reload the page to see whether the branch is still on hold.",
+    tone: 'warning',
+};
+const STILL_HELD = {
+    error: "The server didn't answer, and the branch is still on hold. Try again in a moment.",
+    tone: 'warning',
+};
+export async function releaseConflictsHold(apiClient, branch) {
+    const settle = async () => {
+        const now = await apiClient.conflicts.list({ branch }).catch(() => undefined);
+        if (!now?.ok || !now.data)
+            return UNKNOWN;
+        // Not held now, but this read can't say whose release that was.
+        return now.data.held ? STILL_HELD : { released: true };
+    };
+    let result;
+    try {
+        result = await apiClient.conflicts.releaseHold({ branch });
+    }
+    catch (err) {
+        return isUnanswered(err) ? settle() : { error: getErrorMessage(err), tone: 'error' };
+    }
+    if (result.ok)
+        return { released: true, wasHeld: result.data?.released !== false };
+    if (isGatewayFailure(result))
+        return settle();
+    return {
+        error: result.error ?? "Couldn't release the hold. Try again in a moment.",
+        tone: result.status === 409 ? 'warning' : 'error',
+    };
+}

package/dist/editor/server-clock.d.ts

@@ -0,0 +1,4 @@
+/** Record a time the server reported, as of when its answer arrived. */
+export declare function noteServerTime(serverTime: number, receivedAt?: number): void;
+/** Now, by the server's clock as last heard; the browser's until then. */
+export declare function serverNow(): number;

package/dist/editor/server-clock.js

@@ -0,0 +1,15 @@
+/**
+ * The server's clock as the editor last heard it, so a wait timed against a server timestamp
+ * (base-update-wait.ts) doesn't depend on the browser's clock being right. One offset per page:
+ * the editor talks to one server.
+ */
+let offsetMs = 0;
+/** Record a time the server reported, as of when its answer arrived. */
+export function noteServerTime(serverTime, receivedAt = Date.now()) {
+    if (Number.isFinite(serverTime))
+        offsetMs = serverTime - receivedAt;
+}
+/** Now, by the server's clock as last heard; the browser's until then. */
+export function serverNow() {
+    return Date.now() + offsetMs;
+}

package/dist/editor/undo-change.d.ts

@@ -14,6 +14,13 @@ type FormValue = Record<string, unknown>;
 export declare const formValueOfSide: (side: EntryChangeSide) => FormValue;
 /** A form value as a side shaped like `like`, for comparing it with the base. */
 export declare const sideOfFormValue: (value: FormValue, like: EntryChangeSide) => EntryChangeSide;
+/**
+ * `value` with `next` at a change's place, records on the way made as needed; undefined when the
+ * place is inside an item `value` no longer has.
+ */
+export declare const withValueAt: (value: FormValue, change: Pick<EntryChange, "dataPath">, next: unknown, bodyField?: string) => FormValue | undefined;
+/** What `value` holds at a change's place; undefined where it has nothing there. */
+export declare const valueAtChange: (value: FormValue, change: Pick<EntryChange, "dataPath">, bodyField?: string) => unknown;
 /**
  * Whether `value` holds `change` as `side` has it, so setting the change to `side` would change
  * nothing: a moved item placed as `side` places it, anything else the same value at the change's

package/dist/editor/undo-change.js

@@ -41,6 +41,16 @@ const step = (value, segment) => {
     return isPlainRecord(value) ? (isPlainRecord(value.value) ? value.value : value) : undefined;
 };
 const valueAt = (value, path) => path.reduce(step, value);
+/**
+ * `value` with `next` at a change's place, records on the way made as needed; undefined when the
+ * place is inside an item `value` no longer has.
+ */
+export const withValueAt = (value, change, next, bodyField) => {
+    const placed = updateAt(value, formPath(change, bodyField), () => next);
+    return placed && isPlainRecord(placed.value) ? placed.value : undefined;
+};
+/** What `value` holds at a change's place; undefined where it has nothing there. */
+export const valueAtChange = (value, change, bodyField) => valueAt(value, formPath(change, bodyField));
 /** What a `replace` returns when the change has nothing to act on, so it can't be placed. */
 const NOT_PLACED = Symbol('not-placed');
 /**
@@ -91,17 +101,22 @@ const updateAt = (value, path, replace) => {
 };
 /**
  * `item` placed in `list` (which lacks it) where `order` has it: after the nearest item before it
- * in `order` that `list` holds, else first.
+ * in `order` that `list` holds, else before the nearest one after it, else at its place in `order`.
  */
 const placeLike = (list, item, key, order) => {
     const at = indexOfKey(order, key);
+    const indexIn = (other) => isPlainRecord(other) ? indexOfKey(list, other[ITEM_KEY]) : -1;
     for (let i = at - 1; i >= 0; i--) {
-        const before = order[i];
-        const index = isPlainRecord(before) ? indexOfKey(list, before[ITEM_KEY]) : -1;
+        const index = indexIn(order[i]);
         if (index >= 0)
             return [...list.slice(0, index + 1), item, ...list.slice(index + 1)];
     }
-    return [item, ...list];
+    for (let i = at + 1; at > 0 && i < order.length; i++) {
+        const index = indexIn(order[i]);
+        if (index >= 0)
+            return [...list.slice(0, index), item, ...list.slice(index)];
+    }
+    return at > 0 ? [...list.slice(0, at), item, ...list.slice(at)] : [item, ...list];
 };
 const isNothing = (value) => value === undefined || isEmptyContainer(value);
 /**

package/dist/git-manager.d.ts

@@ -560,6 +560,11 @@ export declare class GitManager {
      * path. Any other failure, such as an unknown `rev`, throws.
      */
     showFile(rev: string, filePath: string): Promise<string | undefined>;
+    /**
+     * The text of the blob `sha`, `'too-large'` when it is over `maxBytes`, or `undefined` when this
+     * clone has no such blob. Any other failure throws.
+     */
+    readBlob(sha: string, maxBytes: number): Promise<string | 'too-large' | undefined>;
     ensureAuthor(author: {
         name: string;
         email: string;
@@ -569,6 +574,7 @@ export declare class GitManager {
     ensureRemote(remoteUrl: string): Promise<void>;
     hasUncommittedChanges(): Promise<boolean>;
     getUncommittedFiles(): Promise<string[]>;
+    /** The remote's URL as configured; `git remote -v`'s listing would split a path with a space. */
     getRemoteUrl(): Promise<string | undefined>;
     /**
      * Excludes `pattern` (e.g. `.canopy-meta/`) from this workspace's git, so it

package/dist/git-manager.js

@@ -1763,6 +1763,36 @@ export class GitManager {
             throw err;
         }
     }
+    /**
+     * The text of the blob `sha`, `'too-large'` when it is over `maxBytes`, or `undefined` when this
+     * clone has no such blob. Any other failure throws.
+     */
+    async readBlob(sha, maxBytes) {
+        if (!/^(?:[0-9a-f]{40}|[0-9a-f]{64})$/.test(sha))
+            return undefined;
+        let sizeText;
+        try {
+            sizeText = (await this.git.raw(['cat-file', '-s', '--end-of-options', sha])).trim();
+        }
+        catch (err) {
+            // LC_ALL=C (gitChildEnv), so git's own wording is stable to match.
+            if (/could not get object info|Not a valid object name/.test(getErrorMessage(err))) {
+                return undefined;
+            }
+            throw err;
+        }
+        // simple-git resolves "" when git exits non-zero without writing to stderr, so anything but
+        // digits is a failed read rather than an empty blob.
+        if (!/^\d+$/.test(sizeText))
+            throw new Error(`git cat-file -s ${sha} printed no size`);
+        const size = Number(sizeText);
+        if (size > maxBytes)
+            return 'too-large';
+        const text = await this.git.raw(['cat-file', 'blob', '--end-of-options', sha]);
+        if (size > 0 && text === '')
+            throw new Error(`git cat-file blob ${sha} printed nothing`);
+        return text;
+    }
     async ensureAuthor(author) {
         const config = (await this.git.listConfig());
         // Verify this is a CanopyCMS-managed workspace before setting author
@@ -1819,10 +1849,15 @@ export class GitManager {
         const status = await this.status();
         return status.files.map((f) => f.path);
     }
+    /** The remote's URL as configured; `git remote -v`'s listing would split a path with a space. */
     async getRemoteUrl() {
-        const remotes = await this.git.getRemotes(true);
-        const remote = remotes.find((r) => r.name === this.remote);
-        return remote?.refs.push || remote?.refs.fetch;
+        try {
+            const url = (await this.git.raw(['remote', 'get-url', this.remote])).trim();
+            return url === '' ? undefined : url;
+        }
+        catch {
+            return undefined;
+        }
     }
     /**
      * Excludes `pattern` (e.g. `.canopy-meta/`) from this workspace's git, so it