@formicoidea/labre-core 0.43.1 → 0.46.0

package/dist/_pkgs/affine-block-note/translations.js

@@ -143,10 +143,6 @@ export const NOTE_DISPLAY_MODE_LABEL = [
     'com.labre.note.display-mode.mode-label',
     'Mode',
 ];
-export const NOTE_DISPLAY_MODE_TOOLTIP = [
-    'com.labre.note.display-mode.tooltip',
-    'Display mode',
-];
 /** An alias (L7 dedupe): the same word as {@link DISPLAY_MODE_BOTH}, one key. */
 export const NOTE_DISPLAY_MODE_BOTH = DISPLAY_MODE_BOTH;
 /** An alias (L7 dedupe): the same word as {@link DISPLAY_MODE_EDGELESS}, one key. */
@@ -158,7 +154,10 @@ export const NOTE_DISPLAY_MODE_PAGE = DISPLAY_MODE_PAGE;
  * `TOAST_NOTE_REMOVED_FROM_PAGE` (already in `chrome.ts`); its opposite gets
  * its own key here. Each toast's BODY bakes in the trailing "Find it in the
  * TOC…" sentence rather than composing it at the call site — one full
- * sentence per key, never a fragment plus a suffix.
+ * sentence per key, never a fragment plus a suffix. That sentence promises the
+ * "View in TOC" link, which exists only when the host registers an outline
+ * panel (`OutlinePanelExtension`, ADR 0034); each body therefore has a
+ * `body-no-toc` twin without it, picked when no outline answers.
  */
 export const NOTE_TOAST_DISPLAYED_IN_PAGE_MODE = [
     'com.labre.note.toast.displayed-in-page-mode',
@@ -172,6 +171,14 @@ export const NOTE_TOAST_ADDED_TO_PAGE_BODY = [
     'com.labre.note.toast.added-to-page.body',
     'Content added to your document. Find it in the TOC for quick navigation.',
 ];
+export const NOTE_TOAST_REMOVED_FROM_PAGE_BODY_NO_TOC = [
+    'com.labre.note.toast.removed-from-page.body-no-toc',
+    'Content removed from your document.',
+];
+export const NOTE_TOAST_ADDED_TO_PAGE_BODY_NO_TOC = [
+    'com.labre.note.toast.added-to-page.body-no-toc',
+    'Content added to your document.',
+];
 export const NOTE_TOAST_VIEW_IN_TOC = [
     'com.labre.note.toast.view-in-toc',
     'View in Toc',
@@ -237,10 +244,11 @@ export const NOTE_WORDINGS = [
     NOTE_STYLE_CUSTOM_COLOR,
     NOTE_STYLE_PANEL_LABEL,
     NOTE_DISPLAY_MODE_LABEL,
-    NOTE_DISPLAY_MODE_TOOLTIP,
     NOTE_TOAST_DISPLAYED_IN_PAGE_MODE,
     NOTE_TOAST_REMOVED_FROM_PAGE_BODY,
     NOTE_TOAST_ADDED_TO_PAGE_BODY,
+    NOTE_TOAST_REMOVED_FROM_PAGE_BODY_NO_TOC,
+    NOTE_TOAST_ADDED_TO_PAGE_BODY_NO_TOC,
     NOTE_TOAST_VIEW_IN_TOC,
     NOTE_TOOLBAR_DISPLAY_IN_PAGE,
     NOTE_TOOLBAR_DISPLAYED_IN_PAGE,

package/dist/_pkgs/affine-block-root/configs/toolbar.js

@@ -5,7 +5,7 @@ import { toast } from '../../affine-components/toast/index.js';
 import { EditorChevronDown } from '../../affine-components/toolbar/index.js';
 import { deleteTextCommand, formatBlockCommand, formatNativeCommand, formatTextCommand, isFormatSupported, textFormatConfigs, } from '../../affine-inline-preset/index.js';
 import { EmbedLinkedDocBlockSchema, EmbedSyncedDocBlockSchema, } from '../../affine-model/index.js';
-import { textConversionConfigs } from '../../affine-rich-text/index.js';
+import { textConversionConfigs, TextConversionEntryIdentifier, } from '../../affine-rich-text/index.js';
 import { copySelectedModelsCommand, deleteSelectedModelsCommand, draftSelectedModelsCommand, duplicateSelectedModelsCommand, getBlockSelectionsCommand, getImageSelectionsCommand, getSelectedBlocksCommand, getSelectedModelsCommand, getTextSelectionCommand, } from '../../affine-shared/commands/index.js';
 import { ActionPlacement, blockCommentToolbarButton, TOAST_COPIED_TO_CLIPBOARD, TOOLBAR_COPY, TOOLBAR_DELETE, TOOLBAR_DUPLICATE, translateKey, } from '../../affine-shared/services/index.js';
 import { tableViewMeta } from '../../data-view/view-presets/index.js';
@@ -42,6 +42,11 @@ const conversionsActionGroup = {
             })
                 .run();
         };
+        // Conversions a gated block package registers from its own view extension
+        // (#418): absent when its flag is off, so never listed statically here.
+        const contributed = [
+            ...std.provider.getAll(TextConversionEntryIdentifier).values(),
+        ].filter(entry => entry.when(std, selectedModels));
         return {
             content: html `
         <editor-menu-button
@@ -65,6 +70,17 @@ const conversionsActionGroup = {
                   ${icon}<span class="label">${name}</span>
                 </editor-menu-action>
               `)}
+            ${repeat(contributed, entry => entry.flavour, entry => {
+                const label = translateKey(std, ...entry.nameWording);
+                return html `
+                  <editor-menu-action
+                    aria-label=${label}
+                    @click=${() => entry.run(std, selectedModels)}
+                  >
+                    ${entry.icon}<span class="label">${label}</span>
+                  </editor-menu-action>
+                `;
+            })}
           </div>
         </editor-menu-button>
       `,
@@ -255,12 +271,41 @@ export const builtinToolbarConfig = {
                                 blockId: block.model.id,
                             })));
                         }
-                        chain
+                        // The copy lands right after the last selected block that no other
+                        // selected block contains. Said explicitly: the command's default
+                        // anchors on the LAST selected model, which in `flat` mode below
+                        // is a descendant — and `highest` keeps a block-selected child of
+                        // a block-selected parent too, so with both selected the copy went
+                        // INSIDE the parent, after the child.
+                        const [, { selectedModels: highest = [] }] = chain
                             .pipe(getSelectedModelsCommand, {
                             types: ['block', 'image'],
                             mode: 'highest',
                         })
-                            .pipe(duplicateSelectedModelsCommand)
+                            .run();
+                        const selected = new Set(highest);
+                        const hasSelectedAncestor = (model) => {
+                            for (let at = store.getParent(model); at; at = store.getParent(at))
+                                if (selected.has(at))
+                                    return true;
+                            return false;
+                        };
+                        const last = highest.findLast(model => !hasSelectedAncestor(model));
+                        const parentModel = last && store.getParent(last);
+                        if (!last || !parentModel)
+                            return;
+                        // `flat`, not `highest`: `draftSelectedModelsCommand` keeps a
+                        // drafted block's children only when they are selected too, so a
+                        // paragraph duplicated alone lost its nested children.
+                        chain
+                            .pipe(getSelectedModelsCommand, {
+                            types: ['block', 'image'],
+                            mode: 'flat',
+                        })
+                            .pipe(duplicateSelectedModelsCommand, {
+                            parentModel,
+                            index: parentModel.children.indexOf(last) + 1,
+                        })
                             .run();
                     },
                 },

package/dist/_pkgs/affine-block-root/edgeless/clipboard/clipboard.js

@@ -7,7 +7,7 @@ import { BookmarkStyles, DEFAULT_NOTE_HEIGHT, DEFAULT_NOTE_WIDTH, FrameBlockMode
 import { ClipboardAdapter, decodeClipboardBlobs, ImageProxyService, } from '../../../affine-shared/adapters/index.js';
 import { CANVAS_EXPORT_IGNORE_TAGS, EMBED_CARD_HEIGHT, EMBED_CARD_WIDTH, } from '../../../affine-shared/consts/index.js';
 import { EmbedOptionProvider, ParseDocUrlProvider, TelemetryProvider, } from '../../../affine-shared/services/index.js';
-import { convertToPng, isInsidePageEditor, isTopLevelBlock, isUrlInClipboard, matchModels, referenceToNode, } from '../../../affine-shared/utils/index.js';
+import { convertToPng, isInsidePageEditor, isTopLevelBlock, isUrlInClipboard, matchModels, normalizeCanvasExportColors, referenceToNode, } from '../../../affine-shared/utils/index.js';
 import { DisposableGroup } from '../../../global/disposable/index.js';
 import { BlockSuiteError, ErrorCode } from '../../../global/exceptions/index.js';
 import { Bound, getCommonBound, Vec, } from '../../../global/gfx/index.js';
@@ -336,6 +336,7 @@ export class EdgelessClipboardController extends PageClipboard {
                 }
             },
             onclone: async function (documentClone, element) {
+                normalizeCanvasExportColors(documentClone, element);
                 // html2canvas can't support transform feature
                 element.style.setProperty('transform', 'none');
                 const layer = documentClone.querySelector('.affine-edgeless-layer');

package/dist/_pkgs/affine-block-root/edgeless/clipboard/command.js

@@ -1,9 +1,11 @@
-import { EdgelessClipboardConfigIdentifier, EdgelessCRUDIdentifier, SurfaceGroupLikeModel, } from '../../../affine-block-surface/index.js';
+import { isFrameBlock } from '../../../affine-block-frame/index.js';
+import { EdgelessClipboardConfigIdentifier, EdgelessCRUDIdentifier, resolveCreationLayer, writeModelLayer, } from '../../../affine-block-surface/index.js';
 import { Bound } from '../../../global/gfx/index.js';
 import { assertType } from '../../../global/utils/index.js';
-import { GfxControllerIdentifier, SortOrder, } from '../../../std/gfx/index.js';
+import { DEFAULT_LAYER_ID, GfxControllerIdentifier, ownLayerOf, } from '../../../std/gfx/index.js';
 import { BlockSnapshotSchema } from '../../../store/index.js';
 import { createCanvasElement } from './canvas.js';
+import { pastedIndexes, pastedParentage } from './paste-order.js';
 import { createNewPresentationIndexes, edgelessElementsBoundFromRawData, } from './utils.js';
 export const createElementsFromClipboardDataCommand = (ctx, next) => {
     const { std, elementsRawData } = ctx;
@@ -33,60 +35,116 @@ export const createElementsFromClipboardDataCommand = (ctx, next) => {
         const blockModels = [];
         const canvasElements = [];
         const allElements = [];
-        for (const data of elementsRawData) {
-            const { data: blockSnapshot } = BlockSnapshotSchema.safeParse(data);
-            if (blockSnapshot) {
-                const oldId = blockSnapshot.id;
-                const config = std.getOptional(EdgelessClipboardConfigIdentifier(blockSnapshot.flavour));
-                if (!config)
-                    continue;
-                if (typeof blockSnapshot.props.index !== 'string') {
-                    console.error(`Block(id: ${oldId}) does not have index property`);
-                    continue;
-                }
-                const originalIndex = blockSnapshot.props.index;
-                if (typeof blockSnapshot.props.xywh !== 'string') {
-                    console.error(`Block(id: ${oldId}) does not have xywh property`);
-                    continue;
-                }
-                assertType(blockSnapshot.props);
-                blockSnapshot.props.xywh = getNewXYWH(blockSnapshot.props.xywh);
-                blockSnapshot.props.lockedBySelf = false;
-                const newId = await config.createBlock(blockSnapshot, context);
-                if (!newId)
-                    continue;
-                const block = std.store.getBlock(newId);
-                if (!block)
-                    continue;
-                assertType(block.model);
-                blockModels.push(block.model);
-                allElements.push(block.model);
-                context.oldToNewIdMap.set(oldId, newId);
-                context.originalIndexes.set(oldId, originalIndex);
-            }
-            else {
-                assertType(data);
-                const oldId = data.id;
+        // Read before anything is created: `createCanvasElement` rewrites a
+        // group's `children` with the new ids.
+        const oldParents = pastedParentage(elementsRawData);
+        // Decided before anything is created too, so that a canvas element is
+        // born with its final index: written afterwards, each index moved an
+        // element already on the board, through the layer manager, one by one.
+        const newIndexes = pastedIndexes(std, elementsRawData, oldParents, context.originalIndexes);
+        const blockIndexes = new Map();
+        // What each block's snapshot asked for, read before its config creates
+        // it; applied in the final transaction (`keepSourceLayerAndHide`).
+        const blockRequests = new Map();
+        // Canvas elements are written in as few transactions as the blocks allow,
+        // so a peer receives one update for a run of them instead of one per
+        // element (plus one per index fix-up). A block cannot join: its config's
+        // `createBlock` may be async (notes, texts, images and attachments go
+        // through the transformer, which awaits), and a Yjs transaction cannot
+        // span an `await`. So the run of canvas elements before a block is written
+        // first — the block may reference them (a frame's `childElementIds`) —
+        // and the last run is written together with the final indexes.
+        // ponytail: a block still costs its own transactions; a two-phase config
+        // contract (async prepare, then a sync write) is the upgrade path.
+        const pendingCanvasElements = [];
+        const seen = new Set();
+        const createPendingCanvasElements = () => {
+            for (const data of pendingCanvasElements) {
+                data.index = newIndexes.get(data.id) ?? data.index;
                 const element = createCanvasElement(std, data, context, getNewXYWH(data.xywh));
                 if (!element)
                     continue;
                 canvasElements.push(element);
                 allElements.push(element);
-                context.oldToNewIdMap.set(oldId, element.id);
-                context.originalIndexes.set(oldId, element.index);
+                context.oldToNewIdMap.set(data.id, element.id);
             }
-        }
-        // remap old id to new id for the original index
-        const oldIds = [...context.originalIndexes.keys()];
-        oldIds.forEach(oldId => {
-            const newId = context.oldToNewIdMap.get(oldId);
-            const originalIndex = context.originalIndexes.get(oldId);
-            if (newId && originalIndex) {
-                context.originalIndexes.set(newId, originalIndex);
-                context.originalIndexes.delete(oldId);
+            pendingCanvasElements.length = 0;
+        };
+        // One gesture, one undo step: close whatever the previous gesture left
+        // open in the undo manager's capture window.
+        // ponytail: the paste's own transactions then merge only while each ends
+        // within that window (500 ms) of the one before, so a block whose creation
+        // takes longer splits the step; the two-phase contract above removes the
+        // ceiling (the budget spec measures it on 406 elements).
+        std.store.captureSync();
+        for (const data of elementsRawData) {
+            // Clipboard data written before `sortEdgelessElements` deduplicated can
+            // list one element twice; the first copy is the one its container maps.
+            if (seen.has(data.id))
+                continue;
+            seen.add(data.id);
+            const { data: blockSnapshot } = BlockSnapshotSchema.safeParse(data);
+            if (!blockSnapshot) {
+                assertType(data);
+                pendingCanvasElements.push(data);
+                continue;
+            }
+            if (pendingCanvasElements.length > 0) {
+                std.store.transact(createPendingCanvasElements);
+            }
+            const oldId = blockSnapshot.id;
+            const config = std.getOptional(EdgelessClipboardConfigIdentifier(blockSnapshot.flavour));
+            if (!config)
+                continue;
+            if (typeof blockSnapshot.props.index !== 'string') {
+                console.error(`Block(id: ${oldId}) does not have index property`);
+                continue;
+            }
+            if (typeof blockSnapshot.props.xywh !== 'string') {
+                console.error(`Block(id: ${oldId}) does not have xywh property`);
+                continue;
             }
+            assertType(blockSnapshot.props);
+            blockSnapshot.props.xywh = getNewXYWH(blockSnapshot.props.xywh);
+            blockSnapshot.props.lockedBySelf = false;
+            const requested = {
+                layer: blockSnapshot.props.layer,
+                hiddenForEveryone: blockSnapshot.props.hiddenForEveryone,
+            };
+            const newId = await config.createBlock(blockSnapshot, context);
+            if (!newId)
+                continue;
+            const block = std.store.getBlock(newId);
+            if (!block)
+                continue;
+            assertType(block.model);
+            blockRequests.set(block.model, requested);
+            blockModels.push(block.model);
+            allElements.push(block.model);
+            context.oldToNewIdMap.set(oldId, newId);
+            const index = newIndexes.get(oldId);
+            if (index)
+                blockIndexes.set(block.model, index);
+        }
+        std.store.transact(() => {
+            createPendingCanvasElements();
+            const parents = new Map();
+            oldParents.forEach((oldParent, oldChild) => {
+                const child = context.oldToNewIdMap.get(oldChild);
+                const parent = context.oldToNewIdMap.get(oldParent);
+                if (child && parent)
+                    parents.set(child, parent);
+            });
+            releaseChildrenFromAdoptingFrames(std, allElements, parents);
+            // A block config chooses its own index (a frame takes the top of the
+            // board, a note the transformer's): set the planned one afterwards.
+            const crud = std.get(EdgelessCRUDIdentifier);
+            blockIndexes.forEach((index, block) => {
+                if (block.index !== index)
+                    crud.updateElement(block.id, { index });
+            });
+            blockRequests.forEach((requested, block) => keepSourceLayerAndHide(std, block, requested));
         });
-        updatePastedElementsIndex(std, allElements, context.originalIndexes);
         return {
             canvasElements: canvasElements,
             blockModels: blockModels,
@@ -96,42 +154,62 @@ export const createElementsFromClipboardDataCommand = (ctx, next) => {
         createdElementsPromise: runner(),
     });
 };
-function updatePastedElementsIndex(std, elements, originalIndexes) {
-    const gfx = std.get(GfxControllerIdentifier);
-    const crud = std.get(EdgelessCRUDIdentifier);
-    function compare(a, b) {
-        if (a instanceof SurfaceGroupLikeModel && a.hasDescendant(b)) {
-            return SortOrder.BEFORE;
-        }
-        else if (b instanceof SurfaceGroupLikeModel && b.hasDescendant(a)) {
-            return SortOrder.AFTER;
-        }
-        else {
-            const aGroups = a.groups;
-            const bGroups = b.groups;
-            let i = 1;
-            let aGroup = aGroups.at(-i);
-            let bGroup = bGroups.at(-i);
-            while (aGroup === bGroup && aGroup) {
-                ++i;
-                aGroup = aGroups.at(-i);
-                bGroup = bGroups.at(-i);
+/**
+ * A pasted or duplicated block gets what a pasted element gets from
+ * `crud.addElement`, which forwards every serialized prop (ADR 0031 §6 and
+ * "What stays loadable"): its `layer` when it names a layer of this surface,
+ * else the active one, and its `hiddenForEveryone`. Most
+ * `EdgelessClipboardConfig.createBlock` rebuild the block from a handful of
+ * the snapshot's props (frame, image, attachment, bookmark, the embeds…), so
+ * a duplicate fell in the active layer and came back visible. The rule is
+ * applied once here, for every config, rather than in each of them; nothing
+ * is written when the config already carried both.
+ *
+ * `requested` is read BEFORE `createBlock`: the snapshot-pasting configs
+ * stamp `snapshot.props` in place, and an explicit default-layer request from
+ * a clone gesture (`prepareCloneData`) is gone from it afterwards. Called
+ * inside the paste's final transaction, beside the index fix-ups, so it adds
+ * no update of its own.
+ */
+function keepSourceLayerAndHide(std, model, requested) {
+    const layer = resolveCreationLayer(std, requested.layer) ?? DEFAULT_LAYER_ID;
+    if (layer !== (ownLayerOf(model) ?? DEFAULT_LAYER_ID)) {
+        writeModelLayer(std, model, layer);
+    }
+    if (requested.hiddenForEveryone === true &&
+        model.props.hiddenForEveryone !== true) {
+        std.store.updateBlock(model, { hiddenForEveryone: true });
+    }
+}
+/**
+ * The paste creates children before their container (post-order), and the
+ * frame manager adopts whatever is created inside a frame — a block at once on
+ * `blockUpdated`, a canvas element a microtask later, which an `await` between
+ * two creations lets run. So a child of a pasted group or frame can already sit
+ * in the frame under the paste point when its own container claims it, and a
+ * child claimed twice is copied twice by the next duplicate.
+ *
+ * The paste knows the parentage it is writing; the frame's guess does not
+ * survive it. Each pasted container's children leave any other frame. The
+ * container itself is untouched, so a pasted group still lands in the frame it
+ * was dropped on.
+ */
+function releaseChildrenFromAdoptingFrames(std, created, parents) {
+    if (parents.size === 0)
+        return;
+    const frames = std.store
+        .getModelsByFlavour('affine:frame')
+        .filter(isFrameBlock);
+    if (frames.length === 0)
+        return;
+    for (const child of created) {
+        const container = parents.get(child.id);
+        if (!container)
+            continue;
+        for (const frame of frames) {
+            if (frame.id !== container && frame.hasChild(child)) {
+                frame.removeChild(child);
             }
-            aGroup = aGroup ?? a;
-            bGroup = bGroup ?? b;
-            return originalIndexes.get(aGroup.id) === originalIndexes.get(bGroup.id)
-                ? SortOrder.SAME
-                : originalIndexes.get(aGroup.id) < originalIndexes.get(bGroup.id)
-                    ? SortOrder.BEFORE
-                    : SortOrder.AFTER;
         }
     }
-    const idxGenerator = gfx.layer.createIndexGenerator();
-    const sortedElements = elements.sort(compare);
-    sortedElements.forEach(ele => {
-        const newIndex = idxGenerator();
-        crud.updateElement(ele.id, {
-            index: newIndex,
-        });
-    });
 }

package/dist/_pkgs/affine-block-root/edgeless/clipboard/paste-order.d.ts

@@ -0,0 +1,21 @@
+import type { BlockStdScope } from '../../../std/index.js';
+import { type SerializedElement } from '../../../std/gfx/index.js';
+import type { BlockSnapshot } from '../../../store/index.js';
+/**
+ * Child id → container id, as the pasted data spells it: a group's or a mind
+ * map's `children`, a frame's `childElementIds`.
+ *
+ * The paste reads its parentage from here and not from the models: a canvas
+ * container written in the final transaction registers its children (its
+ * `childIds`, `getGroup`) only when that transaction ends, so inside it a
+ * model would answer "no parent".
+ */
+export declare function pastedParentage(elementsRawData: (SerializedElement | BlockSnapshot)[]): Map<string, string>;
+/**
+ * The fresh indexes of the pasted elements, by their id in the pasted data: on
+ * top of the board, in the order they had where they were copied from — a
+ * container before its children, and otherwise by the original index of the
+ * topmost pasted ancestor (then of the next one down, then of the element
+ * itself). The original indexes are recorded in `originalIndexes`.
+ */
+export declare function pastedIndexes(std: BlockStdScope, elementsRawData: (SerializedElement | BlockSnapshot)[], parents: Map<string, string>, originalIndexes: Map<string, string>): Map<string, string>;

package/dist/_pkgs/affine-block-root/edgeless/clipboard/paste-order.js

@@ -0,0 +1,85 @@
+import { GfxControllerIdentifier, SortOrder, } from '../../../std/gfx/index.js';
+/*
+ * The paste's stacking order, decided on the PASTED DATA before any model
+ * exists. Its own module, which the package does not re-export, so that
+ * `paste-order-parity.unit.spec.ts` can hold its copy of the canvas'
+ * ancestor rule to `compareLayer` without making it API.
+ */
+/**
+ * Child id → container id, as the pasted data spells it: a group's or a mind
+ * map's `children`, a frame's `childElementIds`.
+ *
+ * The paste reads its parentage from here and not from the models: a canvas
+ * container written in the final transaction registers its children (its
+ * `childIds`, `getGroup`) only when that transaction ends, so inside it a
+ * model would answer "no parent".
+ */
+export function pastedParentage(elementsRawData) {
+    const parents = new Map();
+    for (const data of elementsRawData) {
+        const children = 'flavour' in data ? data.props.childElementIds : data.children;
+        if (!children || typeof children !== 'object')
+            continue;
+        for (const childId of Object.keys(children)) {
+            parents.set(childId, data.id);
+        }
+    }
+    return parents;
+}
+/**
+ * The fresh indexes of the pasted elements, by their id in the pasted data: on
+ * top of the board, in the order they had where they were copied from — a
+ * container before its children, and otherwise by the original index of the
+ * topmost pasted ancestor (then of the next one down, then of the element
+ * itself). The original indexes are recorded in `originalIndexes`.
+ */
+export function pastedIndexes(std, elementsRawData, parents, originalIndexes) {
+    for (const data of elementsRawData) {
+        const index = 'flavour' in data ? data.props.index : data.index;
+        if (typeof index === 'string' && !originalIndexes.has(data.id)) {
+            originalIndexes.set(data.id, index);
+        }
+    }
+    // Pasted ancestors, nearest first — the order `GfxModel.groups` uses.
+    const ancestors = new Map();
+    for (const id of originalIndexes.keys()) {
+        const chain = [];
+        for (let parent = parents.get(id); parent && !chain.includes(parent); parent = parents.get(parent)) {
+            chain.push(parent);
+        }
+        ancestors.set(id, chain);
+    }
+    function compare(a, b) {
+        const aGroups = ancestors.get(a) ?? [];
+        const bGroups = ancestors.get(b) ?? [];
+        if (bGroups.includes(a)) {
+            return SortOrder.BEFORE;
+        }
+        else if (aGroups.includes(b)) {
+            return SortOrder.AFTER;
+        }
+        let i = 1;
+        let aGroup = aGroups.at(-i);
+        let bGroup = bGroups.at(-i);
+        while (aGroup === bGroup && aGroup) {
+            ++i;
+            aGroup = aGroups.at(-i);
+            bGroup = bGroups.at(-i);
+        }
+        const aIndex = originalIndexes.get(aGroup ?? a);
+        const bIndex = originalIndexes.get(bGroup ?? b);
+        return aIndex === bIndex
+            ? SortOrder.SAME
+            : aIndex < bIndex
+                ? SortOrder.BEFORE
+                : SortOrder.AFTER;
+    }
+    const nextIndex = std
+        .get(GfxControllerIdentifier)
+        .layer.createIndexGenerator();
+    const newIndexes = new Map();
+    [...originalIndexes.keys()].sort(compare).forEach(id => {
+        newIndexes.set(id, nextIndex());
+    });
+    return newIndexes;
+}

package/dist/_pkgs/affine-block-root/edgeless/edgeless-root-block.d.ts

@@ -51,6 +51,12 @@ export declare class EdgelessRootBlockComponent extends BlockComponent<RootBlock
         flavour?: boolean;
     }): () => void;
     connectedCallback(): void;
+    /**
+     * The grid follows `CanvasGrid` (ADR 0031 §11) through one attribute on
+     * the root, which both containers that paint it — this block's background
+     * and the surface container — key their `background-image: none` on.
+     */
+    private _initGrid;
     disconnectedCallback(): void;
     firstUpdated(): void;
     renderBlock(): import("lit-html").TemplateResult<1>;

package/dist/_pkgs/affine-block-root/edgeless/edgeless-root-block.js

@@ -38,7 +38,7 @@ import { isSingleMindMapNode } from '../../affine-gfx-mindmap/index.js';
 import { PanTool } from '../../affine-gfx-pointer/index.js';
 import { mountShapeTextEditor } from '../../affine-gfx-shape/index.js';
 import { NoteBlockModel, } from '../../affine-model/index.js';
-import { EditorSettingProvider, EditPropsStore, FontLoaderService, ThemeProvider, ViewportElementProvider, } from '../../affine-shared/services/index.js';
+import { CanvasGrid, EditorSettingProvider, EditPropsStore, FontLoaderService, ThemeProvider, ViewportElementProvider, } from '../../affine-shared/services/index.js';
 import { isTouchPadPinchEvent, matchModels, requestConnectedFrame, requestThrottledConnectedFrame, } from '../../affine-shared/utils/index.js';
 import { IS_WINDOWS } from '../../global/env/index.js';
 import { Bound, Point, Vec } from '../../global/gfx/index.js';
@@ -110,6 +110,11 @@ let EdgelessRootBlockComponent = (() => {
       );
     }
 
+    /* ADR 0031 §11: the grid is a setting (CanvasGrid.visible$). */
+    affine-edgeless-root[data-grid-hidden] .edgeless-background {
+      background-image: none;
+    }
+
     .edgeless-container {
       color: var(--affine-text-primary-color);
       position: relative;
@@ -347,6 +352,7 @@ let EdgelessRootBlockComponent = (() => {
         connectedCallback() {
             super.connectedCallback();
             this._initViewport();
+            this._initGrid();
             this.keyboardManager = new EdgelessPageKeyboardManager(this);
             this.handleEvent('selectionChange', () => {
                 const surface = this.host.selection.value.find((sel) => sel.is(SurfaceSelection));
@@ -359,6 +365,17 @@ let EdgelessRootBlockComponent = (() => {
                 return;
             });
         }
+        /**
+         * The grid follows `CanvasGrid` (ADR 0031 §11) through one attribute on
+         * the root, which both containers that paint it — this block's background
+         * and the surface container — key their `background-image: none` on.
+         */
+        _initGrid() {
+            this._disposables.add(effect(() => {
+                const visible = this.std.getOptional(CanvasGrid)?.visible$.value ?? true;
+                this.toggleAttribute('data-grid-hidden', !visible);
+            }));
+        }
         disconnectedCallback() {
             super.disconnectedCallback();
             if (this._resizeObserver) {

package/dist/_pkgs/affine-block-root/edgeless/utils/clone-utils.d.ts

@@ -7,6 +7,15 @@ import type { BlockSnapshot, Transformer } from '../../../store/index.js';
  * return all elements in the tree of the elements
  */
 export declare function getSortedCloneElements(elements: GfxModel[]): GfxModel[];
+/**
+ * The data a clone gesture in the same document (duplicate, alt-drag)
+ * re-creates. Each model asks for its source's layer EXPLICITLY, the default
+ * layer included (ADR 0031, amendment "A duplicate stays in its source's
+ * layer, the default one included"): a default-layer model serializes no
+ * `layer`, and "absent" would hand its copy to the viewer's active layer. A
+ * paste goes through `prepareClipboardData` instead and keeps §6's rule — it
+ * cannot tell the default layer from another document.
+ */
 export declare function prepareCloneData(elements: GfxModel[], std: BlockStdScope): (BlockSnapshot | SerializedElement)[];
 export declare function serializeElement(element: GfxModel, elements: GfxModel[], job: Transformer): SerializedElement | {
     type: "block";