@formicoidea/labre-core 0.58.0 → 0.59.0

package/dist/_pkgs/affine-block-image/replace/commands.js

@@ -0,0 +1,200 @@
+import { ImageBlockModel, ShapeType } from '../../affine-model/index.js';
+import { TelemetryProvider } from '../../affine-shared/services/index.js';
+import { GfxControllerIdentifier } from '../../std/gfx/index.js';
+import { z } from 'zod';
+import { pickImageSource, replaceImageSource } from '../asset-picker.js';
+import { IMAGE_REPLACE_PICTURE_DESCRIPTION, IMAGE_REPLACE_WITH_IMAGE, IMAGE_REPLACE_WITH_IMAGE_DESCRIPTION, IMAGE_REPLACE_WITH_SHAPE, IMAGE_REPLACE_WITH_SHAPE_DESCRIPTION, } from '../translations.js';
+import { canReplaceImageWithShape, canReplaceShapeWithImage, replaceImageWithShape, replaceShapeWithImage, } from './replace-model.js';
+/**
+ * The replace commands (ADR 0044), `owner: 'core'`: a shape and an image
+ * belong to no framework. Registered from the image view extension, so they
+ * go with the `image` flag; the toolbar entries invoke them through
+ * `runCommand`, so the refusal, the one undo step and the telemetry live
+ * here, once.
+ *
+ * They EMIT FROM THEIR BODY (listed in `registry.unit.spec.ts`'s
+ * self-emitting commands): `CommandDescriptor.telemetry` maps onto the
+ * framework creation events, and whether anything was replaced is a fact of
+ * the invocation — a cancelled file chooser replaces nothing.
+ */
+export const replaceElementParams = z.object({
+    // The element to replace; absent, the single selected one.
+    elementId: z.string().min(1).optional(),
+});
+/**
+ * « Replace with shape » takes the shape picked in its sub-menu (ADR 0044,
+ * amendment of 2026-10-27). Both optional: absent, a plain rectangle, so the
+ * palette and the agent keep the v1 behaviour.
+ */
+export const replaceWithShapeParams = replaceElementParams.extend({
+    shapeType: z.nativeEnum(ShapeType).optional(),
+    // The corner radius as a fraction of the box: 0.1 is the rounded rectangle.
+    radius: z.number().min(0).max(0.5).optional(),
+});
+function target(std, params) {
+    const parsed = replaceElementParams.safeParse(params ?? {});
+    if (!parsed.success)
+        return null;
+    const gfx = std.get(GfxControllerIdentifier);
+    const { elementId } = parsed.data;
+    if (elementId !== undefined)
+        return gfx.getElementById(elementId);
+    const selected = gfx.selection.selectedElements;
+    return selected.length === 1 ? selected[0] : null;
+}
+/** The shape the command would replace, or `null`. */
+export function replaceableShape(std, params) {
+    const model = target(std, params);
+    return canReplaceShapeWithImage(std, model) ? model : null;
+}
+/** The canvas image the command would replace, or `null`. */
+export function replaceableImage(std, params) {
+    const model = target(std, params);
+    return model instanceof ImageBlockModel &&
+        canReplaceImageWithShape(std, model)
+        ? model
+        : null;
+}
+/**
+ * The canvas image whose PICTURE the command would swap, or `null`. Looser
+ * than {@link replaceableImage}: the block stays (same id, caption and
+ * comments kept), so a captioned image may change its picture; a locked one
+ * may not.
+ */
+export function replaceablePicture(std, params) {
+    const model = target(std, params);
+    if (std.store.readonly || !(model instanceof ImageBlockModel))
+        return null;
+    if (model.parent?.flavour !== 'affine:surface')
+        return null;
+    return model.isLocked() ? null : model;
+}
+function track(std, invocation, from, to) {
+    std.getOptional(TelemetryProvider)?.track('ElementReplaced', {
+        page: 'whiteboard editor',
+        from,
+        to,
+        control: invocation.source,
+        module: invocation.surface,
+    });
+}
+function select(std, id) {
+    std.get(GfxControllerIdentifier).selection.set({
+        elements: [id],
+        editing: false,
+    });
+}
+export const REPLACE_SHAPE_WITH_IMAGE = 'canvas.shape.replaceWithImage';
+export const REPLACE_IMAGE_WITH_SHAPE = 'canvas.image.replaceWithShape';
+export const REPLACE_IMAGE_WITH_IMAGE = 'canvas.image.replaceWithImage';
+export const replaceShapeWithImageCommand = {
+    id: REPLACE_SHAPE_WITH_IMAGE,
+    owner: 'core',
+    kind: 'action',
+    labelKey: IMAGE_REPLACE_WITH_IMAGE[0],
+    labelFallback: IMAGE_REPLACE_WITH_IMAGE[1],
+    descriptionKey: IMAGE_REPLACE_WITH_IMAGE_DESCRIPTION[0],
+    descriptionFallback: IMAGE_REPLACE_WITH_IMAGE_DESCRIPTION[1],
+    keywords: ['replace', 'image', 'picture', 'shape'],
+    // Not `agent`: the picture comes from a dialog a person answers.
+    surfaces: ['contextual-toolbar', 'palette'],
+    scope: 'edgeless',
+    defaultKeys: { mac: [], other: [] },
+    availability: 'editable',
+    when: std => replaceableShape(std) !== null,
+    params: replaceElementParams,
+    run: async (std, invocation, params) => {
+        if (!replaceableShape(std, params))
+            return;
+        const image = await pickImageSource(std);
+        if (!image)
+            return;
+        // Re-read: the dialog took time, the shape may be gone, locked or the
+        // document read-only by now.
+        const shape = replaceableShape(std, params);
+        if (!shape)
+            return;
+        const id = replaceShapeWithImage(std, shape, image);
+        if (!id)
+            return;
+        select(std, id);
+        std.getOptional(TelemetryProvider)?.track('BlockCreated', {
+            page: 'whiteboard editor',
+            blockType: 'affine:image',
+            control: invocation.source,
+            module: invocation.surface,
+        });
+        track(std, invocation, 'shape', 'image');
+    },
+};
+export const replaceImageWithShapeCommand = {
+    id: REPLACE_IMAGE_WITH_SHAPE,
+    owner: 'core',
+    kind: 'action',
+    labelKey: IMAGE_REPLACE_WITH_SHAPE[0],
+    labelFallback: IMAGE_REPLACE_WITH_SHAPE[1],
+    descriptionKey: IMAGE_REPLACE_WITH_SHAPE_DESCRIPTION[0],
+    descriptionFallback: IMAGE_REPLACE_WITH_SHAPE_DESCRIPTION[1],
+    keywords: ['replace', 'shape', 'rectangle', 'placeholder', 'image'],
+    surfaces: ['contextual-toolbar', 'palette', 'agent'],
+    scope: 'edgeless',
+    defaultKeys: { mac: [], other: [] },
+    availability: 'editable',
+    when: std => replaceableImage(std) !== null,
+    params: replaceWithShapeParams,
+    run: (std, invocation, params) => {
+        const image = replaceableImage(std, params);
+        if (!image)
+            return;
+        const parsed = replaceWithShapeParams.safeParse(params ?? {});
+        if (!parsed.success)
+            return;
+        const { shapeType, radius } = parsed.data;
+        const id = replaceImageWithShape(std, image, { shapeType, radius });
+        if (!id)
+            return;
+        select(std, id);
+        track(std, invocation, 'image', 'shape');
+    },
+};
+/**
+ * « Replace with image » on a canvas IMAGE (ADR 0044, amendment of
+ * 2026-10-27): another picture in the same block, from the host's library
+ * when there is one, from the system file chooser otherwise — so the entry
+ * exists without a host. The block keeps its id, corner, width and caption
+ * (`replaceImageSource`); it reports `ElementReplaced { image → image }`.
+ */
+export const replaceImageWithImageCommand = {
+    id: REPLACE_IMAGE_WITH_IMAGE,
+    owner: 'core',
+    kind: 'action',
+    labelKey: IMAGE_REPLACE_WITH_IMAGE[0],
+    labelFallback: IMAGE_REPLACE_WITH_IMAGE[1],
+    descriptionKey: IMAGE_REPLACE_PICTURE_DESCRIPTION[0],
+    descriptionFallback: IMAGE_REPLACE_PICTURE_DESCRIPTION[1],
+    keywords: ['replace', 'image', 'picture', 'library', 'swap'],
+    // Not `agent`: the picture comes from a dialog a person answers.
+    surfaces: ['contextual-toolbar', 'palette'],
+    scope: 'edgeless',
+    defaultKeys: { mac: [], other: [] },
+    availability: 'editable',
+    when: std => replaceablePicture(std) !== null,
+    params: replaceElementParams,
+    run: async (std, invocation, params) => {
+        if (!replaceablePicture(std, params))
+            return;
+        const source = await pickImageSource(std);
+        if (!source)
+            return;
+        // Re-read after the dialog, like the shape's.
+        const image = replaceablePicture(std, params);
+        if (!image || !replaceImageSource(image, source))
+            return;
+        track(std, invocation, 'image', 'image');
+    },
+};
+export const imageReplaceCommands = [
+    replaceShapeWithImageCommand,
+    replaceImageWithShapeCommand,
+    replaceImageWithImageCommand,
+];

package/dist/_pkgs/affine-block-image/replace/replace-model.d.ts

@@ -0,0 +1,44 @@
+import { type ImageBlockModel, type ImageBlockProps, ShapeElementModel, ShapeType } from '../../affine-model/index.js';
+import type { BlockStdScope } from '../../std/index.js';
+import type { ImageBlockSource } from '../utils.js';
+/**
+ * Whether a shape may be replaced by an image. Refused: a read-only store, a
+ * locked shape, a NOTATION shape (it carries a role its framework reads), a
+ * shape with text (v1 never drops what the author typed) and a mind-map node
+ * (the mind map owns its tree).
+ */
+export declare function canReplaceShapeWithImage(std: BlockStdScope, shape: unknown): shape is ShapeElementModel;
+/**
+ * Whether a canvas image may be replaced by a shape. Refused: a read-only
+ * store, an image that is not on the canvas, a locked image, and one with a
+ * caption or comments (v1 never drops what the author wrote).
+ */
+export declare function canReplaceImageWithShape(std: BlockStdScope, image: ImageBlockModel | null | undefined): image is ImageBlockModel;
+/**
+ * The crop that cuts `image` to the proportions of `box`, as stored props:
+ * nothing when the picture already has them (the whole image is the absent
+ * key, ADR 0037).
+ */
+export declare function cropToBox(box: {
+    w: number;
+    h: number;
+}, image: Pick<ImageBlockSource, 'width' | 'height'>): Pick<ImageBlockProps, 'crop'>;
+/**
+ * Put `image` in place of `shape`, cut to the shape's box. Answers the new
+ * image block's id, or `null` when the gesture is refused (nothing written).
+ */
+export declare function replaceShapeWithImage(std: BlockStdScope, shape: ShapeElementModel, image: ImageBlockSource): string | null;
+/** Which shape takes the image's place: a rectangle unless told otherwise. */
+export type ReplacementShape = {
+    shapeType?: ShapeType;
+    /** The corner radius, a fraction of the box (the rounded rectangle's 0.1). */
+    radius?: number;
+};
+/**
+ * Put a shape in place of `image` — a rectangle by default, or the
+ * `shapeType` and `radius` picked in « Replace with shape » (ADR 0044,
+ * amendment of 2026-10-27) — at its box, rotation, depth and layer.
+ * The blob stays in the asset store (undo brings the image back, and other
+ * pages may show it). Answers the new shape's id, or `null` when refused.
+ */
+export declare function replaceImageWithShape(std: BlockStdScope, image: ImageBlockModel, shape?: ReplacementShape): string | null;

package/dist/_pkgs/affine-block-image/replace/replace-model.js

@@ -0,0 +1,168 @@
+import { applyCreationLayer, reassociateConnectors, sourceLayerOf, } from '../../affine-block-surface/index.js';
+import { ImageBlockSchema, isWholeImage, MindmapElementModel, ShapeElementModel, ShapeType, } from '../../affine-model/index.js';
+import { Bound } from '../../global/gfx/index.js';
+import { GfxControllerIdentifier } from '../../std/gfx/index.js';
+import { ratioCrop } from '../crop/crop-math.js';
+/**
+ * « Replace with image » and « Replace with shape » (ADR 0044): a model of
+ * the other kind at the old one's place, then the old one deleted. A shape is
+ * a surface ELEMENT and an image a BLOCK, so this is not a morph: the id
+ * changes, on purpose.
+ *
+ * What crosses over, in ONE undo step (one `captureSync`): `xywh`,
+ * `rotate`, `index`, the user layer (`sourceLayerOf`, ADR 0031 §6), every
+ * connector end bound to the old id, and the old model's place in its group
+ * or frame. Nothing is written when the gesture is refused, so a refusal
+ * never leaves an empty undo step.
+ */
+function surfaceOf(std) {
+    return (std.get(GfxControllerIdentifier).surface ??
+        null);
+}
+/**
+ * Whether a shape may be replaced by an image. Refused: a read-only store, a
+ * locked shape, a NOTATION shape (it carries a role its framework reads), a
+ * shape with text (v1 never drops what the author typed) and a mind-map node
+ * (the mind map owns its tree).
+ */
+export function canReplaceShapeWithImage(std, shape) {
+    if (std.store.readonly)
+        return false;
+    if (!(shape instanceof ShapeElementModel))
+        return false;
+    if (shape.isLocked())
+        return false;
+    if (shape.role !== undefined)
+        return false;
+    if ((shape.text?.length ?? 0) > 0)
+        return false;
+    if (shape.group instanceof MindmapElementModel)
+        return false;
+    return true;
+}
+/**
+ * Whether a canvas image may be replaced by a shape. Refused: a read-only
+ * store, an image that is not on the canvas, a locked image, and one with a
+ * caption or comments (v1 never drops what the author wrote).
+ */
+export function canReplaceImageWithShape(std, image) {
+    if (std.store.readonly || !image)
+        return false;
+    if (image.flavour !== ImageBlockSchema.model.flavour)
+        return false;
+    if (image.parent?.flavour !== 'affine:surface')
+        return false;
+    if (image.isLocked())
+        return false;
+    if (image.props.caption)
+        return false;
+    if (Object.keys(image.props.comments ?? {}).length > 0)
+        return false;
+    return true;
+}
+/**
+ * Move `oldModel`'s connectors and container membership onto `newModel`,
+ * then delete `oldModel`. Runs inside the caller's transaction. The new
+ * model joins the container BEFORE the old one leaves it, so a group is never
+ * seen empty.
+ */
+function handOver(std, surface, oldModel, newModel) {
+    reassociateConnectors(surface, oldModel.id, newModel.id);
+    const container = oldModel.group;
+    if (container) {
+        container.addChild(newModel);
+        // oxlint-disable-next-line unicorn/prefer-dom-node-remove
+        container.removeChild(oldModel);
+    }
+    if (surface.hasElementById(oldModel.id)) {
+        surface.deleteElement(oldModel.id);
+    }
+    else {
+        std.store.deleteBlock(oldModel);
+    }
+}
+/**
+ * The crop that cuts `image` to the proportions of `box`, as stored props:
+ * nothing when the picture already has them (the whole image is the absent
+ * key, ADR 0037).
+ */
+export function cropToBox(box, image) {
+    if (!(box.w > 0 && box.h > 0))
+        return {};
+    const rect = ratioCrop(box.w / box.h, image.width, image.height);
+    return isWholeImage(rect) ? {} : { crop: rect };
+}
+/**
+ * Put `image` in place of `shape`, cut to the shape's box. Answers the new
+ * image block's id, or `null` when the gesture is refused (nothing written).
+ */
+export function replaceShapeWithImage(std, shape, image) {
+    const surface = surfaceOf(std);
+    if (!surface || !canReplaceShapeWithImage(std, shape))
+        return null;
+    if (!surface.hasElementById(shape.id))
+        return null;
+    if (!image.sourceId || !(image.width > 0 && image.height > 0))
+        return null;
+    const bound = Bound.deserialize(shape.xywh);
+    const props = {
+        sourceId: image.sourceId,
+        size: image.size,
+        // On the canvas `width`/`height` are the WHOLE picture's natural size
+        // and `xywh` the visible box (ADR 0037).
+        width: image.width,
+        height: image.height,
+        xywh: shape.xywh,
+        rotate: shape.rotate ?? 0,
+        index: shape.index,
+        layer: sourceLayerOf(shape),
+        ...cropToBox(bound, image),
+    };
+    applyCreationLayer(std, props);
+    const { store } = std;
+    store.captureSync();
+    // The block is created OUTSIDE the hand-over's transaction: a block added
+    // inside one has no model until it ends, and the container needs the
+    // model. Both writes land in the undo step `captureSync` just opened.
+    const id = store.addBlock(ImageBlockSchema.model.flavour, props, surface);
+    const created = store.getModelById(id);
+    if (created)
+        store.transact(() => handOver(std, surface, shape, created));
+    return id;
+}
+/**
+ * Put a shape in place of `image` — a rectangle by default, or the
+ * `shapeType` and `radius` picked in « Replace with shape » (ADR 0044,
+ * amendment of 2026-10-27) — at its box, rotation, depth and layer.
+ * The blob stays in the asset store (undo brings the image back, and other
+ * pages may show it). Answers the new shape's id, or `null` when refused.
+ */
+export function replaceImageWithShape(std, image, shape = {}) {
+    const surface = surfaceOf(std);
+    if (!surface || !canReplaceImageWithShape(std, image))
+        return null;
+    if (!std.store.getBlock(image.id))
+        return null;
+    const props = {
+        type: 'shape',
+        shapeType: shape.shapeType ?? ShapeType.Rect,
+        radius: shape.radius ?? 0,
+        xywh: image.xywh,
+        rotate: image.props.rotate ?? 0,
+        index: image.index,
+        layer: sourceLayerOf(image),
+    };
+    // The surface's `beforeAdd` middleware stamps the layer too; resolving it
+    // here keeps the rule when no middleware is mounted.
+    applyCreationLayer(std, props);
+    const { store } = std;
+    let id = null;
+    store.captureSync();
+    store.transact(() => {
+        id = surface.addElement(props);
+        const created = surface.getElementById(id);
+        if (created)
+            handOver(std, surface, image, created);
+    });
+    return id;
+}

package/dist/_pkgs/affine-block-image/replace/toolbar.d.ts

@@ -0,0 +1,21 @@
+import { type ToolbarAction } from '../../affine-shared/services/index.js';
+/**
+ * « Replace » on a canvas image's toolbar (ADR 0044, amendment of
+ * 2026-10-27): ONE menu where there were two buttons, because the product
+ * owner wants the choice in one place — « Replace with image » (another
+ * picture, from the host's library or the system file chooser,
+ * `canvas.image.replaceWithImage`) and « Replace with shape », a sub-menu of
+ * the shape tool's shapes (`canvas.image.replaceWithShape` with the picked
+ * `shapeType` and `radius`). It keeps the id `a.replace`, so it sits where the
+ * old « Replace » did. Each entry shows only when its command would act.
+ */
+export declare const imageReplaceMenuToolbarAction: ToolbarAction;
+/**
+ * « Replace with image » on the SHAPE toolbar, registered from this package:
+ * `gfx/shape` never imports the image block. The bare
+ * `affine:surface:shape` key belongs to `shapeToolbarExtension`, so this
+ * second module carries an owner (`toolbarModuleKey`) and the registry hands
+ * it to the same row. Replacing a shape with ANOTHER shape is the shape
+ * toolbar's own « Switch shape type », not repeated here.
+ */
+export declare const shapeReplaceWithImageToolbarExtension: import("../../store/index.js").ExtensionType;

package/dist/_pkgs/affine-block-image/replace/toolbar.js

@@ -0,0 +1,159 @@
+import { ShapeComponentConfig } from '../../affine-gfx-shape/index.js';
+import { EditorChevronDown, renderPickerMenuItems, } from '../../affine-components/toolbar/index.js';
+import { getShapeRadius, getShapeType, ShapeElementModel, } from '../../affine-model/index.js';
+import { ToolbarModuleExtension, toolbarModuleKey, translateKey, } from '../../affine-shared/services/index.js';
+import { ArrowRightSmallIcon, ImageIcon, ReplaceIcon, ShapeIcon, } from '@blocksuite/icons/lit';
+import { BlockFlavourIdentifier, runCommand } from '../../std/index.js';
+import { html, nothing } from 'lit';
+import { createRef, ref } from 'lit/directives/ref.js';
+import { IMAGE_REPLACE_WITH_IMAGE, IMAGE_REPLACE_WITH_SHAPE, IMAGE_TOOLBAR_REPLACE, } from '../translations.js';
+import { replaceableImage, replaceablePicture, replaceableShape, replaceImageWithImageCommand, replaceImageWithShapeCommand, replaceShapeWithImageCommand, } from './commands.js';
+const FROM_TOOLBAR = {
+    surface: 'contextual-toolbar',
+    source: 'toolbar:general',
+};
+/**
+ * A click inside the shape sub-menu must not reach `document`: every
+ * `editor-menu-button` closes on a click outside its own trigger
+ * (`listenClickAway`), and the sub-menu's trigger and row are outside the
+ * Replace menu's trigger, so the outer menu would close — and take the
+ * sub-menu, which it contains, with it — on the very click that opens it.
+ */
+const keepOpen = (event) => event.stopPropagation();
+/**
+ * Beside the menu, as a sub-menu opens. One object, not a literal per render:
+ * `editor-menu-button` rebuilds its popper whenever `popperOptions` changes
+ * identity, which would drop an open sub-menu on any toolbar re-render.
+ */
+const SUBMENU_POPPER = {
+    allowedPlacements: ['right-start', 'left-start'],
+    mainAxis: 8,
+};
+function renderShapeSubmenu(ctx, outer) {
+    const label = translateKey(ctx.std, ...IMAGE_REPLACE_WITH_SHAPE);
+    const onPick = (name) => {
+        if (!name)
+            return;
+        outer.value?.hide();
+        runCommand(ctx.std, replaceImageWithShapeCommand, FROM_TOOLBAR, {
+            shapeType: getShapeType(name),
+            radius: getShapeRadius(name),
+        });
+    };
+    // The shape tool's own list — names, icons and wordings — so the sub-menu
+    // offers exactly the shapes a user can draw, in the same order.
+    const items = ShapeComponentConfig.map(item => ({
+        key: translateKey(ctx.std, ...item.tooltipWording),
+        value: item.name,
+        icon: item.generalIcon,
+        disabled: item.disabled,
+    }));
+    return html `
+    <div @click=${keepOpen}>
+      <editor-menu-button
+        data-testid="image-replace-shape"
+        .contentPadding=${'4px 6px'}
+        .popperOptions=${SUBMENU_POPPER}
+        .button=${html `
+          <editor-icon-button
+            aria-label=${label}
+            data-testid="image-replace-shape-button"
+            .justify=${'space-between'}
+            .iconContainerPadding=${[4, 8]}
+            .iconContainerWidth=${'100%'}
+          >
+            ${ShapeIcon()}
+            <span class="label">${label}</span>
+            ${ArrowRightSmallIcon()}
+          </editor-icon-button>
+        `}
+      >
+        <div>
+          ${renderPickerMenuItems(items, null, onPick, 'image-replace-shape')}
+        </div>
+      </editor-menu-button>
+    </div>
+  `;
+}
+/**
+ * « Replace » on a canvas image's toolbar (ADR 0044, amendment of
+ * 2026-10-27): ONE menu where there were two buttons, because the product
+ * owner wants the choice in one place — « Replace with image » (another
+ * picture, from the host's library or the system file chooser,
+ * `canvas.image.replaceWithImage`) and « Replace with shape », a sub-menu of
+ * the shape tool's shapes (`canvas.image.replaceWithShape` with the picked
+ * `shapeType` and `radius`). It keeps the id `a.replace`, so it sits where the
+ * old « Replace » did. Each entry shows only when its command would act.
+ */
+export const imageReplaceMenuToolbarAction = {
+    id: 'a.replace',
+    when: ctx => !ctx.readonly &&
+        (replaceablePicture(ctx.std) !== null ||
+            replaceableImage(ctx.std) !== null),
+    content(ctx) {
+        const picture = replaceablePicture(ctx.std) !== null;
+        const toShape = replaceableImage(ctx.std) !== null;
+        if (!picture && !toShape)
+            return null;
+        const label = translateKey(ctx.std, ...IMAGE_TOOLBAR_REPLACE);
+        const withImage = translateKey(ctx.std, ...IMAGE_REPLACE_WITH_IMAGE);
+        const outer = createRef();
+        return html `
+      <editor-menu-button
+        ${ref(outer)}
+        data-testid="image-replace-menu"
+        .contentPadding=${'8px'}
+        .button=${html `
+          <editor-icon-button
+            aria-label=${label}
+            data-testid="image-replace-button"
+            .tooltip=${label}
+          >
+            ${ReplaceIcon()} ${EditorChevronDown}
+          </editor-icon-button>
+        `}
+      >
+        <div data-size="large" data-orientation="vertical">
+          ${picture
+            ? html `
+                <editor-menu-action
+                  aria-label=${withImage}
+                  data-testid="image-replace-with-image"
+                  @click=${() => runCommand(ctx.std, replaceImageWithImageCommand, FROM_TOOLBAR)}
+                >
+                  ${ImageIcon()}
+                  <span class="label">${withImage}</span>
+                </editor-menu-action>
+              `
+            : nothing}
+          ${toShape ? renderShapeSubmenu(ctx, outer) : nothing}
+        </div>
+      </editor-menu-button>
+    `;
+    },
+};
+const shapeReplaceToolbarConfig = {
+    actions: [
+        {
+            id: 'h.replace-with-image',
+            tooltip: IMAGE_REPLACE_WITH_IMAGE[1],
+            tooltipWording: IMAGE_REPLACE_WITH_IMAGE,
+            icon: ImageIcon(),
+            when: ctx => !ctx.readonly && replaceableShape(ctx.std) !== null,
+            run: ctx => runCommand(ctx.std, replaceShapeWithImageCommand, FROM_TOOLBAR),
+        },
+    ],
+    when: ctx => ctx.getSurfaceModelsByType(ShapeElementModel).length === 1,
+};
+/**
+ * « Replace with image » on the SHAPE toolbar, registered from this package:
+ * `gfx/shape` never imports the image block. The bare
+ * `affine:surface:shape` key belongs to `shapeToolbarExtension`, so this
+ * second module carries an owner (`toolbarModuleKey`) and the registry hands
+ * it to the same row. Replacing a shape with ANOTHER shape is the shape
+ * toolbar's own « Switch shape type », not repeated here.
+ */
+export const shapeReplaceWithImageToolbarExtension = ToolbarModuleExtension({
+    id: BlockFlavourIdentifier(toolbarModuleKey('affine:surface:shape', 'image-replace')),
+    config: shapeReplaceToolbarConfig,
+});

package/dist/_pkgs/affine-block-image/translations.d.ts

@@ -36,10 +36,23 @@ export declare const IMAGE_TOAST_DOWNLOADING: ChromeWording;
 export declare const IMAGE_TOAST_COPIED: ChromeWording;
 export declare const IMAGE_TOAST_READ_SIZE_FAILED: ChromeWording;
 /**
- * The image toolbar's "Replace" (`configs/replace-action.ts`), offered only
- * with a host asset dialog (`AssetPickerProvider`).
+ * The image toolbar's "Replace": the page button (`configs/replace-action.ts`)
+ * and the canvas menu that holds « Replace with image » and « Replace with
+ * shape » (`replace/toolbar.ts`, ADR 0044 amendment of 2026-10-27). Offered
+ * with or without a host: without one, the system file chooser.
  */
 export declare const IMAGE_TOOLBAR_REPLACE: ChromeWording;
+/**
+ * « Replace with image » on a shape and « Replace with shape » on a canvas
+ * image (ADR 0044): the toolbar entries and the commands they run share these
+ * keys, so the palette and the toolbar say the same words.
+ */
+export declare const IMAGE_REPLACE_WITH_IMAGE: ChromeWording;
+export declare const IMAGE_REPLACE_WITH_IMAGE_DESCRIPTION: ChromeWording;
+/** `canvas.image.replaceWithImage`: the same label, said of an image. */
+export declare const IMAGE_REPLACE_PICTURE_DESCRIPTION: ChromeWording;
+export declare const IMAGE_REPLACE_WITH_SHAPE: ChromeWording;
+export declare const IMAGE_REPLACE_WITH_SHAPE_DESCRIPTION: ChromeWording;
 /**
  * This package's contribution to the translation-key manifest, listed in
  * `PACKAGE_WORDINGS` under source `chrome`

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

@@ -78,13 +78,41 @@ export const IMAGE_TOAST_READ_SIZE_FAILED = [
     'Failed to read image size, please try another image',
 ];
 /**
- * The image toolbar's "Replace" (`configs/replace-action.ts`), offered only
- * with a host asset dialog (`AssetPickerProvider`).
+ * The image toolbar's "Replace": the page button (`configs/replace-action.ts`)
+ * and the canvas menu that holds « Replace with image » and « Replace with
+ * shape » (`replace/toolbar.ts`, ADR 0044 amendment of 2026-10-27). Offered
+ * with or without a host: without one, the system file chooser.
  */
 export const IMAGE_TOOLBAR_REPLACE = [
     'com.labre.image.toolbar.replace',
     'Replace',
 ];
+/**
+ * « Replace with image » on a shape and « Replace with shape » on a canvas
+ * image (ADR 0044): the toolbar entries and the commands they run share these
+ * keys, so the palette and the toolbar say the same words.
+ */
+export const IMAGE_REPLACE_WITH_IMAGE = [
+    'com.labre.image.replace.with-image',
+    'Replace with image',
+];
+export const IMAGE_REPLACE_WITH_IMAGE_DESCRIPTION = [
+    'com.labre.image.replace.with-image.description',
+    'Put a picture in place of this shape, cut to its box.',
+];
+/** `canvas.image.replaceWithImage`: the same label, said of an image. */
+export const IMAGE_REPLACE_PICTURE_DESCRIPTION = [
+    'com.labre.image.replace.picture.description',
+    'Put another picture in this image, from the library or a file.',
+];
+export const IMAGE_REPLACE_WITH_SHAPE = [
+    'com.labre.image.replace.with-shape',
+    'Replace with shape',
+];
+export const IMAGE_REPLACE_WITH_SHAPE_DESCRIPTION = [
+    'com.labre.image.replace.with-shape.description',
+    'Put a rectangle in place of this image.',
+];
 /**
  * This package's contribution to the translation-key manifest, listed in
  * `PACKAGE_WORDINGS` under source `chrome`
@@ -108,4 +136,9 @@ export const IMAGE_WORDINGS = [
     IMAGE_TOAST_COPIED,
     IMAGE_TOAST_READ_SIZE_FAILED,
     IMAGE_TOOLBAR_REPLACE,
+    IMAGE_REPLACE_WITH_IMAGE,
+    IMAGE_REPLACE_WITH_IMAGE_DESCRIPTION,
+    IMAGE_REPLACE_PICTURE_DESCRIPTION,
+    IMAGE_REPLACE_WITH_SHAPE,
+    IMAGE_REPLACE_WITH_SHAPE_DESCRIPTION,
 ];