canopycms 0.7.0 → 0.8.0

package/dist/editor/entry-diff.js

@@ -0,0 +1,593 @@
+/**
+ * What changed in one entry between two saved states, field by field, for the "Show changes"
+ * drawer. Pure and client-safe: it walks the entry type's schema, so each change carries the
+ * labels the form shows, and lists and blocks match their items by item key (`item-keys.ts`),
+ * so a reordered item reads as moved, not as one removed and one added.
+ */
+import { diffLines, diffWordsWithSpace } from 'diff';
+import equal from 'fast-deep-equal';
+import { ITEM_KEY } from '../item-keys.js';
+import { findBodyFieldName } from '../utils/body-field.js';
+import { flattenGroupFields } from '../utils/flatten-group-fields.js';
+import { isPlainRecord, resolveBlockItem } from '../validation/field-traversal.js';
+import { listItemHeading, listItemTitle } from './fields/list-item-title.js';
+import { humanizeName, schemaLabel } from './schema-label.js';
+/** Text at most this long, on one line, gets a word diff; longer text a line diff. */
+const SHORT_TEXT = 200;
+/** Unchanged lines kept on each side of a change in a line diff. */
+const CONTEXT_LINES = 2;
+/**
+ * How long one entry's line and long-text diffing may take in all, on the editor's main thread,
+ * where jsdiff's run time grows with the square of the edits. The deadline is checked before each
+ * jsdiff call, and each call is given only the time left; past it, every such change left is
+ * shown unmarked.
+ */
+const DIFF_TIMEOUT_MS = 300;
+/**
+ * The absolute deadline for short word diffs, measured from the start of the entry. They cost
+ * about a millisecond at most for prose, a few for 200 characters of punctuation, so they get a
+ * longer budget rather than none; past it they too are shown unmarked.
+ */
+const SHORT_DIFF_TIMEOUT_MS = 1000;
+const OTHER_FIELDS_LABEL = 'Other fields';
+const LONG_TEXT_TYPES = new Set(['markdown', 'mdx', 'code']);
+/** A side's data with an md/mdx body under that side's body field, as the form holds it. */
+const formValue = (fields, side) => {
+    if (!side)
+        return undefined;
+    if (side.body === undefined)
+        return side.data;
+    return { ...side.data, [side.bodyFieldName ?? findBodyFieldName(fields)]: side.body };
+};
+const isEmpty = (value) => value === undefined ||
+    value === null ||
+    value === '' ||
+    (Array.isArray(value) && value.length === 0) ||
+    (isPlainRecord(value) && Object.keys(value).every((k) => k === ITEM_KEY || isEmpty(value[k])));
+/** `value` without item keys and empty members, so equal content compares equal. */
+const normalized = (value) => {
+    if (Array.isArray(value))
+        return value.map(normalized);
+    if (!isPlainRecord(value))
+        return value;
+    const out = {};
+    for (const [k, v] of Object.entries(value)) {
+        if (k !== ITEM_KEY && !isEmpty(v))
+            out[k] = normalized(v);
+    }
+    return out;
+};
+const sameValue = (a, b) => (isEmpty(a) && isEmpty(b)) || equal(normalized(a), normalized(b));
+const at = (parent, label, key) => ({
+    path: [...parent.path, label],
+    key: parent.key ? `${parent.key}.${key}` : key,
+});
+/** A member the schema doesn't name, under an "Other fields" crumb. */
+const otherAt = (parent, name) => ({
+    path: [...parent.path, OTHER_FIELDS_LABEL, humanizeName(name)],
+    key: `${parent.key}?${name}`,
+});
+/** The file name of an image `src`, its query and fragment dropped. */
+const fileName = (src) => {
+    const last = src.split(/[?#]/)[0].split('/').filter(Boolean).pop() ?? src;
+    try {
+        return decodeURIComponent(last);
+    }
+    catch {
+        return last;
+    }
+};
+const rawText = (value) => typeof value === 'string' ? value : (JSON.stringify(normalized(value), null, 2) ?? String(value));
+const DATE_ONLY = /^\d{4}-\d{2}-\d{2}$/;
+const ISO_DATETIME_START = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}/;
+const ISO_CHARS = /^[\d:.+\-TZ]+$/;
+/**
+ * A date as a comparison shows it: absolute, in the viewer's locale, with the time zone. The
+ * editor's dates are otherwise relative, but two relative dates can read alike while their values
+ * differ, which is the one thing a comparison must show.
+ */
+const formatDate = (iso, dateOnly, precision = 'minute') => {
+    if (dateOnly) {
+        const [year, month, day] = iso.split('-').map(Number);
+        return new Date(year, month - 1, day).toLocaleDateString(undefined, {
+            year: 'numeric',
+            month: 'short',
+            day: 'numeric',
+        });
+    }
+    return new Date(iso).toLocaleString(undefined, {
+        year: 'numeric',
+        month: 'short',
+        day: 'numeric',
+        hour: 'numeric',
+        minute: '2-digit',
+        ...(precision !== 'minute' && { second: '2-digit' }),
+        ...(precision === 'millisecond' && { fractionalSecondDigits: 3 }),
+        timeZoneName: 'short',
+    });
+};
+/** Two ISO date-time values naming one instant, however spelled: no change. Free text is not parsed. */
+const sameInstant = (field, a, b) => {
+    if (field?.type !== 'datetime' || typeof a !== 'string' || typeof b !== 'string')
+        return false;
+    const iso = (s) => DATE_ONLY.test(s) || (ISO_DATETIME_START.test(s) && ISO_CHARS.test(s));
+    if (!iso(a) || !iso(b))
+        return false;
+    const [x, y] = [Date.parse(a), Date.parse(b)];
+    return !Number.isNaN(x) && x === y;
+};
+/** Date-times in the same minute are shown to the second, in the same second to the millisecond. */
+const withSecondsWhenNeeded = (before, after) => {
+    if (before.dateOnly || after.dateOnly)
+        return;
+    const [x, y] = [Date.parse(before.iso), Date.parse(after.iso)];
+    if (Math.floor(x / 60_000) !== Math.floor(y / 60_000))
+        return;
+    const precision = Math.floor(x / 1000) === Math.floor(y / 1000) ? 'millisecond' : 'second';
+    before.text = formatDate(before.iso, false, precision);
+    after.text = formatDate(after.iso, false, precision);
+};
+/** The text a display marks word by word in a change: text values', and dates' absolute form. */
+const markableText = (value) => value?.kind === 'text' || value?.kind === 'date' ? value.text : undefined;
+class Walker {
+    constructor(referenceTitle, 
+    /** The `Date.now()` past which no more line or long-text diffs start. */
+    deadline, 
+    /** The `Date.now()` past which no more short word diffs run. */
+    wordDeadline) {
+        this.referenceTitle = referenceTitle;
+        this.deadline = deadline;
+        this.wordDeadline = wordDeadline;
+        this.changes = [];
+    }
+    /** `value` of `field`, as the drawer shows it. */
+    display(field, value) {
+        if (isEmpty(value))
+            return { kind: 'empty' };
+        if (field && 'list' in field && field.list && field.type !== 'object') {
+            const items = Array.isArray(value) ? value : [value];
+            return {
+                kind: 'list',
+                items: items.map((item) => this.display({ ...field, list: false }, item)),
+            };
+        }
+        switch (field?.type) {
+            case 'object': {
+                const objectField = field;
+                if (objectField.list && Array.isArray(value)) {
+                    return {
+                        kind: 'list',
+                        items: value.map((item) => this.record(objectField.fields, item)),
+                    };
+                }
+                return this.record(objectField.fields, value);
+            }
+            case 'block': {
+                const blockField = field;
+                const items = Array.isArray(value) ? value : [];
+                return { kind: 'list', items: items.map((item) => this.blockRecord(blockField, item)) };
+            }
+            case 'reference':
+                if (typeof value === 'string') {
+                    const title = this.referenceTitle?.(value);
+                    return { kind: 'reference', id: value, ...(title !== undefined && { title }) };
+                }
+                break;
+            case 'image':
+                if (isPlainRecord(value) && typeof value.src === 'string') {
+                    return {
+                        kind: 'image',
+                        src: value.src,
+                        name: fileName(value.src),
+                        ...(typeof value.alt === 'string' && value.alt !== '' && { alt: value.alt }),
+                    };
+                }
+                break;
+            case 'select': {
+                const option = field.options?.find((o) => (typeof o === 'string' ? o : o.value) === value);
+                if (option !== undefined) {
+                    return { kind: 'select', label: typeof option === 'string' ? option : option.label };
+                }
+                break;
+            }
+            case 'datetime':
+                if (typeof value === 'string' && !Number.isNaN(Date.parse(value))) {
+                    return DATE_ONLY.test(value)
+                        ? { kind: 'date', iso: value, text: formatDate(value, true), dateOnly: true }
+                        : { kind: 'date', iso: value, text: formatDate(value, false) };
+                }
+                break;
+            default:
+                break;
+        }
+        if (typeof value === 'string') {
+            return field && LONG_TEXT_TYPES.has(field.type)
+                ? { kind: 'text', text: value, long: true }
+                : { kind: 'text', text: value };
+        }
+        if (typeof value === 'number' && Number.isFinite(value))
+            return { kind: 'number', value };
+        if (typeof value === 'boolean')
+            return { kind: 'boolean', value };
+        return { kind: 'raw', text: rawText(value) };
+    }
+    /** A record's non-empty fields, schema fields first, then the ones it doesn't describe. */
+    record(fields, value) {
+        if (!isPlainRecord(value))
+            return this.display(undefined, value);
+        const flat = flattenGroupFields(fields);
+        const known = new Set(flat.map((f) => f.name));
+        const out = [];
+        for (const field of flat) {
+            if (!isEmpty(value[field.name])) {
+                out.push({ label: schemaLabel(field), value: this.display(field, value[field.name]) });
+            }
+        }
+        for (const [name, v] of Object.entries(value)) {
+            if (!known.has(name) && name !== ITEM_KEY && !isEmpty(v)) {
+                out.push({ label: humanizeName(name), value: this.display(undefined, v) });
+            }
+        }
+        return out.length === 0 ? { kind: 'empty' } : { kind: 'fields', fields: out };
+    }
+    blockRecord(field, item) {
+        const resolved = isPlainRecord(item) ? resolveBlockItem(field, item) : undefined;
+        return resolved ? this.record(resolved.fields, resolved.data) : this.display(undefined, item);
+    }
+    /** Compares two records by `fields`, then the members the schema doesn't name. */
+    fields(fields, before, after, where) {
+        const flat = flattenGroupFields(fields);
+        const known = new Set(flat.map((f) => f.name));
+        for (const field of flat) {
+            this.field(field, before?.[field.name], after?.[field.name], at(where, schemaLabel(field), field.name));
+        }
+        const others = new Set([...Object.keys(before ?? {}), ...Object.keys(after ?? {})]);
+        for (const name of others) {
+            if (known.has(name) || name === ITEM_KEY)
+                continue;
+            this.value(undefined, before?.[name], after?.[name], otherAt(where, name));
+        }
+    }
+    field(field, before, after, where) {
+        if (sameValue(before, after))
+            return;
+        if (field.type === 'block') {
+            this.list(before, after, where, {
+                heading: (item) => this.blockHeading(field, item),
+                compare: (b, a, itemAt) => this.block(field, b, a, itemAt),
+                display: (item) => this.blockRecord(field, item),
+            });
+            return;
+        }
+        if (field.type === 'object') {
+            const objectField = field;
+            if (objectField.list) {
+                this.list(before, after, where, {
+                    heading: (item, index) => listItemHeading(item, objectField, index),
+                    compare: (b, a, itemAt) => this.fields(objectField.fields, asRecord(b), asRecord(a), itemAt),
+                    display: (item) => this.record(objectField.fields, item),
+                });
+                return;
+            }
+            if ((isPlainRecord(before) || isEmpty(before)) && (isPlainRecord(after) || isEmpty(after))) {
+                this.fields(objectField.fields ?? [], asRecord(before), asRecord(after), where);
+                return;
+            }
+        }
+        this.value(field, before, after, where);
+    }
+    /** One leaf change: a value set, cleared or changed. */
+    value(field, before, after, where) {
+        if (sameValue(before, after) || sameInstant(field, before, after))
+            return;
+        const kind = isEmpty(before) ? 'added' : isEmpty(after) ? 'removed' : 'changed';
+        const change = { key: where.key, path: where.path, kind };
+        if (kind !== 'added')
+            change.before = this.display(field, before);
+        if (kind !== 'removed')
+            change.after = this.display(field, after);
+        // Text and dates only: a reference's id is a value, shown whole.
+        const beforeText = markableText(change.before);
+        const afterText = markableText(change.after);
+        if (beforeText !== undefined &&
+            afterText !== undefined &&
+            change.before?.kind === change.after?.kind) {
+            const long = change.after?.kind === 'text' && !!change.after.long;
+            if (change.before?.kind === 'date' && change.after?.kind === 'date') {
+                withSecondsWhenNeeded(change.before, change.after);
+            }
+            const text = textDiff(markableText(change.before) ?? beforeText, markableText(change.after) ?? afterText, long, this.deadline, this.wordDeadline);
+            if (text)
+                change.text = text;
+            else
+                change.tooLargeToMark = true;
+        }
+        if (change.before?.kind === 'image' &&
+            change.after?.kind === 'image' &&
+            change.before.alt !== undefined &&
+            change.after.alt !== undefined &&
+            change.before.alt !== change.after.alt) {
+            const alt = textDiff(change.before.alt, change.after.alt, false, this.deadline, this.wordDeadline);
+            if (alt)
+                change.altText = alt;
+        }
+        this.changes.push(change);
+    }
+    blockHeading(field, item) {
+        const record = isPlainRecord(item) ? item : {};
+        const templateName = typeof record.template === 'string' ? record.template : undefined;
+        const template = field.templates.find((t) => t.name === templateName);
+        const label = template
+            ? schemaLabel(template)
+            : templateName
+                ? humanizeName(templateName)
+                : 'Block';
+        const resolved = resolveBlockItem(field, record);
+        const title = resolved ? listItemTitle(resolved.data, { fields: resolved.fields }) : undefined;
+        return title ? `${label}: ${title}` : label;
+    }
+    block(field, before, after, where) {
+        const b = isPlainRecord(before) ? resolveBlockItem(field, before) : undefined;
+        const a = isPlainRecord(after) ? resolveBlockItem(field, after) : undefined;
+        const sameTemplate = isPlainRecord(before) && isPlainRecord(after) && before.template === after.template;
+        if (b && a && sameTemplate) {
+            this.fields(a.fields, b.data, a.data, where);
+            return;
+        }
+        if (sameValue(before, after))
+            return;
+        this.changes.push({
+            key: where.key,
+            path: where.path,
+            kind: 'changed',
+            before: this.blockRecord(field, before),
+            after: this.blockRecord(field, after),
+        });
+    }
+    /**
+     * Compares two lists item by item, matched by item key: an item on one side only is added or
+     * removed, and one whose place among the matched items changed is moved. Items keep their
+     * order relative to each other when they are on the longest common run of the two orders,
+     * so moving one item marks that item alone.
+     */
+    list(before, after, where, item) {
+        const bItems = Array.isArray(before) ? before : [];
+        const aItems = Array.isArray(after) ? after : [];
+        const keyOf = (value, index, side) => isPlainRecord(value) && typeof value[ITEM_KEY] === 'string'
+            ? value[ITEM_KEY]
+            : `${side}#${index}`;
+        const bKeys = bItems.map((v, i) => keyOf(v, i, 'before'));
+        const aKeys = aItems.map((v, i) => keyOf(v, i, 'after'));
+        const bIndex = new Map(bKeys.map((k, i) => [k, i]));
+        const aSet = new Set(aKeys);
+        const shared = aKeys.filter((k) => bIndex.has(k));
+        const stayed = longestCommonRun(bKeys.filter((k) => aSet.has(k)), shared);
+        aItems.forEach((value, index) => {
+            const key = aKeys[index];
+            const from = bIndex.get(key);
+            // A matched item is named as it was at the base, so a change to its title doesn't rename
+            // the path to it.
+            const itemAt = at(where, from === undefined ? item.heading(value, index) : item.heading(bItems[from], from), key);
+            if (from === undefined) {
+                this.changes.push({
+                    key: itemAt.key,
+                    path: itemAt.path,
+                    kind: 'added',
+                    item: true,
+                    after: item.display(value),
+                });
+                return;
+            }
+            if (!stayed.has(key)) {
+                this.changes.push({
+                    key: `${itemAt.key}#moved`,
+                    path: itemAt.path,
+                    kind: 'moved',
+                    item: true,
+                    before: { kind: 'position', position: from + 1, of: bItems.length },
+                    after: { kind: 'position', position: index + 1, of: aItems.length },
+                });
+            }
+            item.compare(bItems[from], value, itemAt);
+        });
+        bItems.forEach((value, index) => {
+            const key = bKeys[index];
+            if (aSet.has(key))
+                return;
+            const itemAt = at(where, item.heading(value, index), key);
+            this.changes.push({
+                key: itemAt.key,
+                path: itemAt.path,
+                kind: 'removed',
+                item: true,
+                before: item.display(value),
+            });
+        });
+    }
+}
+const asRecord = (value) => isPlainRecord(value) ? value : undefined;
+/**
+ * The keys on a longest common subsequence of `a` and `b`, two orders of the same distinct keys.
+ * With distinct keys that is a longest increasing run of `b`'s positions read in `a`'s order,
+ * found in O(n log n) by patience sorting, so a list of thousands of items stays quick.
+ */
+const longestCommonRun = (a, b) => {
+    const position = new Map(b.map((key, i) => [key, i]));
+    const seq = a.map((key) => position.get(key) ?? -1);
+    // tails[n]: the index in `seq` of the smallest last value of an increasing run of length n+1.
+    const tails = [];
+    const previous = new Array(seq.length).fill(-1);
+    for (let i = 0; i < seq.length; i++) {
+        let lo = 0;
+        let hi = tails.length;
+        while (lo < hi) {
+            const mid = (lo + hi) >> 1;
+            if (seq[tails[mid]] < seq[i])
+                lo = mid + 1;
+            else
+                hi = mid;
+        }
+        if (lo > 0)
+            previous[i] = tails[lo - 1];
+        tails[lo] = i;
+    }
+    const out = new Set();
+    for (let i = tails.length > 0 ? tails[tails.length - 1] : -1; i >= 0; i = previous[i]) {
+        out.add(a[i]);
+    }
+    return out;
+};
+const WHITESPACE = /^\s+$/;
+/**
+ * jsdiff's changes as parts. A gap of whitespace widened or narrowed comes back as the old gap
+ * removed and the new one added; it is kept as their common start, then only the net change.
+ */
+const toParts = (changes) => {
+    const parts = [];
+    for (let i = 0; i < changes.length; i++) {
+        const c = changes[i];
+        const next = changes[i + 1];
+        if (next &&
+            c.removed !== next.removed &&
+            (c.removed || c.added) &&
+            (next.removed || next.added) &&
+            WHITESPACE.test(c.value) &&
+            WHITESPACE.test(next.value)) {
+            const [removed, added] = c.removed ? [c.value, next.value] : [next.value, c.value];
+            const shorter = removed.length < added.length ? removed : added;
+            const longer = shorter === removed ? added : removed;
+            if (longer.startsWith(shorter)) {
+                parts.push({ value: shorter });
+                const rest = longer.slice(shorter.length);
+                parts.push(shorter === removed ? { value: rest, added: true } : { value: rest, removed: true });
+                i++;
+                continue;
+            }
+        }
+        parts.push({
+            value: c.value,
+            ...(c.added && { added: true }),
+            ...(c.removed && { removed: true }),
+        });
+    }
+    return parts;
+};
+/** A side of a changed row that kept no text: a blank line, marked, so the row says so. */
+const sideParts = (parts, mark) => parts.some((p) => p.value !== '')
+    ? parts
+    : [mark === 'removed' ? { value: '', removed: true } : { value: '', added: true }];
+const splitLines = (value) => {
+    const lines = value.split('\n');
+    if (lines[lines.length - 1] === '')
+        lines.pop();
+    return lines;
+};
+/**
+ * The difference between two texts. Short single-line text is diffed by word; anything else by
+ * line, a removed line paired with the added line in its place diffed by word inside, and runs
+ * of unchanged lines cut to {@link CONTEXT_LINES} beside each change. Words are diffed with
+ * whitespace as tokens (`diffWordsWithSpace`): `diffWords` gives an unchanged run the new
+ * text's spacing, so one side read back from its parts would not be the text it was.
+ * Undefined once `deadline` (a `Date.now()`) passes: no line diff starts after it. A short word
+ * diff runs until the later `wordDeadline`.
+ * @internal Exported for tests.
+ */
+export function textDiff(before, after, long = false, deadline = Date.now() + DIFF_TIMEOUT_MS, wordDeadline = Date.now() + SHORT_DIFF_TIMEOUT_MS) {
+    // jsdiff restarts its clock on each call, so each is given only what is left of the budget.
+    const timeLeft = () => {
+        const left = deadline - Date.now();
+        return left > 0 ? { timeout: left } : undefined;
+    };
+    const withoutEnd = (text) => (text.endsWith('\n') ? text.slice(0, -1) : text);
+    if (before !== after && withoutEnd(before) === withoutEnd(after)) {
+        return { mode: 'endLineBreak', added: after.endsWith('\n') };
+    }
+    const short = !long &&
+        !before.includes('\n') &&
+        !after.includes('\n') &&
+        before.length <= SHORT_TEXT &&
+        after.length <= SHORT_TEXT;
+    if (short) {
+        return Date.now() < wordDeadline
+            ? { mode: 'words', parts: toParts(diffWordsWithSpace(before, after)) }
+            : undefined;
+    }
+    const rows = [];
+    const budget = timeLeft();
+    const changes = budget && diffLines(before, after, budget);
+    if (!changes)
+        return undefined;
+    for (let i = 0; i < changes.length; i++) {
+        const change = changes[i];
+        if (!change.added && !change.removed) {
+            for (const text of splitLines(change.value))
+                rows.push({ kind: 'same', text });
+            continue;
+        }
+        const removed = change.removed ? splitLines(change.value) : [];
+        const next = changes[i + 1];
+        const added = change.removed && next?.added
+            ? splitLines(next.value)
+            : change.added
+                ? splitLines(change.value)
+                : [];
+        if (change.removed && next?.added)
+            i++;
+        const paired = Math.min(removed.length, added.length);
+        for (let n = 0; n < paired; n++) {
+            const pairBudget = timeLeft();
+            const changed = pairBudget && diffWordsWithSpace(removed[n], added[n], pairBudget);
+            if (!changed)
+                return undefined;
+            const words = toParts(changed);
+            rows.push({
+                kind: 'change',
+                before: sideParts(words.filter((p) => !p.added), 'removed'),
+                after: sideParts(words.filter((p) => !p.removed), 'added'),
+            });
+        }
+        for (const text of removed.slice(paired))
+            rows.push({ kind: 'change', before: [{ value: text, removed: true }] });
+        for (const text of added.slice(paired))
+            rows.push({ kind: 'change', after: [{ value: text, added: true }] });
+    }
+    return { mode: 'lines', rows: withContext(rows) };
+}
+/** `lines` with each run of unchanged lines cut to the context beside its changes. */
+const withContext = (lines) => {
+    const out = [];
+    for (let i = 0; i < lines.length;) {
+        if (lines[i].kind !== 'same') {
+            out.push(lines[i++]);
+            continue;
+        }
+        let end = i;
+        while (end < lines.length && lines[end].kind === 'same')
+            end++;
+        const keepBefore = i === 0 ? 0 : CONTEXT_LINES;
+        const keepAfter = end === lines.length ? 0 : CONTEXT_LINES;
+        if (end - i <= keepBefore + keepAfter + 1) {
+            out.push(...lines.slice(i, end));
+        }
+        else {
+            out.push(...lines.slice(i, i + keepBefore));
+            out.push({ kind: 'skipped', count: end - i - keepBefore - keepAfter });
+            out.push(...lines.slice(end - keepAfter, end));
+        }
+        i = end;
+    }
+    return out;
+};
+/** The entry's changes between `before` and `after`, in schema order. */
+export function computeEntryDiff({ fields, before, after, referenceTitle, }) {
+    // One budget for the whole entry: see DIFF_TIMEOUT_MS and SHORT_DIFF_TIMEOUT_MS.
+    const started = Date.now();
+    const walker = new Walker(referenceTitle, started + DIFF_TIMEOUT_MS, started + SHORT_DIFF_TIMEOUT_MS);
+    const root = { path: [], key: '' };
+    if (before && after && before.entryType !== after.entryType) {
+        walker.value(undefined, humanizeName(before.entryType), humanizeName(after.entryType), at(root, 'Entry type', '$entryType'));
+    }
+    walker.fields(fields, formValue(fields, before), formValue(fields, after), root);
+    const changes = walker.changes;
+    return { changes, formattingOnly: !!before && !!after && changes.length === 0 };
+}

package/dist/editor/hooks/create-branch-request.d.ts

@@ -8,12 +8,22 @@ import { type CanopyApiClient } from '../../api/client.js';
 export declare const CREATE_BRANCH_DEADLINE_MS: number;
 /** @internal Exported for tests. */
 export declare const CREATE_TIMED_OUT_MESSAGE = "Creating the branch didn't finish (the server timed out). It's safe to try again.";
+/** The typed name cannot be created: the create form shows `refusal` in place, with no toast. */
+export interface CreateRefusal {
+    refusal: string;
+}
 export type CreateBranchOutcome = {
     kind: 'created';
     branch: BranchListItem | undefined;
-} | {
+}
+/**
+ * `refused`: the server refused this name (`BRANCH_NAME_REFUSED`), or the listing a busy or
+ * unanswered create settles on holds another user's branch of it. Retrying it cannot pass.
+ */
+ | {
     kind: 'failed';
     message: string;
+    refused?: true;
 };
 /**
  * Create a branch. Past the deadline, after an error page from in front of the API, or after a

package/dist/editor/hooks/create-branch-request.js

@@ -1,7 +1,7 @@
 import { isCreatorsRecentBranch } from '../../api/branch-create-window.js';
 import { isApiTimeoutError, isNonApiResponse } from '../../api/client.js';
 import { GATEWAY_MAX_TIMEOUT_MS } from '../../api/request-deadline.js';
-import { sanitizeBranchName } from '../../paths/branch-name.js';
+import { parseCreatedBranchName } from '../../paths/validation.js';
 /**
  * @internal Exported for tests. Past the gateway's limit, so its 504 lands first, and under
  * `REQUEST_TIMEOUT_MS.long`. The limit comes from `request-deadline` directly: a test that mocks
@@ -32,8 +32,11 @@ export async function requestBranchCreate(apiClient, body, userId, deadlineMs =
     if (isNonApiResponse(result))
         return settle(apiClient, body.branch, userId, CREATE_TIMED_OUT_MESSAGE);
     const message = result.error || 'Failed to create branch';
-    return result.status === 503
-        ? settle(apiClient, body.branch, userId, message)
+    if (result.status === 503)
+        return settle(apiClient, body.branch, userId, message);
+    // Only a refusal of the name carries this code; any other failure is the toast's to report.
+    return result.code === 'BRANCH_NAME_REFUSED'
+        ? { kind: 'failed', message, refused: true }
         : { kind: 'failed', message };
 }
 /** A same-named branch the server would not answer this create with is a name conflict. */
@@ -43,15 +46,22 @@ async function settle(apiClient, requested, userId, message) {
         return { kind: 'failed', message };
     if (isCreatorsRecentBranch(listed, userId))
         return { kind: 'created', branch: listed };
-    return { kind: 'failed', message: `A branch named "${listed.name}" already exists` };
+    return {
+        kind: 'failed',
+        message: `A branch named “${listed.shortName ?? listed.name}” already exists`,
+        refused: true,
+    };
 }
+/** The listed namespace branch (short name not its whole name) that `requested` creates. */
 async function findListedBranch(apiClient, requested) {
-    const name = sanitizeBranchName(requested);
+    const created = parseCreatedBranchName(requested);
+    if (!created.ok)
+        return undefined;
     try {
         const listing = await apiClient.branches.list();
         if (!listing.ok)
             return undefined;
-        return listing.data?.branches.find((branch) => sanitizeBranchName(branch.name) === name);
+        return listing.data?.branches.find((branch) => branch.shortName !== branch.name && branch.shortName === created.shortName);
     }
     catch {
         return undefined;