@formicoidea/labre-core 0.41.0 → 0.42.0

package/dist/_pkgs/affine-widget-edgeless-toolbar/panel/font-weight-and-style-panel.js

@@ -34,16 +34,23 @@ var __runInitializers = (this && this.__runInitializers) || function (thisArg, i
 };
 import { TextUtils } from '../../affine-block-surface/index.js';
 import { FontFamily, FontFamilyMap, FontStyle, FontWeight, } from '../../affine-model/index.js';
-import { FONT_STYLE_ITALIC, FONT_WEIGHT_LIGHT, FONT_WEIGHT_REGULAR, FONT_WEIGHT_SEMIBOLD, translateKey, } from '../../affine-shared/services/index.js';
+import { FONT_STYLE_ITALIC, FONT_WEIGHT_BOLD, FONT_WEIGHT_LIGHT, FONT_WEIGHT_REGULAR, FONT_WEIGHT_SEMIBOLD, translateKey, } from '../../affine-shared/services/index.js';
 import { DoneIcon } from '@blocksuite/icons/lit';
 import { css, html, LitElement, nothing } from 'lit';
 import { property } from 'lit/decorators.js';
 import { join } from 'lit/directives/join.js';
 import { repeat } from 'lit/directives/repeat.js';
+/**
+ * How each weight is named. The panel does not offer this list: it offers the
+ * faces the current family actually has loaded, and only borrows the wording
+ * from here — so a family that ships no 700 file simply never draws a Bold
+ * row.
+ */
 const FONT_WEIGHT_CHOOSE = [
     [FontWeight.Light, FONT_WEIGHT_LIGHT],
     [FontWeight.Regular, FONT_WEIGHT_REGULAR],
     [FontWeight.SemiBold, FONT_WEIGHT_SEMIBOLD],
+    [FontWeight.Bold, FONT_WEIGHT_BOLD],
 ];
 let EdgelessFontWeightAndStylePanel = (() => {
     let _classSuper = LitElement;

package/dist/_pkgs/affine-widget-edgeless-toolbar/placement/artefact-ghost-overlay.d.ts

@@ -0,0 +1,42 @@
+import { type RoughCanvas, ToolOverlay } from '../../affine-block-surface/index.js';
+import type { Bound } from '../../global/gfx/index.js';
+import type { GfxController, GfxPrimitiveElementModel } from '../../std/gfx/index.js';
+/**
+ * The ghost an armed {@link ArtefactPlacementTool} leaves under the cursor: the
+ * artefact itself, painted by the very renderers that will paint it once it is
+ * placed, at full opacity (PO decision, 2026-09-16).
+ *
+ * The elements are DETACHED models (`createDetachedElement`), built once by the
+ * tool from the recording of the command — never per frame, and never in the
+ * document. Each frame only runs the renderers, in paint order.
+ *
+ * When nothing could be built — the recording threw, or recorded nothing the
+ * surface can build — the ghost falls back to what the tool can still promise:
+ * a dashed footprint and the command's label under it. A real preview carries
+ * its own words, so it gets no label.
+ *
+ * Like `ShapeOverlay`, everything is positioned from {@link ToolOverlay.x} /
+ * {@link ToolOverlay.y} — the cursor in model coordinates — and the recorded
+ * boxes are offsets around it, because the recording ran against a viewport
+ * whose centre was the origin. The same offset is what the placement re-applies
+ * for real.
+ */
+export declare class ArtefactGhostOverlay extends ToolOverlay {
+    /** The footprint, relative to the cursor. */
+    bound: Bound;
+    /** What the command is called, in the reader's language. */
+    label: string;
+    /** The artefact's drawable elements, in paint order, with their renderer. */
+    private readonly _preview;
+    constructor(gfx: GfxController, bound: Bound, label: string, models?: GfxPrimitiveElementModel[]);
+    /** Whether the artefact itself is drawn, rather than the fallback box. */
+    get drawsArtefact(): boolean;
+    render(ctx: CanvasRenderingContext2D, rc: RoughCanvas): void;
+    /**
+     * What the surface's render loop does per element, with the cursor in place
+     * of the element's position: the context is already in model coordinates
+     * here, so the element's matrix is that transform moved to cursor + offset.
+     */
+    private _renderArtefact;
+    private _renderFootprint;
+}

package/dist/_pkgs/affine-widget-edgeless-toolbar/placement/artefact-ghost-overlay.js

@@ -0,0 +1,100 @@
+import { CanvasRenderer, ElementRendererIdentifier, ToolOverlay, } from '../../affine-block-surface/index.js';
+import { ThemeProvider } from '../../affine-shared/services/index.js';
+/** Gap between the bottom of the footprint and the baseline of the label. */
+const LABEL_GAP = 16;
+/** Label size in SCREEN pixels; divided by the zoom before it is drawn. */
+const LABEL_SIZE = 12;
+/**
+ * The ghost an armed {@link ArtefactPlacementTool} leaves under the cursor: the
+ * artefact itself, painted by the very renderers that will paint it once it is
+ * placed, at full opacity (PO decision, 2026-09-16).
+ *
+ * The elements are DETACHED models (`createDetachedElement`), built once by the
+ * tool from the recording of the command — never per frame, and never in the
+ * document. Each frame only runs the renderers, in paint order.
+ *
+ * When nothing could be built — the recording threw, or recorded nothing the
+ * surface can build — the ghost falls back to what the tool can still promise:
+ * a dashed footprint and the command's label under it. A real preview carries
+ * its own words, so it gets no label.
+ *
+ * Like `ShapeOverlay`, everything is positioned from {@link ToolOverlay.x} /
+ * {@link ToolOverlay.y} — the cursor in model coordinates — and the recorded
+ * boxes are offsets around it, because the recording ran against a viewport
+ * whose centre was the origin. The same offset is what the placement re-applies
+ * for real.
+ */
+export class ArtefactGhostOverlay extends ToolOverlay {
+    constructor(gfx, bound, label, models = []) {
+        super(gfx);
+        this.bound = bound;
+        this.label = label;
+        // Resolved once: a type without a canvas renderer is skipped silently, as
+        // the surface's own render loop skips it.
+        this._preview = models.flatMap(model => {
+            const render = gfx.std.getOptional(ElementRendererIdentifier(model.type));
+            return render ? [{ model, render }] : [];
+        });
+    }
+    /** Whether the artefact itself is drawn, rather than the fallback box. */
+    get drawsArtefact() {
+        return this._preview.length > 0;
+    }
+    render(ctx, rc) {
+        ctx.globalAlpha = this.globalAlpha;
+        if (this.globalAlpha === 0)
+            return;
+        const renderer = this.gfx.surfaceComponent
+            ?.renderer;
+        if (this.drawsArtefact && renderer instanceof CanvasRenderer) {
+            this._renderArtefact(ctx, rc, renderer);
+        }
+        else {
+            this._renderFootprint(ctx);
+        }
+    }
+    /**
+     * What the surface's render loop does per element, with the cursor in place
+     * of the element's position: the context is already in model coordinates
+     * here, so the element's matrix is that transform moved to cursor + offset.
+     */
+    _renderArtefact(ctx, rc, renderer) {
+        const base = ctx.getTransform();
+        const viewportBound = this.gfx.viewport.viewportBounds;
+        for (const { model, render } of this._preview) {
+            const [x, y] = model.deserializedXYWH;
+            ctx.save();
+            ctx.globalAlpha = model.opacity ?? 1;
+            render(model, ctx, base.translate(this.x + x, this.y + y), renderer, rc, viewportBound);
+            ctx.restore();
+        }
+    }
+    _renderFootprint(ctx) {
+        const theme = this.gfx.std.get(ThemeProvider);
+        const stroke = theme.getCssVariableColor('--affine-primary-color');
+        const text = theme.getCssVariableColor('--affine-text-secondary-color');
+        // Chrome, not content: the outline and the label keep their size on screen
+        // whatever the zoom, the way the polygon tool's own indicators do.
+        const zoom = this.gfx.viewport.zoom;
+        const { bound } = this;
+        const x = this.x + bound.x;
+        const y = this.y + bound.y;
+        const radius = Math.min(8 / zoom, bound.w / 4, bound.h / 4);
+        ctx.save();
+        ctx.beginPath();
+        ctx.roundRect(x, y, bound.w, bound.h, radius);
+        ctx.strokeStyle = stroke;
+        ctx.lineWidth = 1.5 / zoom;
+        ctx.setLineDash([6 / zoom, 4 / zoom]);
+        ctx.stroke();
+        if (this.label) {
+            ctx.setLineDash([]);
+            ctx.font = `${LABEL_SIZE / zoom}px var(--affine-font-family, sans-serif)`;
+            ctx.fillStyle = text;
+            ctx.textAlign = 'center';
+            ctx.textBaseline = 'top';
+            ctx.fillText(this.label, x + bound.w / 2, y + bound.h + LABEL_GAP / zoom - LABEL_SIZE / zoom);
+        }
+        ctx.restore();
+    }
+}

package/dist/_pkgs/affine-widget-edgeless-toolbar/placement/artefact-placement-tool.d.ts

@@ -0,0 +1,100 @@
+import { type AnyCommandDescriptor, type BlockStdScope, type CommandOwner, type PointerEventState } from '../../std/index.js';
+import { BaseTool, type GfxController } from '../../std/gfx/index.js';
+export type ArtefactPlacementOption = {
+    /** Whose senior menu armed this, and therefore whose row Shift+S walks. */
+    owner: CommandOwner;
+    command: AnyCommandDescriptor;
+};
+/**
+ * ONE tool for every framework's artefacts: pick one from a senior menu and it
+ * is not created, it is ARMED — a ghost follows the cursor and the click says
+ * where (PO decision, 2026-09-16).
+ *
+ * The shape tool has always worked this way, and a framework artefact is a
+ * shape the framework named. Before this, an artefact landed at the viewport
+ * centre whatever the author was looking at, and putting it where they meant it
+ * to go was a second gesture with a mouse held down.
+ *
+ * It is generic on purpose. Nothing here knows what a Wardley component or a
+ * BPMN gateway is: the armed {@link CommandDescriptor} carries its own label,
+ * its own creation body and its own telemetry, and the footprint is MEASURED by
+ * running that body against the recording fake (`recordAction`) rather than
+ * declared a second time. A ninth framework arms this tool by existing.
+ *
+ * What it deliberately does not do:
+ *
+ * - **Telemetry.** Arming and cycling emit nothing and record no usage, exactly
+ *   as choosing a shape variant does. The one emission still happens where it
+ *   always did — inside {@link runCommand}, at placement — so the numbers a
+ *   framework already reports are unchanged, and a user who arms an artefact
+ *   and changes their mind has not "used" it.
+ * - **Drag to size.** A framework artefact has a size its framework chose; the
+ *   click places that size. Out of scope, deliberately.
+ */
+export declare class ArtefactPlacementTool extends BaseTool<ArtefactPlacementOption> {
+    static toolName: string;
+    private _ghost;
+    private get _surfaceComponent();
+    activate(): void;
+    deactivate(): void;
+    clearOverlay(): void;
+    /**
+     * Record the armed command once, and hang its ghost off the cursor.
+     *
+     * Once per arming and per cycle, never per pointer move: the recording runs
+     * the command's whole creation body against a fake and the preview builds a
+     * model per element, which is cheap but not free — and neither can change
+     * between two mouse positions.
+     *
+     * An artefact made of connectors only gets no ghost at all: a connector is
+     * not previewed (PO decision, 2026-09-16), and the crosshair alone says the
+     * next click places something.
+     */
+    createOverlay(): void;
+    /**
+     * Place the artefact under the cursor.
+     *
+     * The command is not asked WHERE to create — every one of them creates around
+     * the viewport centre, and teaching eight frameworks' worth of actions to take
+     * a point would be the per-framework code this tool exists to avoid. So the
+     * command runs as it always has, and what it created is moved by the offset
+     * between the centre it aimed at and the point the user clicked. That offset
+     * is read BEFORE the run, because a command may move the viewport.
+     */
+    click(e: PointerEventState): void;
+    pointerMove(e: PointerEventState): void;
+    pointerOut(e: PointerEventState): void;
+    /** A framework artefact keeps the size its framework chose; a drag is a click. */
+    dragStart(_e: PointerEventState): void;
+    dragMove(_e: PointerEventState): void;
+    dragEnd(_e: PointerEventState): void;
+}
+/** The armed artefact, or `null` when the editor is on any other tool. */
+export declare function armedArtefact(gfx: GfxController): ArtefactPlacementOption | null;
+/** Arm `command`; the ghost appears with the next pointer move. */
+export declare function armArtefact(gfx: GfxController, owner: CommandOwner, command: AnyCommandDescriptor): void;
+/**
+ * The artefacts of one owner, in the order its senior menu shows them.
+ *
+ * The MENU's row and not the whole catalogue: cycling is a keyboard walk along
+ * a row of buttons the user is looking at, and a Shift+S that stepped onto an
+ * artefact filed away in the sidepanel would move the ghost with nothing on
+ * screen to explain it. An owner past the fourteen-slot cap therefore cycles
+ * through its thirteen ranked artefacts; the rest stay one catalogue away.
+ *
+ * `kind` is what decides, not the owner: an entry of kind `'tool'` — a link
+ * tool, the evolution arrow, the Wardley area polygon — arms a gesture of its
+ * own and has no footprint to ghost, so it is never armed here and never
+ * stepped onto.
+ */
+export declare function artefactCommandsFor(std: BlockStdScope, owner: CommandOwner): AnyCommandDescriptor[];
+/**
+ * Arm the artefact `dir` steps along the owner's row, wrapping at both ends.
+ * Returns false when nothing is armed, so a caller can fall through to whatever
+ * the keystroke means otherwise.
+ *
+ * An artefact armed from the catalogue is not in the row: a backwards step then
+ * enters on the row's last entry, a forwards one on its first — the same "enter
+ * from nothing" the open menu's highlight gives.
+ */
+export declare function cycleArmedArtefact(gfx: GfxController, dir: 1 | -1): boolean;

package/dist/_pkgs/affine-widget-edgeless-toolbar/placement/artefact-placement-tool.js

@@ -0,0 +1,274 @@
+import { DefaultTool, EXCLUDING_MOUSE_OUT_CLASS_LIST, recordAction, sortIndex, } from '../../affine-block-surface/index.js';
+import { translateKey } from '../../affine-shared/services/index.js';
+import { hasClassNameInList } from '../../affine-shared/utils/index.js';
+import { Bound } from '../../global/gfx/index.js';
+import { runCommand, } from '../../std/index.js';
+import { BaseTool, GfxGroupLikeElementModel, } from '../../std/gfx/index.js';
+import { seniorMenuSelection } from '../menu/senior-menu-selection.js';
+import { ArtefactGhostOverlay } from './artefact-ghost-overlay.js';
+import { collectCreated, translateCreated } from './translate-created.js';
+/** The ghost of an artefact nobody could measure. */
+const FALLBACK_FOOTPRINT = new Bound(-60, -30, 120, 60);
+/**
+ * ONE tool for every framework's artefacts: pick one from a senior menu and it
+ * is not created, it is ARMED — a ghost follows the cursor and the click says
+ * where (PO decision, 2026-09-16).
+ *
+ * The shape tool has always worked this way, and a framework artefact is a
+ * shape the framework named. Before this, an artefact landed at the viewport
+ * centre whatever the author was looking at, and putting it where they meant it
+ * to go was a second gesture with a mouse held down.
+ *
+ * It is generic on purpose. Nothing here knows what a Wardley component or a
+ * BPMN gateway is: the armed {@link CommandDescriptor} carries its own label,
+ * its own creation body and its own telemetry, and the footprint is MEASURED by
+ * running that body against the recording fake (`recordAction`) rather than
+ * declared a second time. A ninth framework arms this tool by existing.
+ *
+ * What it deliberately does not do:
+ *
+ * - **Telemetry.** Arming and cycling emit nothing and record no usage, exactly
+ *   as choosing a shape variant does. The one emission still happens where it
+ *   always did — inside {@link runCommand}, at placement — so the numbers a
+ *   framework already reports are unchanged, and a user who arms an artefact
+ *   and changes their mind has not "used" it.
+ * - **Drag to size.** A framework artefact has a size its framework chose; the
+ *   click places that size. Out of scope, deliberately.
+ */
+export class ArtefactPlacementTool extends BaseTool {
+    constructor() {
+        super(...arguments);
+        this._ghost = null;
+    }
+    static { this.toolName = 'artefact-placement'; }
+    get _surfaceComponent() {
+        return this.gfx.surfaceComponent;
+    }
+    activate() {
+        this.createOverlay();
+    }
+    deactivate() {
+        this.clearOverlay();
+    }
+    clearOverlay() {
+        if (!this._ghost)
+            return;
+        this._ghost.dispose();
+        this._surfaceComponent?.renderer.removeOverlay(this._ghost);
+        this._ghost = null;
+        this._surfaceComponent?.renderer.refresh();
+    }
+    /**
+     * Record the armed command once, and hang its ghost off the cursor.
+     *
+     * Once per arming and per cycle, never per pointer move: the recording runs
+     * the command's whole creation body against a fake and the preview builds a
+     * model per element, which is cheap but not free — and neither can change
+     * between two mouse positions.
+     *
+     * An artefact made of connectors only gets no ghost at all: a connector is
+     * not previewed (PO decision, 2026-09-16), and the crosshair alone says the
+     * next click places something.
+     */
+    createOverlay() {
+        this.clearOverlay();
+        const { command } = this.activatedOption;
+        if (!command)
+            return;
+        const preview = previewOf(this.gfx, command);
+        if (!preview)
+            return;
+        this._ghost = new ArtefactGhostOverlay(this.gfx, preview.bound, translateKey(this.std, command.labelKey, command.labelFallback), preview.models);
+        this._surfaceComponent?.renderer.addOverlay(this._ghost);
+    }
+    /**
+     * Place the artefact under the cursor.
+     *
+     * The command is not asked WHERE to create — every one of them creates around
+     * the viewport centre, and teaching eight frameworks' worth of actions to take
+     * a point would be the per-framework code this tool exists to avoid. So the
+     * command runs as it always has, and what it created is moved by the offset
+     * between the centre it aimed at and the point the user clicked. That offset
+     * is read BEFORE the run, because a command may move the viewport.
+     */
+    click(e) {
+        const { command } = this.activatedOption;
+        this.clearOverlay();
+        if (!command)
+            return;
+        const { viewport } = this.gfx;
+        const [x, y] = viewport.toModelCoord(e.point.x, e.point.y);
+        const dx = x - viewport.centerX;
+        const dy = y - viewport.centerY;
+        this.doc.captureSync();
+        // THE bottleneck, not a shortcut past it: the placement is an invocation
+        // like any other, so `FrameworkElementAdded` and the usage measure are
+        // emitted exactly where they were before the tool existed.
+        const created = collectCreated(this.gfx, () => {
+            runCommand(this.std, command, {
+                surface: 'senior-menu',
+                source: 'toolbar:general',
+            });
+        });
+        const placed = translateCreated(this.gfx, created, dx, dy);
+        // `setTool` clears the selection, so the selection goes after it.
+        this.gfx.tool.setTool(DefaultTool);
+        if (placed.length) {
+            this.gfx.selection.set({ elements: placed, editing: false });
+        }
+    }
+    pointerMove(e) {
+        if (!this._ghost)
+            return;
+        if (this._ghost.globalAlpha === 0)
+            this._ghost.globalAlpha = 1;
+        const [x, y] = this.gfx.viewport.toModelCoord(e.x, e.y);
+        this._ghost.x = x;
+        this._ghost.y = y;
+        this._surfaceComponent?.refresh();
+    }
+    pointerOut(e) {
+        if (e.raw.relatedTarget &&
+            hasClassNameInList(e.raw.relatedTarget, EXCLUDING_MOUSE_OUT_CLASS_LIST))
+            return;
+        if (!this._ghost)
+            return;
+        this._ghost.globalAlpha = 0;
+        this._surfaceComponent?.refresh();
+    }
+    /** A framework artefact keeps the size its framework chose; a drag is a click. */
+    dragStart(_e) { }
+    dragMove(_e) { }
+    dragEnd(_e) { }
+}
+/**
+ * What the command would draw, recorded and BUILT by running it against
+ * nothing: its footprint, and a detached model per drawable element, in paint
+ * order. `null` when there is nothing to show but the crosshair.
+ *
+ * The recording's viewport centre is the origin, so every recorded box is
+ * already the offset around a real centre — and therefore around the cursor.
+ * The records go to `createDetachedElement` as they were handed to the CRUD,
+ * so a seed string becomes its `Y.Text` through the element's own `propsToY`,
+ * exactly as it will at insertion; the host's `TranslationProvider` makes the
+ * seeds come out in the author's language, as they will once placed.
+ *
+ * Skipped: connectors (never previewed) and group-likes, whose renderers draw
+ * selection chrome and look their children up in the document — the children
+ * are drawn on their own. A record the surface cannot build is skipped too.
+ *
+ * A command the fake cannot serve throws by design (it answers only the
+ * members creation actions touch); that is not an error worth a console line
+ * here, it just means the ghost falls back to a plain box rather than the tool
+ * refusing to arm. So does a recording in which nothing could be built.
+ */
+function previewOf(gfx, command) {
+    let recorded;
+    try {
+        recorded = recordAction((std) => {
+            // An async body records nothing it does after its first `await`, and
+            // then fails on the fake: that late failure is the same "cannot
+            // preview", not an unhandled rejection in the console.
+            Promise.resolve(command.run(std, { surface: 'senior-menu', source: 'internal' })).catch(() => { });
+        }, { host: gfx.std });
+    }
+    catch {
+        return { bound: FALLBACK_FOOTPRINT, models: [] };
+    }
+    const { records } = recorded;
+    if (records.length > 0 && records.every(r => r['type'] === 'connector')) {
+        return null;
+    }
+    // Paint order as the surface derives it: a group's children sort under the
+    // group's own index, even though the group itself is not drawn.
+    const groupIndexMap = new Map();
+    for (const record of records) {
+        const children = record['children'];
+        if (record['type'] !== 'group' || typeof children !== 'object')
+            continue;
+        const group = { id: String(record['id']), index: String(record['index']) };
+        for (const childId of Object.keys(children ?? {})) {
+            groupIndexMap.set(childId, group);
+        }
+    }
+    const ordered = records
+        .map(record => ({
+        record,
+        id: String(record['id']),
+        index: String(record['index']),
+    }))
+        .sort((a, b) => sortIndex(a, b, groupIndexMap));
+    const { surface } = gfx;
+    const models = [];
+    for (const { record, id } of ordered) {
+        const type = String(record['type']);
+        const Ctor = surface?.getConstructor(type);
+        if (!surface ||
+            !Ctor ||
+            type === 'connector' ||
+            Ctor.prototype instanceof GfxGroupLikeElementModel) {
+            continue;
+        }
+        try {
+            models.push(surface.createDetachedElement({ ...record, type, id }));
+        }
+        catch {
+            // Unbuildable here means unpaintable here; the rest still draws.
+        }
+    }
+    return { bound: recorded.bound ?? FALLBACK_FOOTPRINT, models };
+}
+/** The armed artefact, or `null` when the editor is on any other tool. */
+export function armedArtefact(gfx) {
+    const { toolType, options } = gfx.tool.currentToolOption$.value ?? {};
+    if (toolType?.toolName !== ArtefactPlacementTool.toolName)
+        return null;
+    const armed = options;
+    return armed?.command ? armed : null;
+}
+/** Arm `command`; the ghost appears with the next pointer move. */
+export function armArtefact(gfx, owner, command) {
+    gfx.tool.setTool(ArtefactPlacementTool, { owner, command });
+}
+/**
+ * The artefacts of one owner, in the order its senior menu shows them.
+ *
+ * The MENU's row and not the whole catalogue: cycling is a keyboard walk along
+ * a row of buttons the user is looking at, and a Shift+S that stepped onto an
+ * artefact filed away in the sidepanel would move the ghost with nothing on
+ * screen to explain it. An owner past the fourteen-slot cap therefore cycles
+ * through its thirteen ranked artefacts; the rest stay one catalogue away.
+ *
+ * `kind` is what decides, not the owner: an entry of kind `'tool'` — a link
+ * tool, the evolution arrow, the Wardley area polygon — arms a gesture of its
+ * own and has no footprint to ghost, so it is never armed here and never
+ * stepped onto.
+ */
+export function artefactCommandsFor(std, owner) {
+    return seniorMenuSelection(std, owner).commands.filter(command => command.kind === 'artefact');
+}
+/**
+ * Arm the artefact `dir` steps along the owner's row, wrapping at both ends.
+ * Returns false when nothing is armed, so a caller can fall through to whatever
+ * the keystroke means otherwise.
+ *
+ * An artefact armed from the catalogue is not in the row: a backwards step then
+ * enters on the row's last entry, a forwards one on its first — the same "enter
+ * from nothing" the open menu's highlight gives.
+ */
+export function cycleArmedArtefact(gfx, dir) {
+    const armed = armedArtefact(gfx);
+    if (!armed)
+        return false;
+    const commands = artefactCommandsFor(gfx.std, armed.owner);
+    if (commands.length === 0)
+        return false;
+    const current = commands.findIndex(command => command.id === armed.command.id);
+    const next = current < 0
+        ? dir === 1
+            ? 0
+            : commands.length - 1
+        : (current + dir + commands.length) % commands.length;
+    armArtefact(gfx, armed.owner, commands[next]);
+    return true;
+}

package/dist/_pkgs/affine-widget-edgeless-toolbar/placement/index.d.ts

@@ -0,0 +1,3 @@
+export * from './artefact-ghost-overlay.js';
+export * from './artefact-placement-tool.js';
+export * from './translate-created.js';

package/dist/_pkgs/affine-widget-edgeless-toolbar/placement/index.js

@@ -0,0 +1,3 @@
+export * from './artefact-ghost-overlay.js';
+export * from './artefact-placement-tool.js';
+export * from './translate-created.js';

package/dist/_pkgs/affine-widget-edgeless-toolbar/placement/translate-created.d.ts

@@ -0,0 +1,25 @@
+import type { GfxController } from '../../std/gfx/index.js';
+/**
+ * Run `body` and report the ids of everything it put on the board — canvas
+ * elements and canvas blocks alike.
+ *
+ * Both subscriptions are synchronous: a Yjs observer fires when the transaction
+ * commits, inside the `addElement` / `addBlock` call, so an action that creates
+ * on the spot is fully accounted for by the time `body` returns. An action that
+ * creates from a promise is NOT, and its artefact is left where the command put
+ * it — which is today's behaviour for every command, so nothing regresses.
+ */
+export declare function collectCreated(gfx: GfxController, body: () => void): string[];
+/**
+ * Move a freshly created drawing by `(dx, dy)`, and report what is left to
+ * select.
+ *
+ * Only the TOP-LEVEL items move. An element the same run filed inside a group
+ * it also created is carried by that group, and moving it twice would tear the
+ * drawing apart. A group is moved through its children — `GfxGroupLikeElement`'s
+ * `xywh` setter is a deliberate no-op, its box being derived from what it holds
+ * — which is exactly what {@link updateXYWH} does, along with a connector's free
+ * endpoints (an anchored one simply follows what it is tied to) and a note's
+ * collapsed height. Hence no second opinion here.
+ */
+export declare function translateCreated(gfx: GfxController, ids: string[], dx: number, dy: number): string[];

package/dist/_pkgs/affine-widget-edgeless-toolbar/placement/translate-created.js

@@ -0,0 +1,67 @@
+import { EdgelessCRUDIdentifier, updateXYWH, } from '../../affine-block-surface/index.js';
+import { Bound } from '../../global/gfx/index.js';
+/**
+ * Run `body` and report the ids of everything it put on the board — canvas
+ * elements and canvas blocks alike.
+ *
+ * Both subscriptions are synchronous: a Yjs observer fires when the transaction
+ * commits, inside the `addElement` / `addBlock` call, so an action that creates
+ * on the spot is fully accounted for by the time `body` returns. An action that
+ * creates from a promise is NOT, and its artefact is left where the command put
+ * it — which is today's behaviour for every command, so nothing regresses.
+ */
+export function collectCreated(gfx, body) {
+    const ids = [];
+    const subscriptions = [
+        gfx.surface?.elementAdded.subscribe(({ id }) => {
+            ids.push(id);
+        }),
+        gfx.std.store.slots.blockUpdated.subscribe(payload => {
+            if (payload.type === 'add')
+                ids.push(payload.id);
+        }),
+    ];
+    try {
+        body();
+    }
+    finally {
+        subscriptions.forEach(subscription => subscription?.unsubscribe());
+    }
+    return ids;
+}
+/**
+ * Move a freshly created drawing by `(dx, dy)`, and report what is left to
+ * select.
+ *
+ * Only the TOP-LEVEL items move. An element the same run filed inside a group
+ * it also created is carried by that group, and moving it twice would tear the
+ * drawing apart. A group is moved through its children — `GfxGroupLikeElement`'s
+ * `xywh` setter is a deliberate no-op, its box being derived from what it holds
+ * — which is exactly what {@link updateXYWH} does, along with a connector's free
+ * endpoints (an anchored one simply follows what it is tied to) and a note's
+ * collapsed height. Hence no second opinion here.
+ */
+export function translateCreated(gfx, ids, dx, dy) {
+    const created = new Set(ids);
+    const models = ids
+        .map(id => gfx.getElementById(id))
+        .filter((model) => !!model && 'xywh' in model);
+    const top = models.filter(model => !model.group || !created.has(model.group.id));
+    if (dx !== 0 || dy !== 0) {
+        const updateElement = gfx.std.get(EdgelessCRUDIdentifier).updateElement;
+        // Wrapped, not handed over: `Store.updateBlock` is a prototype method that
+        // reads `this.readonly` and `this._crud`. `updateXYWH` happens to re-bind it
+        // (`updateBlock.call(ele.store, …)`), so today nothing breaks — but an
+        // unbound method sitting in a variable is a landmine that reads correct, and
+        // the day that `.call` becomes a plain call the first canvas block placed
+        // would throw on `readonly` of undefined.
+        const updateBlock = (model, props) => gfx.std.store.updateBlock(model, props);
+        for (const model of top) {
+            const bound = Bound.deserialize(model.xywh);
+            bound.x += dx;
+            bound.y += dy;
+            updateXYWH(model, bound, updateElement, updateBlock);
+        }
+    }
+    return top.map(model => model.id);
+}

package/dist/_pkgs/affine-widget-edgeless-toolbar/view.js

@@ -3,6 +3,7 @@ import { artefactCatalogueDefaultExtension } from './catalogue/artefact-catalogu
 import { edgelessArtefactCatalogueWidget } from './catalogue/artefact-catalogue-widget.js';
 import { edgelessToolbarWidget } from './edgeless-toolbar.js';
 import { effects } from './effects.js';
+import { ArtefactPlacementTool } from './placement/artefact-placement-tool.js';
 export class EdgelessToolbarViewExtension extends ViewExtensionProvider {
     constructor() {
         super(...arguments);
@@ -23,6 +24,10 @@ export class EdgelessToolbarViewExtension extends ViewExtensionProvider {
             // sidebar overrides the seam and the widget then never opens.
             context.register(edgelessArtefactCatalogueWidget);
             context.register(artefactCatalogueDefaultExtension);
+            // Unconditionally too, and for the same reason: the tool is generic
+            // chrome driven by whatever commands are registered, so a framework whose
+            // flag is off simply never arms it. See `docs/adr/0009`.
+            context.register(ArtefactPlacementTool);
         }
     }
 }