@formicoidea/labre-core 0.58.0 → 0.59.0

package/dist/_pkgs/affine-block-image/crop/crop-controller.js

@@ -1,5 +1,6 @@
 import { readImageCrop, } from '../../affine-model/index.js';
 import { Bound } from '../../global/gfx/index.js';
+import { GfxControllerIdentifier } from '../../std/gfx/index.js';
 import { computed, signal } from '@preact/signals-core';
 import { html, nothing } from 'lit';
 import { styleMap } from 'lit/directives/style-map.js';
@@ -9,6 +10,14 @@ import { writeImageCrop } from './write-crop.js';
  * The « Rogner » state of one image block (ADR 0037), shared by the page and
  * the canvas components: which preset the crop frame is open on, if any, and
  * the gestures that write. The frame is local UI and never stored.
+ *
+ * On the canvas the open frame owns the pointer and the wheel: the image is
+ * selected in EDITING state, which hides the selected-rect handles that
+ * would otherwise sit on the frame's corners, and the viewport is locked,
+ * so the wheel zooms the picture inside the frame rather than the canvas.
+ * Both are taken by one open path and given back by one `stop`, whatever
+ * closes the frame (Escape, Enter, a press elsewhere, the toolbar, the block
+ * leaving the DOM, the selection moving elsewhere), so they cannot drift.
  */
 export class ImageCropController {
     constructor(_block, _onCanvas) {
@@ -17,6 +26,8 @@ export class ImageCropController {
         /** The mask the crop frame is open on, `null` when it is closed. */
         this.editing$ = signal(null);
         this.crop$ = computed(() => readImageCrop(this._block.model.props.crop$.value));
+        /** Gives the canvas back; set while the frame is open on the canvas. */
+        this._release = null;
     }
     /**
      * The source's proportions: the loaded `<img>`'s pixel size, else what the
@@ -56,17 +67,44 @@ export class ImageCropController {
                 return;
             this.commit(presetCrop(mask, natural.width, natural.height), mask);
         }
+        this._open(mask);
+    }
+    _open(mask) {
         this.editing$.value = mask;
+        if (!this._onCanvas || this._release)
+            return;
+        const { selection, viewport } = this._block.std.get(GfxControllerIdentifier);
+        const { id, store } = this._block.model;
+        const wasLocked = viewport.locked;
+        viewport.locked = true;
+        selection.set({ elements: [id], editing: true });
+        // Another selection (a shortcut, the selection pane, a peer's undo
+        // removing the block) closes the frame instead of leaving it orphaned.
+        const watch = selection.slots.updated.subscribe(() => {
+            if (!selection.editing || !selection.has(id))
+                this.stop();
+        });
+        this._release = () => {
+            watch.unsubscribe();
+            viewport.locked = wasLocked;
+            if (selection.editing && selection.has(id) && store.hasBlock(id)) {
+                selection.set({ elements: [id], editing: false });
+            }
+        };
     }
     commit(rect, mask = this.editing$.peek() ?? 'free') {
         return writeImageCrop(this._block.model, rect, mask, this._onCanvas);
     }
     /** « Image d'origine »: removes the crop; the bytes never changed. */
     restoreOriginal() {
-        this.editing$.value = null;
+        this.stop();
         return writeImageCrop(this._block.model, undefined, 'free', this._onCanvas);
     }
+    /** Closes the frame and gives the canvas back; harmless when closed. */
     stop() {
+        const release = this._release;
+        this._release = null;
+        release?.();
         this.editing$.value = null;
     }
     /** The frame, or nothing when it is closed or the page is readonly. */
@@ -88,7 +126,7 @@ export class ImageCropController {
       .ratio=${ratio}
       .rotate=${rotate}
       .onCommit=${(rect) => {
-            this.commit(rect);
+            this.commit(rect, mask);
         }}
       .onExit=${() => this.stop()}
     ></affine-image-crop-overlay>`;

package/dist/_pkgs/affine-block-image/crop/crop-math.d.ts

@@ -14,6 +14,13 @@ export declare function maskRatio(mask: ImageCropMask, naturalWidth: number, nat
  * writes before the author adjusts it. Free is the whole image.
  */
 export declare function presetCrop(mask: ImageCropMask, naturalWidth: number, naturalHeight: number): CropRect;
+/**
+ * The largest centred rectangle whose width over height, in SOURCE PIXELS, is
+ * `ratio`: a preset's window, and the cut a shape's box makes in the picture
+ * that replaces it (ADR 0044). The whole image when the size or the ratio is
+ * unknown.
+ */
+export declare function ratioCrop(ratio: number, naturalWidth: number, naturalHeight: number): CropRect;
 /** The window dragged by a normalised delta, kept inside the image. */
 export declare function moveCrop(start: CropRect, dx: number, dy: number): CropRect;
 /**
@@ -22,6 +29,21 @@ export declare function moveCrop(start: CropRect, dx: number, dy: number): CropR
  * and then shrinks to fit the image, so it never leaves the source.
  */
 export declare function resizeCrop(start: CropRect, corner: CropCorner, dx: number, dy: number, k: number | null): CropRect;
+/** Scale of the window per 100 units of wheel `deltaY`. */
+export declare const CROP_WHEEL_STEP = 1.05;
+/**
+ * The window's scale for one wheel event: below 1 when the wheel turns up
+ * (`deltaY < 0`), which shrinks the window and so zooms into the picture.
+ */
+export declare function cropWheelFactor(deltaY: number): number;
+/**
+ * The window scaled by `factor` about a point of the source (`px`, `py`,
+ * normalised): that point stays under the pointer. The aspect is `k`
+ * (normalised `w / h`) when a mask holds one, else the window's own; the
+ * window never outgrows the image nor shrinks below the minimum side, and is
+ * then pushed back inside the image.
+ */
+export declare function zoomCrop(start: CropRect, factor: number, px: number, py: number, k: number | null): CropRect;
 export declare function sameCropRect(a: CropRect, b: CropRect): boolean;
 /**
  * The canvas box once the crop changes from `from` to `to`, for a block whose

package/dist/_pkgs/affine-block-image/crop/crop-math.js

@@ -23,9 +23,21 @@ export function maskRatio(mask, naturalWidth, naturalHeight) {
  * writes before the author adjusts it. Free is the whole image.
  */
 export function presetCrop(mask, naturalWidth, naturalHeight) {
-    const k = maskRatio(mask, naturalWidth, naturalHeight);
-    if (k === null)
+    if (mask === 'free')
         return WHOLE_IMAGE;
+    return ratioCrop(MASK_RATIOS[mask], naturalWidth, naturalHeight);
+}
+/**
+ * The largest centred rectangle whose width over height, in SOURCE PIXELS, is
+ * `ratio`: a preset's window, and the cut a shape's box makes in the picture
+ * that replaces it (ADR 0044). The whole image when the size or the ratio is
+ * unknown.
+ */
+export function ratioCrop(ratio, naturalWidth, naturalHeight) {
+    if (!(ratio > 0) || naturalWidth <= 0 || naturalHeight <= 0) {
+        return WHOLE_IMAGE;
+    }
+    const k = (ratio * naturalHeight) / naturalWidth;
     let w = k;
     let h = 1;
     if (w > 1) {
@@ -88,6 +100,47 @@ export function resizeCrop(start, corner, dx, dy, k) {
         h,
     };
 }
+/** Scale of the window per 100 units of wheel `deltaY`. */
+export const CROP_WHEEL_STEP = 1.05;
+/** At most this many steps per wheel event: a fast flick stays readable. */
+const CROP_WHEEL_MAX_STEPS = 3;
+/**
+ * The window's scale for one wheel event: below 1 when the wheel turns up
+ * (`deltaY < 0`), which shrinks the window and so zooms into the picture.
+ */
+export function cropWheelFactor(deltaY) {
+    const steps = clamp(deltaY / 100, -CROP_WHEEL_MAX_STEPS, CROP_WHEEL_MAX_STEPS);
+    return CROP_WHEEL_STEP ** steps;
+}
+/**
+ * The window scaled by `factor` about a point of the source (`px`, `py`,
+ * normalised): that point stays under the pointer. The aspect is `k`
+ * (normalised `w / h`) when a mask holds one, else the window's own; the
+ * window never outgrows the image nor shrinks below the minimum side, and is
+ * then pushed back inside the image.
+ */
+export function zoomCrop(start, factor, px, py, k) {
+    const ratio = k ?? start.w / start.h;
+    const min = IMAGE_CROP_MIN_SIDE;
+    let w = start.w * factor;
+    let h = w / ratio;
+    // Fit inside the image first, then grow to the minimum: a ratio too
+    // extreme for both keeps the minimum, as `resizeCrop` does.
+    const shrink = Math.min(1, 1 / w, 1 / h);
+    w *= shrink;
+    h *= shrink;
+    const grow = Math.max(1, min / w, min / h);
+    w *= grow;
+    h *= grow;
+    const sx = w / start.w;
+    const sy = h / start.h;
+    return {
+        x: clamp(px - (px - start.x) * sx, 0, Math.max(0, 1 - w)),
+        y: clamp(py - (py - start.y) * sy, 0, Math.max(0, 1 - h)),
+        w,
+        h,
+    };
+}
 export function sameCropRect(a, b) {
     return (Math.abs(a.x - b.x) < EPSILON &&
         Math.abs(a.y - b.y) < EPSILON &&

package/dist/_pkgs/affine-block-image/crop/crop-overlay.d.ts

@@ -11,9 +11,17 @@ declare const ImageCropOverlay_base: typeof LitElement & import("../../global/ut
  * release hands it to `onCommit` once — one gesture, one write, one undo
  * step, decided by the caller (`writeImageCrop`).
  *
- * Pointer events never reach the editor while the frame is open: a press on
- * the frame would otherwise start a canvas drag or a page selection. Escape,
- * Enter or a press anywhere else calls `onExit`.
+ * The wheel over the frame zooms the picture inside it: it scales the window
+ * about the pointer, the ratio held, inside the image. One scroll is one
+ * write: the draft is handed to `onCommit` once the wheel has been quiet for
+ * a moment, or at once when a drag starts or the frame is left by Escape,
+ * Enter or a press elsewhere. A frame closed by anything else (the toolbar,
+ * the block leaving) drops a scroll still pending rather than write after it.
+ *
+ * Pointer and wheel events never reach the editor while the frame is open: a
+ * press on the frame would otherwise start a canvas drag or a page
+ * selection, a wheel would zoom or scroll the canvas. Escape, Enter or a
+ * press anywhere else calls `onExit`.
  */
 export declare class ImageCropOverlay extends ImageCropOverlay_base {
     static styles: import("lit").CSSResult;
@@ -28,11 +36,17 @@ export declare class ImageCropOverlay extends ImageCropOverlay_base {
     accessor onExit: () => void;
     accessor draft: CropRect;
     private _dragging;
+    /** The pending end of a wheel gesture, `null` when none is under way. */
+    private _wheelTimer;
     /** Removes the listeners of the gesture in progress, if any. */
     private _releaseGesture;
     private readonly _stop;
     private readonly _onOutsidePointer;
     private readonly _onKeydown;
+    /** Ends the wheel gesture under way, if any, with its one write. */
+    private _commitWheel;
+    private _dropWheel;
+    private readonly _onWheel;
     /**
      * The document-wide listeners (a press elsewhere, Escape, Enter) live only
      * as long as this element: the frame is rendered while it is open and

package/dist/_pkgs/affine-block-image/crop/crop-overlay.js

@@ -38,8 +38,10 @@ import { css, html, LitElement } from 'lit';
 import { property, state } from 'lit/decorators.js';
 import { repeat } from 'lit/directives/repeat.js';
 import { styleMap } from 'lit/directives/style-map.js';
-import { moveCrop, resizeCrop, WHOLE_IMAGE, } from './crop-math.js';
+import { cropWheelFactor, moveCrop, resizeCrop, WHOLE_IMAGE, zoomCrop, } from './crop-math.js';
 const CORNERS = ['nw', 'ne', 'sw', 'se'];
+/** Quiet time after the last wheel event that ends one wheel gesture. */
+const WHEEL_COMMIT_DELAY_MS = 150;
 const rectStyle = (rect) => styleMap({
     left: `${rect.x * 100}%`,
     top: `${rect.y * 100}%`,
@@ -56,9 +58,17 @@ const rectStyle = (rect) => styleMap({
  * release hands it to `onCommit` once — one gesture, one write, one undo
  * step, decided by the caller (`writeImageCrop`).
  *
- * Pointer events never reach the editor while the frame is open: a press on
- * the frame would otherwise start a canvas drag or a page selection. Escape,
- * Enter or a press anywhere else calls `onExit`.
+ * The wheel over the frame zooms the picture inside it: it scales the window
+ * about the pointer, the ratio held, inside the image. One scroll is one
+ * write: the draft is handed to `onCommit` once the wheel has been quiet for
+ * a moment, or at once when a drag starts or the frame is left by Escape,
+ * Enter or a press elsewhere. A frame closed by anything else (the toolbar,
+ * the block leaving) drops a scroll still pending rather than write after it.
+ *
+ * Pointer and wheel events never reach the editor while the frame is open: a
+ * press on the frame would otherwise start a canvas drag or a page
+ * selection, a wheel would zoom or scroll the canvas. Escape, Enter or a
+ * press anywhere else calls `onExit`.
  */
 let ImageCropOverlay = (() => {
     let _classSuper = WithDisposable(LitElement);
@@ -94,12 +104,15 @@ let ImageCropOverlay = (() => {
             this.#onExit_accessor_storage = (__runInitializers(this, _onCommit_extraInitializers), __runInitializers(this, _onExit_initializers, () => { }));
             this.#draft_accessor_storage = (__runInitializers(this, _onExit_extraInitializers), __runInitializers(this, _draft_initializers, WHOLE_IMAGE));
             this._dragging = (__runInitializers(this, _draft_extraInitializers), false);
+            /** The pending end of a wheel gesture, `null` when none is under way. */
+            this._wheelTimer = null;
             /** Removes the listeners of the gesture in progress, if any. */
             this._releaseGesture = null;
             this._stop = (event) => event.stopPropagation();
             this._onOutsidePointer = (event) => {
                 if (event.composedPath().includes(this))
                     return;
+                this._commitWheel();
                 this.onExit();
             };
             this._onKeydown = (event) => {
@@ -107,8 +120,31 @@ let ImageCropOverlay = (() => {
                     return;
                 event.preventDefault();
                 event.stopPropagation();
+                this._commitWheel();
                 this.onExit();
             };
+            this._onWheel = (event) => {
+                event.preventDefault();
+                event.stopPropagation();
+                if (this._dragging)
+                    return;
+                const { width, height, cos, sin, scale } = this._geometry();
+                if (width <= 0 || height <= 0)
+                    return;
+                // The pointer in the source's normalised coordinates: the frame is the
+                // whole source, possibly rotated about its centre.
+                const box = this.getBoundingClientRect();
+                const cdx = event.clientX - (box.left + box.width / 2);
+                const cdy = event.clientY - (box.top + box.height / 2);
+                const px = ((cdx * cos + cdy * sin) / scale + width / 2) / width;
+                const py = ((-cdx * sin + cdy * cos) / scale + height / 2) / height;
+                // A line or page delta (Firefox) counts as one full step per unit.
+                const deltaY = event.deltaMode === 0 ? event.deltaY : event.deltaY * 100;
+                this.draft = zoomCrop(this.draft, cropWheelFactor(deltaY), Math.min(Math.max(px, 0), 1), Math.min(Math.max(py, 0), 1), this.ratio);
+                if (this._wheelTimer !== null)
+                    clearTimeout(this._wheelTimer);
+                this._wheelTimer = setTimeout(() => this._commitWheel(), WHEEL_COMMIT_DELAY_MS);
+            };
         }
         static {
             const _metadata = typeof Symbol === "function" && Symbol.metadata ? Object.create(_classSuper[Symbol.metadata] ?? null) : void 0;
@@ -229,6 +265,20 @@ let ImageCropOverlay = (() => {
         #draft_accessor_storage;
         get draft() { return this.#draft_accessor_storage; }
         set draft(value) { this.#draft_accessor_storage = value; }
+        /** Ends the wheel gesture under way, if any, with its one write. */
+        _commitWheel() {
+            if (this._wheelTimer === null)
+                return;
+            clearTimeout(this._wheelTimer);
+            this._wheelTimer = null;
+            this.onCommit(this.draft);
+        }
+        _dropWheel() {
+            if (this._wheelTimer === null)
+                return;
+            clearTimeout(this._wheelTimer);
+            this._wheelTimer = null;
+        }
         /**
          * The document-wide listeners (a press elsewhere, Escape, Enter) live only
          * as long as this element: the frame is rendered while it is open and
@@ -237,15 +287,22 @@ let ImageCropOverlay = (() => {
         connectedCallback() {
             super.connectedCallback();
             this.disposables.add(() => this._releaseGesture?.());
+            this.disposables.add(() => this._dropWheel());
             this.disposables.addFromEvent(this, 'pointerdown', this._stop);
             this.disposables.addFromEvent(this, 'click', this._stop);
             this.disposables.addFromEvent(this, 'dblclick', this._stop);
+            this.disposables.addFromEvent(this, 'wheel', this._onWheel, {
+                passive: false,
+            });
             this.disposables.addFromEvent(document, 'pointerdown', this._onOutsidePointer, true);
             this.disposables.addFromEvent(document, 'keydown', this._onKeydown, true);
         }
         willUpdate(changed) {
-            if (changed.has('crop') && !this._dragging)
-                this.draft = this.crop;
+            if (!changed.has('crop') || this._dragging)
+                return;
+            // A crop written meanwhile (a preset, a peer) wins over a pending scroll.
+            this._dropWheel();
+            this.draft = this.crop;
         }
         /**
          * Client pixels per layout pixel, read from the rendered box: the canvas
@@ -267,6 +324,7 @@ let ImageCropOverlay = (() => {
                 return;
             event.preventDefault();
             event.stopPropagation();
+            this._commitWheel();
             const start = this.draft;
             const originX = event.clientX;
             const originY = event.clientY;

package/dist/_pkgs/affine-block-image/edgeless-clipboard-config.d.ts

@@ -1,6 +1,7 @@
-import { EdgelessClipboardConfig } from '../affine-block-surface/index.js';
+import { type ClipboardConfigCreationContext, EdgelessClipboardConfig, type PreparedClipboardBlock } from '../affine-block-surface/index.js';
 import { type BlockSnapshot } from '../store/index.js';
 export declare class EdgelessClipboardImageConfig extends EdgelessClipboardConfig {
     static readonly key = "affine:image";
-    createBlock(image: BlockSnapshot): Promise<string | null>;
+    prepare(image: BlockSnapshot): Promise<PreparedClipboardBlock | null>;
+    createBlock(image: BlockSnapshot, context: ClipboardConfigCreationContext): Promise<string | null>;
 }

package/dist/_pkgs/affine-block-image/edgeless-clipboard-config.js

@@ -1,25 +1,31 @@
-import { EdgelessClipboardConfig } from '../affine-block-surface/index.js';
+import { EdgelessClipboardConfig, } from '../affine-block-surface/index.js';
 import {} from '../store/index.js';
 export class EdgelessClipboardImageConfig extends EdgelessClipboardConfig {
     static { this.key = 'affine:image'; }
-    async createBlock(image) {
+    async prepare(image) {
         const { xywh, rotate, sourceId, size, width, height, caption, crop } = image.props;
         if (!this.surface)
             return null;
         if (!(await this.std.workspace.blobSync.get(sourceId))) {
             return null;
         }
-        return this.crud.addBlock('affine:image', {
-            caption,
-            sourceId,
-            xywh,
-            rotate,
-            size,
-            width,
-            height,
-            // The box above is the cropped one: without its crop the copy would
-            // stretch the whole picture into it (ADR 0037).
-            crop,
-        }, this.surface.model.id);
+        const surfaceId = this.surface.model.id;
+        return {
+            write: () => this.crud.addBlock('affine:image', {
+                caption,
+                sourceId,
+                xywh,
+                rotate,
+                size,
+                width,
+                height,
+                // The box above is the cropped one: without its crop the copy
+                // would stretch the whole picture into it (ADR 0037).
+                crop,
+            }, surfaceId),
+        };
+    }
+    createBlock(image, context) {
+        return this.createPreparedBlock(image, context);
     }
 }

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

@@ -148,6 +148,7 @@ let ImageBlockComponent = (() => {
             this.resourceController.setEngine(this.std.store.blobSync);
             this.disposables.add(this.resourceController.subscribe());
             this.disposables.add(this.resourceController);
+            this.disposables.add(() => this.cropController.stop());
             this.disposables.add(this.model.props.sourceId$.subscribe(() => {
                 this.refreshData();
             }));

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

@@ -133,6 +133,9 @@ let ImageEdgelessBlockComponent = (() => {
             this.resourceController.setEngine(this.std.store.blobSync);
             this.disposables.add(this.resourceController.subscribe());
             this.disposables.add(this.resourceController);
+            // A crop frame left open would keep the canvas locked and the image in
+            // editing state after the block is gone (ADR 0037, 2026-10-27).
+            this.disposables.add(() => this.cropController.stop());
             this.disposables.add(this.model.props.sourceId$.subscribe(() => {
                 this.refreshData();
             }));

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

@@ -6,6 +6,8 @@ export * from './image-block.js';
 export * from './image-edgeless-block.js';
 export * from './image-service.js';
 export * from './image-spec.js';
+export { imageReplaceCommands, REPLACE_IMAGE_WITH_IMAGE, REPLACE_IMAGE_WITH_SHAPE, REPLACE_SHAPE_WITH_IMAGE, } from './replace/commands.js';
+export { replaceImageWithShape, replaceShapeWithImage, } from './replace/replace-model.js';
 export * from './turbo/image-layout-handler.js';
 export * from './turbo/image-painter.worker.js';
 export { addImages, addSiblingImageBlocks, downloadImageBlob } from './utils.js';

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

@@ -6,6 +6,8 @@ export * from './image-block.js';
 export * from './image-edgeless-block.js';
 export * from './image-service.js';
 export * from './image-spec.js';
+export { imageReplaceCommands, REPLACE_IMAGE_WITH_IMAGE, REPLACE_IMAGE_WITH_SHAPE, REPLACE_SHAPE_WITH_IMAGE, } from './replace/commands.js';
+export { replaceImageWithShape, replaceShapeWithImage, } from './replace/replace-model.js';
 export * from './turbo/image-layout-handler.js';
 export * from './turbo/image-painter.worker.js';
 export { addImages, addSiblingImageBlocks, downloadImageBlob } from './utils.js';

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

@@ -0,0 +1,68 @@
+import { ImageBlockModel, ShapeType } from '../../affine-model/index.js';
+import type { AnyCommandDescriptor, BlockStdScope, CommandDescriptor } from '../../std/index.js';
+import { z } from 'zod';
+/**
+ * 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 declare const replaceElementParams: z.ZodObject<{
+    elementId: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    elementId?: string | undefined;
+}, {
+    elementId?: string | undefined;
+}>;
+export type ReplaceElementParams = z.infer<typeof replaceElementParams>;
+/**
+ * « 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 declare const replaceWithShapeParams: z.ZodObject<{
+    elementId: z.ZodOptional<z.ZodString>;
+} & {
+    shapeType: z.ZodOptional<z.ZodNativeEnum<typeof ShapeType>>;
+    radius: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    radius?: number | undefined;
+    shapeType?: ShapeType | undefined;
+    elementId?: string | undefined;
+}, {
+    radius?: number | undefined;
+    shapeType?: ShapeType | undefined;
+    elementId?: string | undefined;
+}>;
+export type ReplaceWithShapeParams = z.infer<typeof replaceWithShapeParams>;
+/** The shape the command would replace, or `null`. */
+export declare function replaceableShape(std: BlockStdScope, params?: unknown): import("../../affine-model/index.js").ShapeElementModel | null;
+/** The canvas image the command would replace, or `null`. */
+export declare function replaceableImage(std: BlockStdScope, params?: unknown): ImageBlockModel | 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 declare function replaceablePicture(std: BlockStdScope, params?: unknown): ImageBlockModel | null;
+export declare const REPLACE_SHAPE_WITH_IMAGE = "canvas.shape.replaceWithImage";
+export declare const REPLACE_IMAGE_WITH_SHAPE = "canvas.image.replaceWithShape";
+export declare const REPLACE_IMAGE_WITH_IMAGE = "canvas.image.replaceWithImage";
+export declare const replaceShapeWithImageCommand: CommandDescriptor<ReplaceElementParams>;
+export declare const replaceImageWithShapeCommand: CommandDescriptor<ReplaceWithShapeParams>;
+/**
+ * « 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 declare const replaceImageWithImageCommand: CommandDescriptor<ReplaceElementParams>;
+export declare const imageReplaceCommands: AnyCommandDescriptor[];