@formicoidea/labre-core 0.31.0 → 0.33.0

package/dist/_pkgs/affine-block-frame/frame-manager.js

@@ -1,4 +1,5 @@
 import { Overlay } from '../affine-block-surface/index.js';
+import { FrameworkBackgroundElementModel } from '../affine-model/index.js';
 import { EditPropsStore } from '../affine-shared/services/index.js';
 import { DisposableGroup } from '../global/disposable/index.js';
 import { BlockSuiteError, ErrorCode } from '../global/exceptions/index.js';
@@ -186,8 +187,12 @@ export class EdgelessFrameManager extends GfxExtension {
                         element.hasChild(frame)) {
                         return;
                     }
-                    // Only add elements that aren't already grouped and have a valid frame
-                    if (!element.group && frame) {
+                    // Only add elements that aren't already grouped and have a valid
+                    // frame, and never let the frame swallow a backdrop that encloses
+                    // it (e.g. a Wardley map background the frame was drawn on top of).
+                    if (!element.group &&
+                        frame &&
+                        !this._enclosesFrame(element, frame)) {
                         this._adoptNewlyCreatedElement(frame, element);
                     }
                 });
@@ -204,6 +209,12 @@ export class EdgelessFrameManager extends GfxExtension {
                     payload.model.containsBound(frame.elementBound)) {
                     return;
                 }
+                // A block that encloses the frame is a backdrop, not frame content —
+                // adopting it would bury the frame behind its own child (see
+                // `_enclosesFrame`).
+                if (this._enclosesFrame(payload.model, frame)) {
+                    return;
+                }
                 if (payload.isLocal) {
                     this._adoptNewlyCreatedElement(frame, payload.model);
                 }
@@ -216,6 +227,27 @@ export class EdgelessFrameManager extends GfxExtension {
             }
         }));
     }
+    /**
+     * Whether `element` fully encloses `frame`.
+     *
+     * A frame always renders behind everything it owns (`compare` short-circuits
+     * on the ancestor relationship, ignoring indexes) and "bring to front" only
+     * reorders top-level siblings — a grouped child is no longer one. So if a
+     * frame auto-adopted an element that encloses it (a Wardley map background
+     * the frame was drawn on top of, matched only because its center happened to
+     * fall inside the frame), the frame would be permanently buried behind its
+     * own child with no way to raise it. Such a backdrop must never become frame
+     * content. Mirrors the existing frame-inside-frame guard for canvas elements.
+     */
+    _enclosesFrame(element, frame) {
+        // A framework background is never frame content, whatever its geometry:
+        // the geometric test below has a hole (a frame TALLER than the map
+        // satisfies center-in-frame adoption without being fully enclosed), and
+        // since PF2 the model says outright what the geometry only hinted at.
+        if (element instanceof FrameworkBackgroundElementModel)
+            return true;
+        return element.elementBound.contains(frame.elementBound);
+    }
     /**
      * Adopt an element that was just created inside the frame's bounds.
      *

package/dist/_pkgs/affine-block-frame/frame-tool.js

@@ -1,4 +1,4 @@
-import { DefaultTool, OverlayIdentifier, } from '../affine-block-surface/index.js';
+import { DefaultTool, OverlayIdentifier } from '../affine-block-surface/index.js';
 import { EditPropsStore, TelemetryProvider, } from '../affine-shared/services/index.js';
 import { Bound, Vec } from '../global/gfx/index.js';
 import { BaseTool, getTopElements } from '../std/gfx/index.js';

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

@@ -36,7 +36,7 @@ import { focusBlockEnd, focusBlockStart, getNextBlockCommand, getPrevBlockComman
 import { ImageSelection } from '../../affine-shared/selection/index.js';
 import { unsafeCSSVarV2 } from '../../affine-shared/theme/index.js';
 import { SignalWatcher, WithDisposable } from '../../global/lit/index.js';
-import { BlockSelection, ShadowlessElement, TextSelection, } from '../../std/index.js';
+import { BlockSelection, ShadowlessElement, TextSelection } from '../../std/index.js';
 import { computed } from '@preact/signals-core';
 import { css, html } from 'lit';
 import { property, query } from 'lit/decorators.js';

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

@@ -35,7 +35,7 @@ var __runInitializers = (this && this.__runInitializers) || function (thisArg, i
 import { LoadingIcon } from '../affine-components/icons/index.js';
 import { Peekable } from '../affine-components/peek/index.js';
 import { ResourceController } from '../affine-components/resource/index.js';
-import { ImageBlockSchema, } from '../affine-model/index.js';
+import { ImageBlockSchema } from '../affine-model/index.js';
 import { cssVarV2, unsafeCSSVarV2 } from '../affine-shared/theme/index.js';
 import { formatSize } from '../affine-shared/utils/index.js';
 import { BrokenImageIcon, ImageIcon } from '@blocksuite/icons/lit';

package/dist/_pkgs/affine-block-latex/styles.js

@@ -8,7 +8,12 @@ export const latexBlockStyles = css `
     height: 100%;
     padding: 10px 24px;
     flex-direction: column;
-    align-items: center;
+    /**
+     * The rendered formula must span the container so a wide equation can be
+     * scrolled through (overflow-x below); centring shrank it to its content
+     * and pushed the overflow out of reach.
+     */
+    align-items: stretch;
     justify-content: center;
     border-radius: 4px;
     overflow-x: auto;

package/dist/_pkgs/affine-block-list/utils/forward-delete.js

@@ -1,5 +1,5 @@
 import { ListBlockModel } from '../../affine-model/index.js';
-import { getNextContentBlock, matchModels, } from '../../affine-shared/utils/index.js';
+import { getNextContentBlock, matchModels } from '../../affine-shared/utils/index.js';
 import { TextSelection } from '../../std/index.js';
 // When deleting at line end of a list block,
 // check current block's children and siblings

package/dist/_pkgs/affine-block-note/commands/select-block.js

@@ -1,4 +1,4 @@
-import { BlockSelection, } from '../../std/index.js';
+import { BlockSelection } from '../../std/index.js';
 export const selectBlock = (ctx, next) => {
     const { focusBlock, std } = ctx;
     if (!focusBlock) {

package/dist/_pkgs/affine-block-note/commands/select-blocks-between.js

@@ -1,4 +1,4 @@
-import { BlockSelection, } from '../../std/index.js';
+import { BlockSelection } from '../../std/index.js';
 export const selectBlocksBetween = (ctx, next) => {
     const { focusBlock, anchorBlock, tail } = ctx;
     if (!focusBlock || !anchorBlock) {

package/dist/_pkgs/affine-block-note/move-block.js

@@ -1,4 +1,4 @@
-import { BlockSelection, TextSelection, } from '../std/index.js';
+import { BlockSelection, TextSelection } from '../std/index.js';
 const getSelection = (std) => std.selection;
 function getBlockSelectionBySide(std, tail) {
     const selection = getSelection(std);

package/dist/_pkgs/affine-block-note/note-edgeless-block.d.ts

@@ -30,6 +30,15 @@ export declare class EdgelessNoteBlockComponent extends EdgelessNoteBlockCompone
     };
     firstUpdated(): void;
     updated(changedProperties: PropertyValues): void;
+    /**
+     * A note carries its own `scale` on top of the viewport zoom. That scale
+     * belongs to the host element's transform, not to an inner wrapper: the
+     * element is laid out from the *unscaled* bound (see `getRenderingRect`), so
+     * scaling only the content would leave the element's box — the thing hit
+     * tests, the selection rect and the toolbar anchor read — out of step with
+     * what is painted at any scale other than 100%.
+     */
+    getCSSTransform(): string;
     getRenderingRect(): {
         x: number;
         y: number;

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

@@ -246,6 +246,18 @@ let EdgelessNoteBlockComponent = (() => {
                 });
             }
         }
+        /**
+         * A note carries its own `scale` on top of the viewport zoom. That scale
+         * belongs to the host element's transform, not to an inner wrapper: the
+         * element is laid out from the *unscaled* bound (see `getRenderingRect`), so
+         * scaling only the content would leave the element's box — the thing hit
+         * tests, the selection rect and the toolbar anchor read — out of step with
+         * what is painted at any scale other than 100%.
+         */
+        getCSSTransform() {
+            const extraScale = this.model.props.edgeless?.scale ?? 1;
+            return `${super.getCSSTransform()} scale(${extraScale})`;
+        }
         getRenderingRect() {
             const { xywh, edgeless } = this.model.props;
             const { collapse, scale = 1 } = edgeless;
@@ -273,7 +285,6 @@ let EdgelessNoteBlockComponent = (() => {
             const height = bound.h / scale;
             const style = {
                 borderRadius: borderRadius + 'px',
-                transform: `scale(${scale})`,
             };
             const extra = this._editing ? ACTIVE_NOTE_EXTRA_PADDING : 0;
             const isCollapsable = collapse != null &&
@@ -458,6 +469,17 @@ export const EdgelessNoteInteraction = GfxViewInteractionExtension(NoteBlockSche
                         if (!view.isConnected) {
                             return;
                         }
+                        // A click landing on the note title belongs to the title:
+                        // routing it through the children container below would
+                        // clamp it into the first paragraph instead.
+                        const titleRect = view
+                            .querySelector('edgeless-page-block-title')
+                            ?.getBoundingClientRect();
+                        if (titleRect &&
+                            new Bound(titleRect.x, titleRect.y, titleRect.width, titleRect.height).isPointInBound([e.clientX, e.clientY])) {
+                            handleNativeRangeAtPoint(e.clientX, e.clientY);
+                            return;
+                        }
                         if (model.children.length === 0) {
                             const blockId = std.store.addBlock('affine:paragraph', { type: 'text' }, model.id);
                             if (blockId) {
@@ -482,6 +504,12 @@ export const EdgelessNoteInteraction = GfxViewInteractionExtension(NoteBlockSche
                     })
                         .catch(console.error);
                 }
+                else if (multiSelect && alreadySelected && editing) {
+                    // Shift-clicking inside a note being edited extends the text
+                    // range; the default multi-select would drop the editing state
+                    // and take the range with it.
+                    return;
+                }
                 else {
                     context.default(context);
                 }

package/dist/_pkgs/affine-block-paragraph/utils/forward-delete.js

@@ -1,7 +1,7 @@
 import { AttachmentBlockModel, BookmarkBlockModel, CalloutBlockModel, CodeBlockModel, DatabaseBlockModel, DividerBlockModel, ImageBlockModel, ListBlockModel, ParagraphBlockModel, } from '../../affine-model/index.js';
 import { EMBED_BLOCK_MODEL_LIST } from '../../affine-shared/consts/index.js';
-import { getNextContentBlock, matchModels, } from '../../affine-shared/utils/index.js';
-import { BlockSelection, TextSelection, } from '../../std/index.js';
+import { getNextContentBlock, matchModels } from '../../affine-shared/utils/index.js';
+import { BlockSelection, TextSelection } from '../../std/index.js';
 export function forwardDelete(std) {
     const { store, host } = std;
     const text = std.selection.find(TextSelection);

package/dist/_pkgs/affine-block-paragraph/utils/merge-with-prev.js

@@ -1,5 +1,5 @@
 import { AttachmentBlockModel, BookmarkBlockModel, CalloutBlockModel, CodeBlockModel, DatabaseBlockModel, DividerBlockModel, EdgelessTextBlockModel, ImageBlockModel, ListBlockModel, NoteBlockModel, ParagraphBlockModel, } from '../../affine-model/index.js';
-import { asyncSetInlineRange, focusTextModel, } from '../../affine-rich-text/index.js';
+import { asyncSetInlineRange, focusTextModel } from '../../affine-rich-text/index.js';
 import { EMBED_BLOCK_MODEL_LIST } from '../../affine-shared/consts/index.js';
 import { focusTitle, getDocTitleInlineEditor, getPrevContentBlock, matchModels, } from '../../affine-shared/utils/index.js';
 import { BlockSelection } from '../../std/index.js';

package/dist/_pkgs/affine-block-root/commands/pivot-commands.d.ts

@@ -0,0 +1,37 @@
+import { type AnyCommandDescriptor } from '../../std/index.js';
+import { z } from 'zod';
+/**
+ * `pivotDocId: null` unbinds. The key is REQUIRED on purpose: an optional one
+ * would make a forgotten argument silently destroy a binding, which is exactly
+ * the failure mode an agent-invocable command must not have.
+ */
+export declare const bindPivotParams: z.ZodObject<{
+    pivotDocId: z.ZodNullable<z.ZodString>;
+    /**
+     * Explicit targets, for a host or an agent acting on something other than the
+     * live selection. **Omitted** — the key absent — the command acts on the
+     * current canvas selection.
+     *
+     * An EMPTY array is not the same thing: it means "these zero elements", so
+     * the command does nothing and does not fall back to the selection. That is
+     * the safe reading — an agent that computed a target list and came up empty
+     * must not have the gesture redirected onto whatever the user happened to
+     * have selected — but it is silent, so callers filtering a list should check
+     * it before invoking.
+     */
+    elementIds: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+}, "strip", z.ZodTypeAny, {
+    pivotDocId: string | null;
+    elementIds?: string[] | undefined;
+}, {
+    pivotDocId: string | null;
+    elementIds?: string[] | undefined;
+}>;
+export type BindPivotParams = z.infer<typeof bindPivotParams>;
+/**
+ * The registry's element type erases the parameter contract
+ * ({@link AnyCommandDescriptor}) — this is the first command to have one, and
+ * `run` re-validates with {@link bindPivotParams} rather than trusting the
+ * static type, which is what an agent-invocable command has to do anyway.
+ */
+export declare const pivotCommands: AnyCommandDescriptor[];

package/dist/_pkgs/affine-block-root/commands/pivot-commands.js

@@ -0,0 +1,168 @@
+/**
+ * The promotion rung "role → component": bind a surface element to a host-owned
+ * **pivot record** (MF1, ADR 0005 § 3, ladder in ADR 0007 § 6).
+ *
+ * The library cannot choose a document — it does not know what a pivot record
+ * is. So the record id is a PARAMETER: the host's picker (labreapp, MF2) runs
+ * the selection UI and invokes the command with the answer. That is also what
+ * makes the command usable by the agent surface with no UI at all.
+ */
+import { TelemetryProvider } from '../../affine-shared/services/index.js';
+import { FRAMEWORK_IDS, } from '../../std/index.js';
+import { GfxControllerIdentifier, GfxPrimitiveElementModel, } from '../../std/gfx/index.js';
+import { z } from 'zod';
+const PIVOT_DOC_ID = 'pivotDocId';
+/**
+ * `pivotDocId: null` unbinds. The key is REQUIRED on purpose: an optional one
+ * would make a forgotten argument silently destroy a binding, which is exactly
+ * the failure mode an agent-invocable command must not have.
+ */
+export const bindPivotParams = z.object({
+    pivotDocId: z.string().min(1).nullable(),
+    /**
+     * Explicit targets, for a host or an agent acting on something other than the
+     * live selection. **Omitted** — the key absent — the command acts on the
+     * current canvas selection.
+     *
+     * An EMPTY array is not the same thing: it means "these zero elements", so
+     * the command does nothing and does not fall back to the selection. That is
+     * the safe reading — an agent that computed a target list and came up empty
+     * must not have the gesture redirected onto whatever the user happened to
+     * have selected — but it is silent, so callers filtering a list should check
+     * it before invoking.
+     */
+    elementIds: z.array(z.string()).optional(),
+});
+/**
+ * The elements this gesture would write to. Surface elements only: canvas
+ * BLOCKS carry a versioned schema, so binding them would be a `version` bump in
+ * `packages/affine/model` and is out of scope (ADR 0005 § 6).
+ */
+function pivotTargets(std, elementIds) {
+    const gfx = std.get(GfxControllerIdentifier);
+    const models = elementIds
+        ? elementIds.map(id => gfx.surface?.getElementById(id))
+        : gfx.selection.selectedElements;
+    return models.filter((model) => model instanceof GfxPrimitiveElementModel);
+}
+/**
+ * Whether this document may be written to at all.
+ *
+ * Checked in `run` and not only in `when`, because `when` is consulted by the
+ * SURFACES and `runCommand` consults neither it nor `availability` — the
+ * palette and the agent reach `run` directly. Without this guard, unbinding
+ * succeeds in a read-only document: `clearField` goes through `Store.transact`,
+ * which (unlike `addBlock` / `updateBlock` / `deleteBlock`) carries no
+ * read-only guard, so the key is deleted and the promotion event is emitted for
+ * a document the user cannot edit. Binding merely throws out of `runCommand`,
+ * which is bad in a different way.
+ */
+const isBindable = (std) => !std.store.readonly;
+/** `'wardley:component'` → `'wardley'`, when that names a real framework. */
+function frameworkOfRole(role) {
+    const namespace = role?.split(':')[0];
+    return FRAMEWORK_IDS.includes(namespace ?? '')
+        ? namespace
+        : undefined;
+}
+/** The single value shared by every target, or `undefined` if they disagree. */
+function unanimous(values) {
+    const distinct = new Set(values);
+    return distinct.size === 1 ? values[0] : undefined;
+}
+const bindPivot = {
+    id: 'pivot.bind',
+    owner: 'core',
+    kind: 'action',
+    // NOT `com.labre.keyboardShortcuts.*` like every labelKey before it: those
+    // all belong to commands that ship a default chord. This one is keyless by
+    // intent and lives in the palette and the agent, so filing it under
+    // "keyboard shortcuts" would mislead a translator.
+    labelKey: 'com.labre.command.pivot.bind',
+    labelFallback: 'Link to record',
+    descriptionKey: 'com.labre.command.pivot.bind.description',
+    surfaces: ['palette', 'agent'],
+    scope: 'edgeless',
+    // Keyless by intent — still bindable from Settings › Shortcuts, which is
+    // what `toShortcutDescriptor` being total buys.
+    defaultKeys: { mac: [], other: [] },
+    availability: 'selection',
+    // Narrows `'selection'`, never contradicts it: a read-only document, and a
+    // selection of nothing but canvas blocks, both have no bindable target.
+    //
+    // Read-only rides on `when` rather than on `availability` because the union
+    // does not COMPOSE: it is one value per command (`command-registry.ts`
+    // `isCommandAvailable`), so declaring `'editable'` would buy the read-only
+    // gate by dropping the selection gate a host panel needs far more often.
+    // `'selection'` stays the serializable answer — it is the precondition a
+    // catalogue must show — and the state precondition is enforced below.
+    // The missing composition is recorded as an amendment trigger in ADR 0008.
+    when: std => isBindable(std) && pivotTargets(std).length > 0,
+    params: bindPivotParams,
+    run: (std, invocation, params) => {
+        const parsed = bindPivotParams.safeParse(params);
+        if (!parsed.success) {
+            console.error('pivot.bind: invalid params', parsed.error.issues);
+            return;
+        }
+        const { pivotDocId, elementIds } = parsed.data;
+        // The load-bearing half of the read-only gate: see `isBindable`.
+        if (!isBindable(std))
+            return;
+        const targets = pivotTargets(std, elementIds);
+        if (!targets.length)
+            return;
+        // A gesture that changes nothing emits nothing and costs no undo step.
+        const changing = targets.filter(el => el.pivotDocId !== (pivotDocId ?? undefined));
+        if (!changing.length)
+            return;
+        // BEFORE the write, not after. `store.transact()` is not an undo
+        // boundary: the `Y.UndoManager` is built with no `captureTimeout`, so
+        // Yjs's 500 ms default merges consecutive transactions — and a bind
+        // issued within 500 ms of a drag would be undone TOGETHER with the drag,
+        // making the promotion look like it moved geometry. `stopCapturing()`
+        // opens a new stack item for what comes NEXT, so it has to precede the
+        // write (`Store.captureSync` docstring; same order as `applyLastStyle`).
+        //
+        // The ADRs' snippets (0005 § 3, 0007 § 6) show it after the write; that
+        // contradicts their own stated rationale and is treated as an editorial
+        // slip — see the PR description.
+        std.store.captureSync();
+        for (const element of changing) {
+            if (pivotDocId === null) {
+                // Not `updateElement(id, { pivotDocId: undefined })`: the `@field()`
+                // setter is unconditional, so that would leave the key behind as a
+                // tombstone. `clearField` removes it, and accepts this field because
+                // it is a declared, non-structural `@field()`.
+                element.clearField(PIVOT_DOC_ID);
+            }
+            else {
+                element.surface.updateElement(element.id, { pivotDocId });
+            }
+        }
+        // The ONE emission for this gesture. Not routed through `runCommand`'s
+        // bottleneck: that emitter maps `CommandKind` onto the three creation
+        // events from a STATIC `{ framework, element }` on the descriptor, and a
+        // promotion is neither a creation nor static — `rung`, `direction` and
+        // `role` are facts of the invocation. See ADR 0007 § 7.
+        const roles = changing.map(el => el.role);
+        const role = unanimous(roles);
+        std.getOptional(TelemetryProvider)?.track('FrameworkElementPromoted', {
+            page: 'whiteboard editor',
+            framework: frameworkOfRole(role),
+            rung: 'pivot',
+            direction: pivotDocId === null ? 'demote' : 'promote',
+            role,
+            elementCount: changing.length,
+            control: invocation.source,
+            module: invocation.surface,
+        });
+    },
+};
+/**
+ * The registry's element type erases the parameter contract
+ * ({@link AnyCommandDescriptor}) — this is the first command to have one, and
+ * `run` re-validates with {@link bindPivotParams} rather than trusting the
+ * static type, which is what an agent-invocable command has to do anyway.
+ */
+export const pivotCommands = [bindPivot];

package/dist/_pkgs/affine-block-root/commands/reading-commands.d.ts

@@ -0,0 +1,23 @@
+import { type AnyCommandDescriptor } from '../../std/index.js';
+import { z } from 'zod';
+/**
+ * `elementId` omitted, the command reads the current canvas selection. Passing
+ * it explicitly is what lets the element's own toolbar name the element that
+ * CARRIES the role rather than the group the user clicked (the same reason
+ * `tags-toolbar.ts` passes `elementIds` to `tag.set`), and what makes the
+ * command usable by the agent with no selection at all.
+ */
+export declare const readElementParams: z.ZodObject<{
+    elementId: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    elementId?: string | undefined;
+}, {
+    elementId?: string | undefined;
+}>;
+export type ReadElementParams = z.infer<typeof readElementParams>;
+/**
+ * The registry's element type erases the parameter contract; `run` re-validates
+ * with {@link readElementParams} rather than trusting the static type, which is
+ * what an agent-invocable command has to do anyway.
+ */
+export declare const readingCommands: AnyCommandDescriptor[];

package/dist/_pkgs/affine-block-root/commands/reading-commands.js

@@ -0,0 +1,107 @@
+/**
+ * `element.read` — the CLICK that asks the tool what it reads of a component
+ * (MF3, "reversed reading").
+ *
+ * The PO's arbitration of 01/08/2026, verbatim: the reversed reading is
+ * triggered **on a click, never by automatic validation**, and **writes nothing
+ * without confirmation**. This command is the click. It opens a proposal and
+ * that is the whole of its effect — no tag, no binding, no property, nothing
+ * touched in the document, on any path, ever.
+ *
+ * Which is also why it is NOT read-only gated: reading a board one cannot edit
+ * is exactly as legitimate as reading one you can. The gate lives on the
+ * CONFIRMATIONS, which are `tag.set` and `pivot.bind` — two commands that
+ * already refuse a read-only store.
+ */
+import { ReadingManager } from '../../affine-block-surface/index.js';
+import {} from '../../std/index.js';
+import { GfxControllerIdentifier, GfxPrimitiveElementModel, } from '../../std/gfx/index.js';
+import { z } from 'zod';
+/**
+ * `elementId` omitted, the command reads the current canvas selection. Passing
+ * it explicitly is what lets the element's own toolbar name the element that
+ * CARRIES the role rather than the group the user clicked (the same reason
+ * `tags-toolbar.ts` passes `elementIds` to `tag.set`), and what makes the
+ * command usable by the agent with no selection at all.
+ */
+export const readElementParams = z.object({
+    elementId: z.string().min(1).optional(),
+});
+/**
+ * The element this reading is about: the one named, or the single selected
+ * surface element.
+ *
+ * ONE element, never a multi-selection: a proposal is one fiche about one
+ * thing, and two components have two readings that no single panel could
+ * honestly show at once.
+ */
+function readTarget(std, elementId) {
+    const gfx = std.get(GfxControllerIdentifier);
+    if (elementId) {
+        const model = gfx.surface?.getElementById(elementId);
+        return model instanceof GfxPrimitiveElementModel ? model : null;
+    }
+    const selected = gfx.selection.selectedElements.filter((model) => model instanceof GfxPrimitiveElementModel);
+    return selected.length === 1 ? selected[0] : null;
+}
+/**
+ * Whether anything registered can read this element.
+ *
+ * Asked through the manager rather than re-implemented here: the profiles are
+ * registered by a framework's FLAG-GATED view extension, so a board whose
+ * framework is off has no reading and the command stands down — in the palette,
+ * on the toolbar and for the agent alike, from one answer.
+ */
+function readable(std, elementId) {
+    const manager = std.getOptional(ReadingManager);
+    if (!manager)
+        return false;
+    const target = readTarget(std, elementId);
+    return target !== null && manager.profileOf(target.id) !== null;
+}
+const readElementCommand = {
+    id: 'element.read',
+    owner: 'core',
+    kind: 'action',
+    // Not under `com.labre.keyboardShortcuts.*`: keyless by intent, like
+    // `pivot.bind` and `tag.set`, and filing it there would mislead a translator.
+    labelKey: 'com.labre.command.element.read',
+    labelFallback: 'Read this component',
+    descriptionKey: 'com.labre.command.element.read.description',
+    // The three surfaces the reading is reachable from. `'contextual-toolbar'`
+    // is where it is actually used — one click on the component — and declaring
+    // it is what keeps the telemetry honest about where a gesture came from
+    // (ADR 0008: the invocation names the surface, and the surface must exist).
+    surfaces: ['palette', 'contextual-toolbar', 'agent'],
+    scope: 'edgeless',
+    defaultKeys: { mac: [], other: [] },
+    availability: 'selection',
+    // Narrows `'selection'`, never contradicts it. Note what is NOT here: a
+    // read-only guard. Reading writes nothing, so there is nothing to refuse.
+    when: std => readable(std),
+    params: readElementParams,
+    run: (std, _invocation, params) => {
+        const parsed = readElementParams.safeParse(params);
+        if (!parsed.success) {
+            console.error('element.read: invalid params', parsed.error.issues);
+            return;
+        }
+        const manager = std.getOptional(ReadingManager);
+        if (!manager)
+            return;
+        const target = readTarget(std, parsed.data.elementId);
+        if (!target)
+            return;
+        // A neutral element, or one whose framework is flagged off, has no reading
+        // and must not open an empty panel.
+        if (!manager.profileOf(target.id))
+            return;
+        manager.open(target.id);
+    },
+};
+/**
+ * The registry's element type erases the parameter contract; `run` re-validates
+ * with {@link readElementParams} rather than trusting the static type, which is
+ * what an agent-invocable command has to do anyway.
+ */
+export const readingCommands = [readElementCommand];

package/dist/_pkgs/affine-block-root/commands/tag-commands.d.ts

@@ -0,0 +1,47 @@
+import { type AnyCommandDescriptor } from '../../std/index.js';
+import { z } from 'zod';
+/**
+ * `values: []` removes the tag. Both keys are REQUIRED on purpose: an optional
+ * `values` would make a forgotten argument silently destroy a qualification,
+ * which is exactly the failure mode an agent-invocable command must not have.
+ */
+export declare const setTagParams: z.ZodObject<{
+    /** Namespaced tag def id, e.g. `'wardley:nature'`. */
+    tag: z.ZodString;
+    /**
+     * The value ids selected for that tag, e.g. `['wardley:nature/data']`.
+     * `[]` clears it.
+     *
+     * NOT validated against the registered defs. A document may legitimately
+     * carry an id whose def was removed, renamed or never seeded in this
+     * deployment, and the persisted value must accept any string — narrowing it
+     * here would push that case toward a load-time failure. The picker offers
+     * only defined values; the command does not police them.
+     */
+    values: z.ZodArray<z.ZodString, "many">;
+    /**
+     * Explicit targets, for a host or an agent acting on something other than the
+     * live selection. **Omitted** — the key absent — the command acts on the
+     * current canvas selection.
+     *
+     * An EMPTY array is not the same thing: it means "these zero elements", so
+     * the command does nothing and does not fall back to the selection.
+     */
+    elementIds: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+}, "strip", z.ZodTypeAny, {
+    values: string[];
+    tag: string;
+    elementIds?: string[] | undefined;
+}, {
+    values: string[];
+    tag: string;
+    elementIds?: string[] | undefined;
+}>;
+export type SetTagParams = z.infer<typeof setTagParams>;
+/**
+ * The registry's element type erases the parameter contract
+ * ({@link AnyCommandDescriptor}); `run` re-validates with {@link setTagParams}
+ * rather than trusting the static type, which is what an agent-invocable
+ * command has to do anyway.
+ */
+export declare const tagCommands: AnyCommandDescriptor[];