@formicoidea/labre-core 0.45.0 → 0.46.0

package/dist/_pkgs/affine-block-callout/commands/turn-callout-into.d.ts

@@ -0,0 +1,43 @@
+import { CalloutBlockModel } from '../../affine-model/index.js';
+import { type Command } from '../../std/index.js';
+import { type BlockModel, type Store } from '../../store/index.js';
+/**
+ * The selected callouts "Turn into → <text kind>" would unwrap, or none at all.
+ *
+ * Decided BEFORE anything is written, and all-or-nothing: if one callout
+ * cannot be converted, none is (#468). A callout cannot be when its parent
+ * does not accept the target flavour (a code block under a database row),
+ * or when a grandchild could not live under the block its own parent becomes
+ * — and a code block keeps no children at all, so a callout whose content
+ * has nested blocks is not turned into code (the merge would drop them).
+ * Anything that is not a callout is skipped, and a callout nested in another
+ * selected callout moves with it rather than being converted twice.
+ */
+export declare function calloutUnwrapTargets(store: Store, models: BlockModel[], flavour: string): CalloutBlockModel[];
+/**
+ * "Turn into → <text kind>" on a selected callout (#468): the exact inverse of
+ * `turnIntoCalloutCommand`. The callout is a HUB whose own `text` is unused
+ * and whose words live in its children, so the conversion UNWRAPS: each child
+ * becomes a block of the target kind at the callout's place, in order, its
+ * own children moved under it; a target of `affine:code` merges a callout's
+ * children into one code block, the way `mergeToCodeModel` merges a
+ * selection; an empty callout yields one empty block. The callout's emoji is
+ * dropped with it — it belongs to the frame being removed.
+ *
+ * Add first, prove with `getModelById`, delete only after (#418, #423): every
+ * new block is built before anything moves, and if one cannot be, the ones
+ * already built are deleted and every callout stays as it was. Only then are
+ * the grandchildren moved (validated up front by `calloutUnwrapTargets`) and
+ * the callouts deleted. The lifted blocks are therefore NEW blocks carrying
+ * the text, like the paragraph `turnIntoCalloutCommand` creates, while the
+ * grandchildren keep their identity.
+ */
+export declare const turnCalloutIntoCommand: Command<{
+    models: BlockModel[];
+    flavour: string;
+    props?: {
+        type?: string;
+    };
+}, {
+    updatedBlocks: BlockModel[];
+}>;

package/dist/_pkgs/affine-block-callout/commands/turn-callout-into.js

@@ -0,0 +1,109 @@
+import { CalloutBlockModel } from '../../affine-model/index.js';
+import { matchModels } from '../../affine-shared/utils/index.js';
+import { BlockSelection } from '../../std/index.js';
+import { Text } from '../../store/index.js';
+const isAncestor = (store, ancestor, block) => {
+    for (let at = store.getParent(block); at; at = store.getParent(at)) {
+        if (at === ancestor)
+            return true;
+    }
+    return false;
+};
+/**
+ * The selected callouts "Turn into → <text kind>" would unwrap, or none at all.
+ *
+ * Decided BEFORE anything is written, and all-or-nothing: if one callout
+ * cannot be converted, none is (#468). A callout cannot be when its parent
+ * does not accept the target flavour (a code block under a database row),
+ * or when a grandchild could not live under the block its own parent becomes
+ * — and a code block keeps no children at all, so a callout whose content
+ * has nested blocks is not turned into code (the merge would drop them).
+ * Anything that is not a callout is skipped, and a callout nested in another
+ * selected callout moves with it rather than being converted twice.
+ */
+export function calloutUnwrapTargets(store, models, flavour) {
+    const { schema } = store;
+    const callouts = models.filter((model) => matchModels(model, [CalloutBlockModel]));
+    const outermost = callouts.filter(callout => !callouts.some(other => isAncestor(store, other, callout)));
+    const feasible = outermost.every(callout => {
+        const parent = store.getParent(callout);
+        if (!parent || !schema.isValid(flavour, parent.flavour))
+            return false;
+        return callout.children.every(child => flavour === 'affine:code'
+            ? child.children.length === 0
+            : child.children.every(grandchild => schema.isValid(grandchild.flavour, flavour)));
+    });
+    return feasible ? outermost : [];
+}
+/**
+ * "Turn into → <text kind>" on a selected callout (#468): the exact inverse of
+ * `turnIntoCalloutCommand`. The callout is a HUB whose own `text` is unused
+ * and whose words live in its children, so the conversion UNWRAPS: each child
+ * becomes a block of the target kind at the callout's place, in order, its
+ * own children moved under it; a target of `affine:code` merges a callout's
+ * children into one code block, the way `mergeToCodeModel` merges a
+ * selection; an empty callout yields one empty block. The callout's emoji is
+ * dropped with it — it belongs to the frame being removed.
+ *
+ * Add first, prove with `getModelById`, delete only after (#418, #423): every
+ * new block is built before anything moves, and if one cannot be, the ones
+ * already built are deleted and every callout stays as it was. Only then are
+ * the grandchildren moved (validated up front by `calloutUnwrapTargets`) and
+ * the callouts deleted. The lifted blocks are therefore NEW blocks carrying
+ * the text, like the paragraph `turnIntoCalloutCommand` creates, while the
+ * grandchildren keep their identity.
+ */
+export const turnCalloutIntoCommand = (ctx, next) => {
+    const { std, models, flavour, props } = ctx;
+    const store = std.store;
+    if (store.readonly)
+        return;
+    const callouts = calloutUnwrapTargets(store, models, flavour);
+    if (callouts.length === 0)
+        return;
+    store.captureSync();
+    const created = [];
+    const adoptions = [];
+    const add = (callout, text) => {
+        const parent = store.getParent(callout);
+        // Inserted right before the callout, so the blocks keep their order.
+        const block = parent
+            ? store.getModelById(store.addBlock(flavour, { ...props, ...(text && { text }) }, parent, parent.children.indexOf(callout)))
+            : null;
+        if (block)
+            created.push(block);
+        return block;
+    };
+    // `addBlock` returns an id even for a block the store refused, so only
+    // `getModelById` proves the block exists (`add` above).
+    const build = (callout) => {
+        const sources = callout.children;
+        if (flavour === 'affine:code') {
+            const joined = sources
+                .map(source => source.text?.toString())
+                .filter(Boolean)
+                .join('\n');
+            return add(callout, new Text(joined)) !== null;
+        }
+        if (sources.length === 0)
+            return add(callout) !== null;
+        return sources.every(source => {
+            const block = add(callout, source.text?.clone());
+            if (block && source.children.length > 0)
+                adoptions.push([source.children, block]);
+            return block !== null;
+        });
+    };
+    if (!callouts.every(build)) {
+        created.forEach(block => store.deleteBlock(block));
+        return;
+    }
+    adoptions.forEach(([children, block]) => store.moveBlocks(children, block));
+    callouts.forEach(callout => store.deleteBlock(callout));
+    // The gesture started from a block selection (the callout's handle), so it
+    // ends on one; deferred a frame so the new blocks have rendered.
+    requestAnimationFrame(() => {
+        std.selection.setGroup('note', created.map(block => std.selection.create(BlockSelection, { blockId: block.id })));
+    });
+    return next({ updatedBlocks: created });
+};

package/dist/_pkgs/affine-block-callout/configs/toolbar.d.ts

@@ -0,0 +1,65 @@
+import { ActionPlacement, type ToolbarContext } from '../../affine-shared/services/index.js';
+/**
+ * The callout's block toolbar, opened by its drag handle (#468). Without a
+ * module for `affine:callout` the toolbar widget shows no row for a selected
+ * callout at all, so a callout could not be converted back. Copy, duplicate
+ * and delete are the note row's, restricted to the block selection — except
+ * that they take the selection in `flat` mode, descendants included, where
+ * the note row's Duplicate takes `highest`: a callout is a hub, and drafted
+ * without its children it would copy as an empty frame.
+ *
+ * Centred above the block (`top`) like the note row a paragraph or a code
+ * block opens; without a placement of its own the widget sets a block's row
+ * at `top-start`, which left the callout's row hanging off its left edge.
+ */
+export declare const calloutToolbarConfig: {
+    readonly placement: "top";
+    readonly actions: [{
+        readonly id: "a.conversions";
+        readonly when: (ctx: ToolbarContext) => boolean;
+        readonly content: (ctx: ToolbarContext) => import("lit-html").TemplateResult<1> | null;
+    }, {
+        readonly variant?: "destructive";
+        readonly content?: ((cx: ToolbarContext) => import("lit-html").TemplateResult | null) | (import("lit-html").TemplateResult | null);
+        readonly label?: string;
+        readonly icon?: import("lit-html").TemplateResult;
+        readonly active?: ((cx: ToolbarContext) => boolean) | boolean;
+        readonly disabled?: ((cx: ToolbarContext) => boolean) | boolean;
+        readonly placement?: ActionPlacement;
+        readonly tooltip?: string | import("lit-html").TemplateResult;
+        readonly score?: number;
+        readonly when?: ((cx: ToolbarContext) => boolean) | boolean;
+        readonly priority?: number;
+        readonly labelWording?: import("../../affine-shared/services/index.js").ChromeWording;
+        readonly showLabel?: boolean;
+        readonly tooltipWording?: import("../../affine-shared/services/index.js").ChromeWording;
+        readonly run?: (cx: ToolbarContext) => void;
+        readonly id: "g.comment";
+    }, {
+        readonly placement: ActionPlacement.More;
+        readonly id: "a.clipboard";
+        readonly actions: [{
+            readonly id: "copy";
+            readonly labelWording: import("../../affine-shared/services/index.js").ChromeWording;
+            readonly icon: import("lit-html").TemplateResult<1>;
+            readonly run: ({ chain, host, std }: ToolbarContext) => void;
+        }, {
+            readonly id: "duplicate";
+            readonly labelWording: import("../../affine-shared/services/index.js").ChromeWording;
+            readonly icon: import("lit-html").TemplateResult<1>;
+            readonly run: (ctx: ToolbarContext) => void;
+        }];
+        readonly when: (ctx: ToolbarContext) => boolean;
+    }, {
+        readonly placement: ActionPlacement.More;
+        readonly id: "c.delete";
+        readonly actions: [{
+            readonly id: "delete";
+            readonly labelWording: import("../../affine-shared/services/index.js").ChromeWording;
+            readonly icon: import("lit-html").TemplateResult<1>;
+            readonly variant: "destructive";
+            readonly run: ({ chain }: ToolbarContext) => void;
+        }];
+        readonly when: (ctx: ToolbarContext) => boolean;
+    }];
+};

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

@@ -0,0 +1,178 @@
+import { toast } from '../../affine-components/toast/index.js';
+import { EditorChevronDown } from '../../affine-components/toolbar/index.js';
+import { CalloutBlockModel } from '../../affine-model/index.js';
+import { textConversionConfigs } from '../../affine-rich-text/index.js';
+import { copySelectedModelsCommand, deleteSelectedModelsCommand, draftSelectedModelsCommand, duplicateSelectedModelsCommand, getSelectedModelsCommand, } from '../../affine-shared/commands/index.js';
+import { ActionPlacement, blockCommentToolbarButton, TOAST_COPIED_TO_CLIPBOARD, TOOLBAR_CONVERSIONS_ARIA, TOOLBAR_COPY, TOOLBAR_DELETE, TOOLBAR_DUPLICATE, TOOLBAR_TURN_INTO, translateKey, } from '../../affine-shared/services/index.js';
+import { matchModels } from '../../affine-shared/utils/index.js';
+import { CopyIcon, DeleteIcon, DuplicateIcon, FontIcon, } from '@blocksuite/icons/lit';
+import { html } from 'lit';
+import { repeat } from 'lit/directives/repeat.js';
+import { calloutUnwrapTargets, turnCalloutIntoCommand, } from '../commands/turn-callout-into.js';
+/** The block-selected callouts — the row only opens on a block selection. */
+const selectedCallouts = ({ chain }) => {
+    const [ok, { selectedModels = [] }] = chain
+        .pipe(getSelectedModelsCommand, { types: ['block'], mode: 'highest' })
+        .run();
+    return ok
+        ? selectedModels.filter(model => matchModels(model, [CalloutBlockModel]))
+        : [];
+};
+/**
+ * "Turn into" on a callout (#468): the text kinds of the note's own row, minus
+ * the divider (which is not a conversion of a block's words), each offered
+ * only when `calloutUnwrapTargets` says the whole conversion can complete —
+ * a refusal is an absent entry, never a click that does nothing.
+ *
+ * Like the note row, which offers "Turn into" on a paragraph or a code block
+ * only once it holds words (`isFormatSupported`), the entry waits for the
+ * callout to hold some: an empty callout shows the "⋮" menu alone (PO
+ * recette of #468, for one behaviour across blocks).
+ */
+const conversionsAction = {
+    id: 'a.conversions',
+    when: ctx => !ctx.readonly,
+    content(ctx) {
+        const { std, store } = ctx;
+        const callouts = selectedCallouts(ctx);
+        if (callouts.length === 0)
+            return null;
+        const holdsWords = callouts.some(callout => callout.children.some(child => (child.text?.length ?? 0) > 0));
+        if (!holdsWords)
+            return null;
+        const conversions = textConversionConfigs.filter(({ flavour }) => flavour !== 'affine:divider' &&
+            calloutUnwrapTargets(store, callouts, flavour).length > 0);
+        if (conversions.length === 0)
+            return null;
+        return html `
+      <editor-menu-button
+        .contentPadding="${'8px'}"
+        .button=${html `
+          <editor-icon-button
+            aria-label="${translateKey(std, ...TOOLBAR_CONVERSIONS_ARIA)}"
+            .tooltip="${translateKey(std, ...TOOLBAR_TURN_INTO)}"
+          >
+            ${FontIcon()} ${EditorChevronDown}
+          </editor-icon-button>
+        `}
+      >
+        <div data-size="large" data-orientation="vertical">
+          ${repeat(conversions, item => item.name, ({ flavour, type, name, nameWording, icon }) => {
+            const label = nameWording
+                ? translateKey(std, ...nameWording)
+                : name;
+            return html `
+                <editor-menu-action
+                  aria-label=${label}
+                  @click=${() => std.command.exec(turnCalloutIntoCommand, {
+                models: callouts,
+                flavour,
+                ...(type && { props: { type } }),
+            })}
+                >
+                  ${icon}<span class="label">${label}</span>
+                </editor-menu-action>
+              `;
+        })}
+        </div>
+      </editor-menu-button>
+    `;
+    },
+};
+/**
+ * The callout's block toolbar, opened by its drag handle (#468). Without a
+ * module for `affine:callout` the toolbar widget shows no row for a selected
+ * callout at all, so a callout could not be converted back. Copy, duplicate
+ * and delete are the note row's, restricted to the block selection — except
+ * that they take the selection in `flat` mode, descendants included, where
+ * the note row's Duplicate takes `highest`: a callout is a hub, and drafted
+ * without its children it would copy as an empty frame.
+ *
+ * Centred above the block (`top`) like the note row a paragraph or a code
+ * block opens; without a placement of its own the widget sets a block's row
+ * at `top-start`, which left the callout's row hanging off its left edge.
+ */
+export const calloutToolbarConfig = {
+    placement: 'top',
+    actions: [
+        conversionsAction,
+        {
+            id: 'g.comment',
+            ...blockCommentToolbarButton,
+        },
+        {
+            placement: ActionPlacement.More,
+            id: 'a.clipboard',
+            actions: [
+                {
+                    id: 'copy',
+                    labelWording: TOOLBAR_COPY,
+                    icon: CopyIcon(),
+                    run({ chain, host, std }) {
+                        // `flat`, not `highest`: the callout's words are its children,
+                        // and the draft keeps only the children that are selected too.
+                        const [ok] = chain
+                            .pipe(getSelectedModelsCommand, {
+                            types: ['block'],
+                            mode: 'flat',
+                        })
+                            .pipe(draftSelectedModelsCommand)
+                            .pipe(copySelectedModelsCommand)
+                            .run();
+                        if (!ok)
+                            return;
+                        toast(host, translateKey(std, ...TOAST_COPIED_TO_CLIPBOARD));
+                    },
+                },
+                {
+                    id: 'duplicate',
+                    labelWording: TOOLBAR_DUPLICATE,
+                    icon: DuplicateIcon(),
+                    run(ctx) {
+                        const { chain, store } = ctx;
+                        // The copy lands right after the (last) callout. Said explicitly:
+                        // the command's default anchors on the LAST selected model, which
+                        // in `flat` mode is one of the callout's descendants.
+                        const last = selectedCallouts(ctx).at(-1);
+                        const parentModel = last && store.getParent(last);
+                        if (!last || !parentModel)
+                            return;
+                        store.captureSync();
+                        // `flat`, not `highest`, for the same reason as Copy: a callout
+                        // drafted without its children duplicates as an empty frame.
+                        chain
+                            .pipe(getSelectedModelsCommand, {
+                            types: ['block'],
+                            mode: 'flat',
+                        })
+                            .pipe(duplicateSelectedModelsCommand, {
+                            parentModel,
+                            index: parentModel.children.indexOf(last) + 1,
+                        })
+                            .run();
+                    },
+                },
+            ],
+            when: ctx => !ctx.flags.isNative(),
+        },
+        {
+            placement: ActionPlacement.More,
+            id: 'c.delete',
+            actions: [
+                {
+                    id: 'delete',
+                    labelWording: TOOLBAR_DELETE,
+                    icon: DeleteIcon(),
+                    variant: 'destructive',
+                    run({ chain }) {
+                        chain
+                            .pipe(getSelectedModelsCommand, { types: ['block'] })
+                            .pipe(deleteSelectedModelsCommand)
+                            .run();
+                    },
+                },
+            ],
+            when: ctx => !ctx.flags.isNative(),
+        },
+    ],
+};

package/dist/_pkgs/affine-block-callout/view.js

@@ -1,10 +1,12 @@
 import { ViewExtensionProvider, } from '../affine-ext-loader/index.js';
 import { TextConversionEntryExtension } from '../affine-rich-text/index.js';
+import { ToolbarModuleExtension } from '../affine-shared/services/index.js';
 import { SlashMenuConfigExtension } from '../affine-widget-slash-menu/index.js';
-import { BlockViewExtension, FlavourExtension } from '../std/index.js';
+import { BlockFlavourIdentifier, BlockViewExtension, FlavourExtension, } from '../std/index.js';
 import { literal } from 'lit/static-html.js';
 import { CalloutKeymapExtension } from './callout-keymap.js';
 import { calloutSlashMenuConfig } from './configs/slash-menu.js';
+import { calloutToolbarConfig } from './configs/toolbar.js';
 import { calloutTurnIntoEntry } from './configs/turn-into.js';
 import { effects } from './effects.js';
 export class CalloutViewExtension extends ViewExtensionProvider {
@@ -24,6 +26,10 @@ export class CalloutViewExtension extends ViewExtensionProvider {
             CalloutKeymapExtension,
             SlashMenuConfigExtension('affine:callout', calloutSlashMenuConfig),
             TextConversionEntryExtension(calloutTurnIntoEntry),
+            ToolbarModuleExtension({
+                id: BlockFlavourIdentifier('affine:callout'),
+                config: calloutToolbarConfig,
+            }),
         ]);
     }
 }

package/dist/_pkgs/affine-block-frame/commands.d.ts

@@ -0,0 +1,27 @@
+import type { AnyCommandDescriptor } from '../std/index.js';
+import { z } from 'zod';
+/**
+ * The frames' commands, `owner: 'core'`: a frame belongs to no framework, and
+ * `'core'` owners are exempt from the id-prefix rule (ADR 0008).
+ *
+ * They live here and not beside the selection pane's: `blocks/surface` cannot
+ * import `blocks/frame` (the dependency runs the other way), and the action
+ * reads the frame manager's presentation order.
+ */
+export declare const reorderFramesParams: z.ZodObject<{
+    /** The frames to move, as one block, keeping their relative order. */
+    ids: z.ZodArray<z.ZodString, "many">;
+    /**
+     * The frame they land directly BEFORE in the presentation order; `null`
+     * puts them at the end.
+     */
+    before: z.ZodNullable<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    before: string | null;
+    ids: string[];
+}, {
+    before: string | null;
+    ids: string[];
+}>;
+export type ReorderFramesParams = z.infer<typeof reorderFramesParams>;
+export declare const frameCommands: AnyCommandDescriptor[];

package/dist/_pkgs/affine-block-frame/commands.js

@@ -0,0 +1,49 @@
+import { z } from 'zod';
+import { reorderFramePresentation } from './frame-order.js';
+/**
+ * The frames' commands, `owner: 'core'`: a frame belongs to no framework, and
+ * `'core'` owners are exempt from the id-prefix rule (ADR 0008).
+ *
+ * They live here and not beside the selection pane's: `blocks/surface` cannot
+ * import `blocks/frame` (the dependency runs the other way), and the action
+ * reads the frame manager's presentation order.
+ */
+export const reorderFramesParams = z.object({
+    /** The frames to move, as one block, keeping their relative order. */
+    ids: z.array(z.string().min(1)).min(1),
+    /**
+     * The frame they land directly BEFORE in the presentation order; `null`
+     * puts them at the end.
+     */
+    before: z.string().min(1).nullable(),
+});
+/**
+ * Reorder the presentation (ADR 0034). The frame panel's drag, the
+ * presentation toolbar's order menu and a host's own slide panel all run it
+ * through `runCommand`, so the read-only refusal, the no-op check and the one
+ * undo step live in the action, once.
+ */
+const reorderFrames = {
+    id: 'canvas.frame.reorder',
+    owner: 'core',
+    kind: 'action',
+    labelKey: 'com.labre.command.canvas.frame.reorder',
+    labelFallback: 'Reorder frames',
+    descriptionKey: 'com.labre.command.canvas.frame.reorder.description',
+    descriptionFallback: 'Move frames before another frame in the presentation order, or to its end.',
+    // Agent only: without an explicit target there is nothing to say where.
+    surfaces: ['agent'],
+    scope: 'edgeless',
+    defaultKeys: { mac: [], other: [] },
+    availability: 'editable',
+    params: reorderFramesParams,
+    run: (std, _invocation, params) => {
+        const parsed = reorderFramesParams.safeParse(params);
+        if (!parsed.success) {
+            console.error('canvas.frame.reorder: invalid params', parsed.error);
+            return;
+        }
+        reorderFramePresentation(std, parsed.data.ids, parsed.data.before);
+    },
+};
+export const frameCommands = [reorderFrames];

package/dist/_pkgs/affine-block-frame/frame-manager.d.ts

@@ -24,9 +24,9 @@ export declare class EdgelessFrameManager extends GfxExtension {
     private readonly _pendingAdoptions;
     private _pendingAdoptionTicks;
     /**
-     * Get all sorted frames by presentation orderer,
-     * the legacy frame that uses `index` as presentation order
-     * will be put at the beginning of the array.
+     * Every frame, in presentation order (`framePresentationComparator`): by
+     * `presentationIndex`, and the legacy frames that have none AFTER the keyed
+     * ones, ordered among themselves by their stacking `index`.
      */
     get frames(): FrameBlockModel[];
     constructor(gfx: GfxController);
@@ -35,7 +35,7 @@ export declare class EdgelessFrameManager extends GfxExtension {
             index: string;
             presentationIndex?: string;
         };
-    }>(a: T, b: T): 0 | 1 | -1;
+    }>(a: T, b: T): 1 | 0 | -1;
     private _addChildrenToLegacyFrame;
     private _addFrameBlock;
     /**
@@ -124,8 +124,13 @@ export declare class EdgelessFrameManager extends GfxExtension {
     getFrameFromPoint([x, y]: IVec, ignoreFrames?: FrameBlockModel[]): FrameBlockModel | null;
     getParentFrame(element: GfxModel): FrameBlockModel | null;
     /**
-     * This method will populate `presentationIndex` for all legacy frames,
-     * and keep the orderer of the legacy frames.
+     * Give a `presentationIndex` to legacy frames, keeping their order — but
+     * only on a document where NO frame has one yet. The comparator sorts
+     * keyless frames AFTER keyed ones, so as soon as one frame is keyed the first
+     * frame is keyed and this returns at once: a mix of keyed and keyless frames
+     * is left as it is. In practice a loaded frame always carries a key (the
+     * schema's default is written on load), so this only acts on a hand-built
+     * store. Idempotent; writes through the props proxy.
      */
     refreshLegacyFrameOrder(): void;
     removeAllChildrenFromFrame(frame: FrameBlockModel): void;

package/dist/_pkgs/affine-block-frame/frame-manager.js

@@ -90,9 +90,9 @@ export const EdgelessFrameManagerIdentifier = GfxExtensionIdentifier('frame-mana
 export class EdgelessFrameManager extends GfxExtension {
     static { this.key = 'frame-manager'; }
     /**
-     * Get all sorted frames by presentation orderer,
-     * the legacy frame that uses `index` as presentation order
-     * will be put at the beginning of the array.
+     * Every frame, in presentation order (`framePresentationComparator`): by
+     * `presentationIndex`, and the legacy frames that have none AFTER the keyed
+     * ones, ordered among themselves by their stacking `index`.
      */
     get frames() {
         return Object.values(this.gfx.doc.blocks.value)
@@ -484,8 +484,13 @@ export class EdgelessFrameManager extends GfxExtension {
         return container && isFrameBlock(container) ? container : null;
     }
     /**
-     * This method will populate `presentationIndex` for all legacy frames,
-     * and keep the orderer of the legacy frames.
+     * Give a `presentationIndex` to legacy frames, keeping their order — but
+     * only on a document where NO frame has one yet. The comparator sorts
+     * keyless frames AFTER keyed ones, so as soon as one frame is keyed the first
+     * frame is keyed and this returns at once: a mix of keyed and keyless frames
+     * is left as it is. In practice a loaded frame always carries a key (the
+     * schema's default is written on load), so this only acts on a hand-built
+     * store. Idempotent; writes through the props proxy.
      */
     refreshLegacyFrameOrder() {
         const frames = this.frames.splice(0, this.frames.length);

package/dist/_pkgs/affine-block-frame/frame-order.d.ts

@@ -0,0 +1,43 @@
+import type { BlockStdScope } from '../std/index.js';
+/**
+ * The one write of the frames' PRESENTATION order (ADR 0034): the
+ * order a presentation walks the frames in, held by each frame's
+ * `presentationIndex` — a fractional key, never a position.
+ *
+ * Why one function: two sites wrote that order by hand — the frame panel's
+ * drag and the presentation toolbar's order menu — each its own way, neither
+ * refusing a read-only document, and the panel taking its undo checkpoint
+ * AFTER the write, so the reorder merged into whatever gesture came before.
+ * Both now reach this through `canvas.frame.reorder`, and so does a host's own
+ * slide panel: the guards below live here, once.
+ *
+ * Mirrors the selection pane's `reorderPaneElement`
+ * (`blocks/surface/src/extensions/selection-pane/actions.ts`):
+ *
+ * - refuses on a read-only document before reading anything else;
+ * - writes nothing when nothing would change — an unchanged write is an empty
+ *   undo step, and an undo that "does nothing" reads as a broken undo;
+ * - takes ONE `captureSync()` first, so one gesture is one undo step, the
+ *   legacy keys `refreshLegacyFrameOrder` may write included (it writes in
+ *   the same capture window, so it joins the gesture's step);
+ * - writes through `gfx.updateElement`, which is `store.updateBlock` for a
+ *   frame — not the CRUD `updateElement`, which would also record the moved
+ *   frame's props as the flavour's last-used props.
+ */
+/**
+ * Move the frames `ids` so they sit, as one block, directly BEFORE `before` in
+ * the presentation order — `null` puts them at the end. The moved frames keep
+ * their current relative order, whatever order `ids` lists them in. Answers
+ * whether anything was written.
+ *
+ * Refused, with nothing written: a read-only document; an id that is not a
+ * frame of this document; a `before` that is one of the moved frames, or not
+ * a frame; and a target that is where the frames already are.
+ *
+ * Each moved frame gets a key between its new neighbours, so only the moved
+ * frames are written and nothing else shifts. Two neighbours with equal (or
+ * inverted) keys cannot be split — `generateKeyBetweenV2` throws on them, and
+ * the model's default key is random per frame, so a pasted, imported or
+ * hand-made document can carry them: refusing beats throwing in a drop.
+ */
+export declare function reorderFramePresentation(std: BlockStdScope, ids: readonly string[], before: string | null): boolean;