@formicoidea/labre-core 0.43.1 → 0.46.0

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

@@ -12,11 +12,13 @@ export const CALLOUT_SLASH_DESCRIPTION = [
 ];
 /** The item's tooltip caption says the exact same word as its name. */
 export const CALLOUT_SLASH_CAPTION = CALLOUT_SLASH_NAME;
+/** "Turn into → Callout" names the block with the slash item's own word. */
+export const CALLOUT_TURN_INTO_NAME = CALLOUT_SLASH_NAME;
 /**
  * Every wording declared above, in declaration order — walked by
  * `PACKAGE_WORDINGS` in `packages/affine/all/src/translations.ts`. The
- * caption alias is not listed again, same rule other packages' chrome
- * aliases already follow.
+ * caption and turn-into aliases are not listed again, same rule other
+ * packages' chrome aliases already follow.
  */
 export const CALLOUT_WORDINGS = [
     CALLOUT_SLASH_NAME,

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

@@ -1,9 +1,13 @@
 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 {
     constructor() {
@@ -21,6 +25,11 @@ export class CalloutViewExtension extends ViewExtensionProvider {
             BlockViewExtension('affine:callout', literal `affine-callout`),
             CalloutKeymapExtension,
             SlashMenuConfigExtension('affine:callout', calloutSlashMenuConfig),
+            TextConversionEntryExtension(calloutTurnIntoEntry),
+            ToolbarModuleExtension({
+                id: BlockFlavourIdentifier('affine:callout'),
+                config: calloutToolbarConfig,
+            }),
         ]);
     }
 }

package/dist/_pkgs/affine-block-code/code-block-service.d.ts

@@ -6,8 +6,21 @@ export declare class CodeBlockHighlighter extends LifeCycleWatcher {
     private _darkThemeKey;
     private _lightThemeKey;
     highlighter$: Signal<HighlighterCore | null>;
+    /**
+     * In-flight grammar loads, one per language. Per instance rather than
+     * static: each editor owns its own shiki core, and a grammar loaded into
+     * another editor's core is not loaded into this one.
+     */
+    private readonly _languageLoads;
     get themeKey(): string | undefined;
     private readonly _loadTheme;
+    /**
+     * Loads a grammar into the shiki core, sharing the pending promise between
+     * concurrent callers (every code block of that language asks at once on
+     * first paint). A settled load leaves the map, so a failed one is retried
+     * on the next request.
+     */
+    loadLanguage(lang: string, input: Parameters<HighlighterCore['loadLanguage']>[0]): Promise<void>;
     mounted(): void;
     unmounted(): void;
 }

package/dist/_pkgs/affine-block-code/code-block-service.js

@@ -10,6 +10,12 @@ export class CodeBlockHighlighter extends LifeCycleWatcher {
     constructor() {
         super(...arguments);
         this.highlighter$ = signal(null);
+        /**
+         * In-flight grammar loads, one per language. Per instance rather than
+         * static: each editor owns its own shiki core, and a grammar loaded into
+         * another editor's core is not loaded into this one.
+         */
+        this._languageLoads = new Map();
         this._loadTheme = async (highlighter) => {
             const config = this.std.getOptional(CodeBlockConfigExtension.identifier);
             const darkTheme = config?.theme?.dark ?? CODE_BLOCK_DEFAULT_DARK_THEME;
@@ -27,6 +33,26 @@ export class CodeBlockHighlighter extends LifeCycleWatcher {
             ? this._darkThemeKey
             : this._lightThemeKey;
     }
+    /**
+     * Loads a grammar into the shiki core, sharing the pending promise between
+     * concurrent callers (every code block of that language asks at once on
+     * first paint). A settled load leaves the map, so a failed one is retried
+     * on the next request.
+     */
+    loadLanguage(lang, input) {
+        const pending = this._languageLoads.get(lang);
+        if (pending)
+            return pending;
+        const highlighter = this.highlighter$.peek();
+        if (!highlighter) {
+            return Promise.reject(new Error('Code block highlighter is not ready'));
+        }
+        const load = highlighter.loadLanguage(input).finally(() => {
+            this._languageLoads.delete(lang);
+        });
+        this._languageLoads.set(lang, load);
+        return load;
+    }
     mounted() {
         super.mounted();
         createHighlighterCore({

package/dist/_pkgs/affine-block-code/code-block.d.ts

@@ -32,6 +32,12 @@ export declare class CodeBlockComponent extends CaptionedBlockComponent<CodeBloc
      */
     get showLineNumbers(): boolean;
     get topContenteditableElement(): BlockComponent<import("../store/index.js").BlockModel<object>, import("../std/index.js").BlockService, string> | null;
+    /**
+     * Bumped on every highlight request: a grammar load that resolves after a
+     * newer request (another language, or plain text) must not repaint the
+     * block with its stale tokens (#416).
+     */
+    private _highlightRequestId;
     private _updateHighlightTokens;
     /**
      * Stable signal: true when the global editor setting enables line numbers.

package/dist/_pkgs/affine-block-code/code-block.js

@@ -84,6 +84,12 @@ let CodeBlockComponent = (() => {
                     ? matchedInfo.name
                     : translateKey(this.std, ...CODE_PLAIN_TEXT_LANGUAGE);
             });
+            /**
+             * Bumped on every highlight request: a grammar load that resolves after a
+             * newer request (another language, or plain text) must not repaint the
+             * block with its stale tokens (#416).
+             */
+            this._highlightRequestId = 0;
             /**
              * Stable signal: true when the global editor setting enables line numbers.
              * Defaults to true. Updated reactively by an effect in connectedCallback.
@@ -146,6 +152,7 @@ let CodeBlockComponent = (() => {
             return this.rootComponent;
         }
         _updateHighlightTokens() {
+            const requestId = ++this._highlightRequestId;
             const modelLang = this.model.props.language$.value;
             if (modelLang === null) {
                 this.highlightTokens$.value = [];
@@ -168,9 +175,11 @@ let CodeBlockComponent = (() => {
                 const code = this.model.props.text.toString();
                 const loadedLanguages = highlighter.getLoadedLanguages();
                 if (!loadedLanguages.includes(lang)) {
-                    highlighter
-                        .loadLanguage(langImport)
+                    this.highlighter
+                        .loadLanguage(lang, langImport)
                         .then(() => {
+                        if (requestId !== this._highlightRequestId)
+                            return;
                         this.highlightTokens$.value = highlighter.codeToTokensBase(code, {
                             lang,
                             theme,

package/dist/_pkgs/affine-block-code/code-toolbar/components/lang-button.js

@@ -42,7 +42,17 @@ import { css, LitElement, nothing } from 'lit';
 import { property, query } from 'lit/decorators.js';
 import { styleMap } from 'lit/directives/style-map.js';
 import { html } from 'lit/static-html.js';
-import { CODE_SEARCH_FOR_LANGUAGE } from '../../translations.js';
+import { CODE_PLAIN_TEXT_LANGUAGE, CODE_SEARCH_FOR_LANGUAGE, } from '../../translations.js';
+/**
+ * The list name of the Plain Text entry, which stands for `language: null`
+ * (#417). A colon never appears in a shiki language id, so it cannot collide
+ * with one, and no query starting with a letter matches it by name. It lives
+ * in the list and its persisted order only, never in the model.
+ */
+const PLAIN_TEXT_ITEM_NAME = ':plain-text';
+function languageOf(item) {
+    return item.name === PLAIN_TEXT_ITEM_NAME ? null : item.name;
+}
 let LanguageListButton = (() => {
     let _classSuper = WithDisposable(SignalWatcher(LitElement));
     let __langButton_decorators;
@@ -95,16 +105,29 @@ let LanguageListButton = (() => {
         connectedCallback() {
             super.connectedCallback();
             const langList = localStorage.getItem('blocksuite:code-block:lang-list');
-            if (langList) {
-                this._sortedBundledLanguages = JSON.parse(langList);
-            }
-            else {
-                this._sortedBundledLanguages = this.blockComponent.langs.map(lang => ({
+            const languages = langList
+                ? JSON.parse(langList)
+                : this.blockComponent.langs.map(lang => ({
                     label: lang.name,
                     name: lang.id,
                     aliases: lang.aliases,
                 }));
+            // A list persisted before the entry existed lacks it, and a persisted
+            // label is in the locale of the session that wrote it: keep the entry's
+            // recently-used position, refresh its words.
+            const plainText = {
+                label: translateKey(this.blockComponent.std, ...CODE_PLAIN_TEXT_LANGUAGE),
+                name: PLAIN_TEXT_ITEM_NAME,
+                aliases: ['plain', 'text', 'none'],
+            };
+            const index = languages.findIndex(item => item.name === PLAIN_TEXT_ITEM_NAME);
+            if (index === -1) {
+                languages.unshift(plainText);
+            }
+            else {
+                languages[index] = plainText;
             }
+            this._sortedBundledLanguages = languages;
             this.disposables.add(() => {
                 localStorage.setItem('blocksuite:code-block:lang-list', JSON.stringify(this._sortedBundledLanguages));
             });
@@ -169,7 +192,7 @@ let LanguageListButton = (() => {
                             sortedBundledLanguages.unshift(item);
                         }
                         this.blockComponent.store.transact(() => {
-                            this.blockComponent.model.props.language$.value = item.name;
+                            this.blockComponent.model.props.language$.value = languageOf(item);
                         });
                         const std = this.blockComponent.std;
                         const mode = std.getOptional(DocModeProvider)?.getEditorMode() ?? 'page';
@@ -183,7 +206,7 @@ let LanguageListButton = (() => {
                             control: item.name,
                         });
                     },
-                    active: item => item.name === this.blockComponent.model.props.language,
+                    active: item => languageOf(item) === this.blockComponent.model.props.language,
                     items: this._sortedBundledLanguages,
                 };
                 showPopFilterableList({

package/dist/_pkgs/affine-block-edgeless-text/edgeless-toolbar/config.d.ts

@@ -8,6 +8,17 @@ export declare const edgelessTextToolbarConfig: {
     }, {
         readonly id: "c.font-style";
         readonly content: (ctx: import("../../affine-shared/services/index.js").ToolbarContext) => import("lit-html").TemplateResult<1> | null;
+    }, {
+        readonly id: "c.text-decoration";
+        readonly when: boolean;
+        readonly actions: {
+            id: "a.underline" | "b.overline";
+            icon: import("lit-html").TemplateResult<1>;
+            tooltipWording: import("../../affine-shared/services/index.js").ChromeWording;
+            when: (ctx: import("../../affine-shared/services/index.js").ToolbarContext) => boolean;
+            active: (ctx: import("../../affine-shared/services/index.js").ToolbarContext) => boolean;
+            run: (ctx: import("../../affine-shared/services/index.js").ToolbarContext) => void;
+        }[];
     }, {
         readonly id: "d.font-size";
         readonly when: boolean;

package/dist/_pkgs/affine-block-edgeless-text/svg-painter.d.ts

@@ -0,0 +1,20 @@
+import { type BlockSvgPainter } from '../affine-block-surface/index.js';
+import { type EdgelessTextBlockModel } from '../affine-model/index.js';
+/**
+ * An edgeless text, redrawn as VECTOR text for "Export SVG" (ADR 0025,
+ * amendment of 2026-10-04).
+ *
+ * The block is DOM, so no canvas renderer paints it; this lays it out the way
+ * its CSS does, with the canvas text renderer's own font string and wrapping
+ * (`@labre/affine-gfx-text`): one line run per paragraph, its size and weight
+ * from `HEADING_SCALE` for a heading and from the 15px body otherwise, wrapped
+ * to the block's width only when the block has one (`hasMaxWidth`), then
+ * rotated about the block's centre and scaled by `scale`, as on screen.
+ *
+ * ponytail: each paragraph is drawn in the BLOCK's style — inline bold, italic,
+ * colour and links are flattened, list bullets and numbers are not drawn, and
+ * heading margins are ignored. Upgrade by walking the paragraph's deltas the
+ * way `wrapTextDeltas` does for a canvas text, when a board needs it.
+ */
+export declare const edgelessTextSvgPainter: BlockSvgPainter<EdgelessTextBlockModel>;
+export declare const EdgelessTextSvgPainterExtension: import("../store/index.js").ExtensionType;

package/dist/_pkgs/affine-block-edgeless-text/svg-painter.js

@@ -0,0 +1,76 @@
+import { BlockSvgPainterExtension, } from '../affine-block-surface/index.js';
+import { getFontString, wrapText } from '../affine-gfx-text/index.js';
+import { DefaultTheme } from '../affine-model/index.js';
+import { HEADING_SCALE } from '../affine-shared/consts/index.js';
+import { EDGELESS_TEXT_BASE_FONT_SIZE } from './edgeless-toolbar/font-size.js';
+/** `--affine-line-height` is `calc(1em + 8px)`: what a body line adds to its size. */
+const BODY_LINE_EXTRA = 8;
+/** The container's 1px border, which the text sits inside. */
+const BORDER = 1;
+/** Every paragraph and list item of the block, depth first, as plain text. */
+function runsOf(model, runs = []) {
+    for (const child of model.children) {
+        if (child.text) {
+            const type = child.props.type;
+            runs.push({
+                level: type !== undefined && type in HEADING_SCALE
+                    ? type
+                    : undefined,
+                text: child.text.toString(),
+            });
+        }
+        runsOf(child, runs);
+    }
+    return runs;
+}
+/**
+ * An edgeless text, redrawn as VECTOR text for "Export SVG" (ADR 0025,
+ * amendment of 2026-10-04).
+ *
+ * The block is DOM, so no canvas renderer paints it; this lays it out the way
+ * its CSS does, with the canvas text renderer's own font string and wrapping
+ * (`@labre/affine-gfx-text`): one line run per paragraph, its size and weight
+ * from `HEADING_SCALE` for a heading and from the 15px body otherwise, wrapped
+ * to the block's width only when the block has one (`hasMaxWidth`), then
+ * rotated about the block's centre and scaled by `scale`, as on screen.
+ *
+ * ponytail: each paragraph is drawn in the BLOCK's style — inline bold, italic,
+ * colour and links are flattened, list bullets and numbers are not drawn, and
+ * heading margins are ignored. Upgrade by walking the paragraph's deltas the
+ * way `wrapTextDeltas` does for a canvas text, when a board needs it.
+ */
+export const edgelessTextSvgPainter = (model, ctx, matrix, renderer) => {
+    const { scale, rotate, color, fontFamily, fontStyle, fontWeight, textAlign, hasMaxWidth, } = model.props;
+    const [, , w, h] = model.deserializedXYWH;
+    ctx.setTransform(matrix
+        .translate(w / 2, h / 2)
+        .rotate(rotate)
+        .translate(-w / 2, -h / 2)
+        .scale(scale));
+    const width = w / scale - 2 * BORDER;
+    const x = BORDER +
+        (textAlign === 'center' ? width / 2 : textAlign === 'right' ? width : 0);
+    ctx.fillStyle = renderer.getColorValue(color, DefaultTheme.textColor, true);
+    ctx.textAlign = textAlign;
+    ctx.textBaseline = 'middle';
+    let y = BORDER;
+    for (const { level, text } of runsOf(model)) {
+        const heading = level ? HEADING_SCALE[level] : undefined;
+        const fontSize = heading?.fontSize ?? EDGELESS_TEXT_BASE_FONT_SIZE;
+        const lineHeight = fontSize + (heading?.lineHeightExtra ?? BODY_LINE_EXTRA);
+        const font = getFontString({
+            fontStyle,
+            fontWeight: heading ? String(heading.fontWeight) : fontWeight,
+            fontSize,
+            fontFamily,
+        });
+        ctx.font = font;
+        const lines = (hasMaxWidth ? wrapText(text, font, width) : text).split('\n');
+        for (const line of lines) {
+            if (line)
+                ctx.fillText(line, x, y + lineHeight / 2);
+            y += lineHeight;
+        }
+    }
+};
+export const EdgelessTextSvgPainterExtension = BlockSvgPainterExtension('affine:edgeless-text', edgelessTextSvgPainter);

package/dist/_pkgs/affine-block-edgeless-text/view.js

@@ -5,6 +5,7 @@ import { EdgelessClipboardEdgelessTextConfig } from './edgeless-clipboard-config
 import { EdgelessTextInteraction } from './edgeless-text-block.js';
 import { edgelessTextToolbarExtension } from './edgeless-toolbar/index.js';
 import { effects } from './effects.js';
+import { EdgelessTextSvgPainterExtension } from './svg-painter.js';
 export class EdgelessTextViewExtension extends ViewExtensionProvider {
     constructor() {
         super(...arguments);
@@ -24,6 +25,7 @@ export class EdgelessTextViewExtension extends ViewExtensionProvider {
             context.register(edgelessTextToolbarExtension);
             context.register(EdgelessClipboardEdgelessTextConfig);
             context.register(EdgelessTextInteraction);
+            context.register(EdgelessTextSvgPainterExtension);
         }
     }
 }

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

@@ -1,4 +1,4 @@
-import { reassociateConnectorsCommand } from '../../affine-block-surface/index.js';
+import { applyCreationLayer, reassociateConnectorsCommand, sourceLayerOf, } from '../../affine-block-surface/index.js';
 import { toast } from '../../affine-components/toast/index.js';
 import { BookmarkStyles, EmbedGithubModel, EmbedGithubStyles, isExternalEmbedModel, } from '../../affine-model/index.js';
 import { EMBED_CARD_HEIGHT, EMBED_CARD_WIDTH, } from '../../affine-shared/consts/index.js';
@@ -342,7 +342,16 @@ const createBuiltinSurfaceToolbarConfigForExternal = (klass) => {
                             const bounds = Bound.deserialize(xywh);
                             bounds.w = EMBED_CARD_WIDTH[style];
                             bounds.h = EMBED_CARD_HEIGHT[style];
-                            const newId = ctx.store.addBlock(flavour, { url, caption, style, xywh: bounds.serialize() }, parent);
+                            // The card takes the embed's place, layer included (ADR 0031 §6).
+                            const props = {
+                                url,
+                                caption,
+                                style,
+                                xywh: bounds.serialize(),
+                                layer: sourceLayerOf(model),
+                            };
+                            applyCreationLayer(ctx.std, props);
+                            const newId = ctx.store.addBlock(flavour, props, parent);
                             ctx.command.exec(reassociateConnectorsCommand, { oldId, newId });
                             ctx.store.deleteBlock(model);
                             // Selects new block

package/dist/_pkgs/affine-block-embed/embed-iframe-block/configs/toolbar.js

@@ -1,4 +1,4 @@
-import { reassociateConnectorsCommand } from '../../../affine-block-surface/index.js';
+import { applyCreationLayer, reassociateConnectorsCommand, sourceLayerOf, } from '../../../affine-block-surface/index.js';
 import { toast } from '../../../affine-components/toast/index.js';
 import { BookmarkStyles, EmbedIframeBlockModel } from '../../../affine-model/index.js';
 import { EMBED_CARD_HEIGHT, EMBED_CARD_WIDTH, } from '../../../affine-shared/consts/index.js';
@@ -292,7 +292,16 @@ export const builtinSurfaceToolbarConfig = {
                         const bounds = Bound.deserialize(xywh);
                         bounds.w = EMBED_CARD_WIDTH[style];
                         bounds.h = EMBED_CARD_HEIGHT[style];
-                        const newId = ctx.store.addBlock(flavour, { url, caption, style, xywh: bounds.serialize() }, parent);
+                        // The card takes the iframe's place, layer included (ADR 0031 §6).
+                        const props = {
+                            url,
+                            caption,
+                            style,
+                            xywh: bounds.serialize(),
+                            layer: sourceLayerOf(model),
+                        };
+                        applyCreationLayer(ctx.std, props);
+                        const newId = ctx.store.addBlock(flavour, props, parent);
                         ctx.command.exec(reassociateConnectorsCommand, { oldId, newId });
                         ctx.store.deleteBlock(model);
                         // Selects new block

package/dist/_pkgs/affine-block-embed-doc/embed-linked-doc-block/embed-edgeless-linked-doc-block.js

@@ -1,5 +1,5 @@
 import { createEmbedEdgelessBlockInteraction, toEdgelessEmbedBlock, } from '../../affine-block-embed/index.js';
-import { EdgelessCRUDIdentifier, reassociateConnectorsCommand, } from '../../affine-block-surface/index.js';
+import { EdgelessCRUDIdentifier, reassociateConnectorsCommand, sourceLayerOf, } from '../../affine-block-surface/index.js';
 import { EmbedLinkedDocBlockSchema } from '../../affine-model/index.js';
 import { EMBED_CARD_HEIGHT, EMBED_CARD_WIDTH, } from '../../affine-shared/consts/index.js';
 import { cloneReferenceInfoWithoutAliases, isNewTabTrigger, isNewViewTrigger, } from '../../affine-shared/utils/index.js';
@@ -21,6 +21,8 @@ export class EmbedEdgelessLinkedDocBlockComponent extends toEdgelessEmbedBlock(E
                 xywh: bound.serialize(),
                 caption,
                 ...cloneReferenceInfoWithoutAliases(this.referenceInfo$.peek()),
+                // In the linked doc's layer, not the active one (ADR 0031 §6).
+                layer: sourceLayerOf(this.model),
             }, surface);
             this.std.command.exec(reassociateConnectorsCommand, {
                 oldId: id,

package/dist/_pkgs/affine-block-embed-doc/embed-synced-doc-block/configs/toolbar.js

@@ -1,3 +1,4 @@
+import { applyCreationLayer, sourceLayerOf } from '../../../affine-block-surface/index.js';
 import { toast } from '../../../affine-components/toast/index.js';
 import { EditorChevronDown } from '../../../affine-components/toolbar/index.js';
 import { DEFAULT_NOTE_HEIGHT, DEFAULT_NOTE_WIDTH, EmbedSyncedDocModel, NoteBlockModel, NoteDisplayMode, } from '../../../affine-model/index.js';
@@ -297,11 +298,15 @@ const builtinSurfaceToolbarConfig = {
                             PADDING;
                         const y = syncedDocModel.elementBound.y;
                         const children = await draftedModels;
-                        const noteId = std.store.addBlock('affine:note', {
+                        const props = {
                             xywh: new Bound(x, y, DEFAULT_NOTE_WIDTH, DEFAULT_NOTE_HEIGHT).serialize(),
                             index: gfx.layer.generateIndex(),
                             displayMode: NoteDisplayMode.EdgelessOnly,
-                        }, ctx.store.root);
+                            // Beside the synced doc, in its layer (ADR 0031 §6).
+                            layer: sourceLayerOf(syncedDocModel),
+                        };
+                        applyCreationLayer(std, props);
+                        const noteId = std.store.addBlock('affine:note', props, ctx.store.root);
                         std.store.addBlock('affine:paragraph', {
                             text: new Text([
                                 {

package/dist/_pkgs/affine-block-embed-doc/embed-synced-doc-block/embed-edgeless-synced-doc-block.js

@@ -33,7 +33,7 @@ var __runInitializers = (this && this.__runInitializers) || function (thisArg, i
     return useValue ? value : void 0;
 };
 import { toEdgelessEmbedBlock } from '../../affine-block-embed/index.js';
-import { EdgelessCRUDIdentifier, reassociateConnectorsCommand, } from '../../affine-block-surface/index.js';
+import { EdgelessCRUDIdentifier, reassociateConnectorsCommand, sourceLayerOf, } from '../../affine-block-surface/index.js';
 import {} from '../../affine-model/index.js';
 import { EMBED_CARD_HEIGHT, EMBED_CARD_WIDTH, } from '../../affine-shared/consts/index.js';
 import { ThemeExtensionIdentifier, ThemeProvider, translateKey, } from '../../affine-shared/services/index.js';
@@ -170,6 +170,8 @@ let EmbedEdgelessSyncedDocBlockComponent = (() => {
                     caption,
                     ...this.referenceInfo,
                     ...aliasInfo,
+                    // In the synced doc's layer, not the active one (ADR 0031 §6).
+                    layer: sourceLayerOf(this.model),
                 }, surface);
                 this.std.command.exec(reassociateConnectorsCommand, {
                     oldId: id,

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

@@ -20,10 +20,13 @@ export declare const EdgelessFrameManagerIdentifier: import("../global/di/types.
 export declare class EdgelessFrameManager extends GfxExtension {
     static key: string;
     private readonly _disposable;
+    /** Canvas elements added locally, waiting for the adoption microtask. */
+    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);
@@ -32,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;
     /**
@@ -67,6 +70,8 @@ export declare class EdgelessFrameManager extends GfxExtension {
      */
     private _watchFrameMoved;
     private _watchElementAdded;
+    /** A canvas element just added locally: the frame under it adopts it. */
+    private _adoptIfInFrame;
     /**
      * Whether `element` fully encloses `frame`.
      *
@@ -119,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;