@formicoidea/labre-core 0.41.0 → 0.43.1

package/dist/_pkgs/affine-widget-edgeless-toolbar/panel/font-family-panel.js

@@ -34,15 +34,20 @@ var __runInitializers = (this && this.__runInitializers) || function (thisArg, i
 };
 import { TextUtils } from '../../affine-block-surface/index.js';
 import { FontFamily, FontFamilyList } from '../../affine-model/index.js';
+import { fillPlaceholders, FontConfigIdentifier, 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 { repeat } from 'lit/directives/repeat.js';
+import { EDGELESS_TOOLBAR_FONT_FAMILY_UNAVAILABLE } from '../translations.js';
 let EdgelessFontFamilyPanel = (() => {
     let _classSuper = LitElement;
     let _onSelect_decorators;
     let _onSelect_initializers = [];
     let _onSelect_extraInitializers = [];
+    let _std_decorators;
+    let _std_initializers = [];
+    let _std_extraInitializers = [];
     let _value_decorators;
     let _value_initializers = [];
     let _value_extraInitializers = [];
@@ -50,8 +55,10 @@ let EdgelessFontFamilyPanel = (() => {
         static {
             const _metadata = typeof Symbol === "function" && Symbol.metadata ? Object.create(_classSuper[Symbol.metadata] ?? null) : void 0;
             _onSelect_decorators = [property({ attribute: false })];
+            _std_decorators = [property({ attribute: false })];
             _value_decorators = [property({ attribute: false })];
             __esDecorate(this, null, _onSelect_decorators, { kind: "accessor", name: "onSelect", static: false, private: false, access: { has: obj => "onSelect" in obj, get: obj => obj.onSelect, set: (obj, value) => { obj.onSelect = value; } }, metadata: _metadata }, _onSelect_initializers, _onSelect_extraInitializers);
+            __esDecorate(this, null, _std_decorators, { kind: "accessor", name: "std", static: false, private: false, access: { has: obj => "std" in obj, get: obj => obj.std, set: (obj, value) => { obj.std = value; } }, metadata: _metadata }, _std_initializers, _std_extraInitializers);
             __esDecorate(this, null, _value_decorators, { kind: "accessor", name: "value", static: false, private: false, access: { has: obj => "value" in obj, get: obj => obj.value, set: (obj, value) => { obj.value = value; } }, metadata: _metadata }, _value_initializers, _value_extraInitializers);
             if (_metadata) Object.defineProperty(this, Symbol.metadata, { enumerable: true, configurable: true, writable: true, value: _metadata });
         }
@@ -67,26 +74,59 @@ let EdgelessFontFamilyPanel = (() => {
       width: 100%;
     }
   `; }
+        /**
+         * The families the host configured: those with at least one face in its
+         * `FontConfig` (#396). Read from the config itself rather than from
+         * `document.fonts`, which the font loader fills a few seconds late for every
+         * non-critical family.
+         *
+         * `null` when no config is registered (the seam is absent, or empty, which
+         * the font loader also treats as absent): every family is offered, as before
+         * the seam narrowed the list. None of them has a file then, so each paints
+         * with the same fallback anyway.
+         */
+        _configuredFamilies() {
+            const config = this.std?.getOptional(FontConfigIdentifier);
+            if (!config || config.length === 0)
+                return null;
+            return new Set(config.map(face => face.font));
+        }
         _onSelect(value) {
             this.value = value;
             if (this.onSelect) {
                 this.onSelect(value);
             }
         }
+        _unavailableLabel(name) {
+            return this.std
+                ? translateKey(this.std, ...EDGELESS_TOOLBAR_FONT_FAMILY_UNAVAILABLE, {
+                    name,
+                })
+                : fillPlaceholders(EDGELESS_TOOLBAR_FONT_FAMILY_UNAVAILABLE[1], { name });
+        }
         render() {
-            return repeat(FontFamilyList, item => item[0], ([font, name]) => {
-                const active = this.value === font;
+            const configured = this._configuredFamilies();
+            // The current family stays listed even when the host no longer ships it:
+            // the element keeps it (and paints the fallback), so the picker names it
+            // rather than pretend the text has none. Greyed and never picked from
+            // here, so nothing rewrites the stored value behind the user's back.
+            const families = FontFamilyList.filter(([font]) => !configured || configured.has(font) || font === this.value);
+            return repeat(families, item => item[0], ([font, name]) => {
+                const unavailable = !!configured && !configured.has(font);
+                const current = this.value === font;
                 return html `
           <edgeless-tool-icon-button
             data-font="${name}"
             style="font-family: ${TextUtils.wrapFontFamily(font)}"
             .iconContainerPadding=${[4, 8]}
             .justify=${'space-between'}
-            .active=${active}
+            .active=${current && !unavailable}
+            .disabled=${unavailable}
             .iconSize=${'20px'}
-            @click=${() => this._onSelect(font)}
+            @click=${unavailable ? nothing : () => this._onSelect(font)}
           >
-            ${name} ${active ? DoneIcon() : nothing}
+            ${unavailable ? this._unavailableLabel(name) : name}
+            ${current ? DoneIcon() : nothing}
           </edgeless-tool-icon-button>
         `;
             });
@@ -94,7 +134,13 @@ let EdgelessFontFamilyPanel = (() => {
         #onSelect_accessor_storage = __runInitializers(this, _onSelect_initializers, undefined);
         get onSelect() { return this.#onSelect_accessor_storage; }
         set onSelect(value) { this.#onSelect_accessor_storage = value; }
-        #value_accessor_storage = (__runInitializers(this, _onSelect_extraInitializers), __runInitializers(this, _value_initializers, FontFamily.Inter));
+        #std_accessor_storage = (__runInitializers(this, _onSelect_extraInitializers), __runInitializers(this, _std_initializers, undefined));
+        /** Set by the caller that has one (`gfx/text`'s `createTextActions`): it
+         * carries the host's `FontConfig` and translations. Optional, so the panel
+         * still renders (every family, in English) when created with none. */
+        get std() { return this.#std_accessor_storage; }
+        set std(value) { this.#std_accessor_storage = value; }
+        #value_accessor_storage = (__runInitializers(this, _std_extraInitializers), __runInitializers(this, _value_initializers, FontFamily.Inter));
         get value() { return this.#value_accessor_storage; }
         set value(value) { this.#value_accessor_storage = value; }
         constructor() {

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';