@formicoidea/labre-core 0.41.0 → 0.43.1

package/dist/_pkgs/affine-block-surface/extensions/index.d.ts

@@ -6,9 +6,12 @@ export * from './edit-props-middleware-builder.js';
 export * from './editor-anchored-panel.js';
 export * from './element-renderer.js';
 export * from './export-manager/index.js';
+export * from './export-svg/index.js';
 export * from './interchange.js';
 export * from './interchange-import.js';
 export * from './legacy-slot-extension.js';
+export * from './legend.js';
+export * from './legend-toolbar.js';
 export * from './map-quality.js';
 export * from './map-quality-widget.js';
 export * from './morph-toolbar.js';
@@ -16,6 +19,7 @@ export * from './query.js';
 export * from './reading.js';
 export * from './reading-toolbar.js';
 export * from './reading-widget.js';
+export * from './record-action.js';
 export * from './spotlight.js';
 export * from './surface-middleware.js';
 export * from './svg-sketch.js';

package/dist/_pkgs/affine-block-surface/extensions/index.js

@@ -6,9 +6,12 @@ export * from './edit-props-middleware-builder.js';
 export * from './editor-anchored-panel.js';
 export * from './element-renderer.js';
 export * from './export-manager/index.js';
+export * from './export-svg/index.js';
 export * from './interchange.js';
 export * from './interchange-import.js';
 export * from './legacy-slot-extension.js';
+export * from './legend.js';
+export * from './legend-toolbar.js';
 export * from './map-quality.js';
 export * from './map-quality-widget.js';
 export * from './morph-toolbar.js';
@@ -16,6 +19,7 @@ export * from './query.js';
 export * from './reading.js';
 export * from './reading-toolbar.js';
 export * from './reading-widget.js';
+export * from './record-action.js';
 export * from './spotlight.js';
 export * from './surface-middleware.js';
 export * from './svg-sketch.js';

package/dist/_pkgs/affine-block-surface/extensions/interchange-import.d.ts

@@ -1,6 +1,6 @@
 import type { ServiceProvider } from '../../global/di/index.js';
 import type { BlockStdScope } from '../../std/index.js';
-import { type InterchangeFormat, type InterchangeImportCapability, type InterchangeReport, type SerializedElementProps } from './interchange.js';
+import { type InterchangeFormat, type InterchangeImportCapability, type InterchangeNote, type InterchangeReport, type SerializedElementProps } from './interchange.js';
 /**
  * **The public import API** — what an editor, a host application or a plugin
  * calls to turn a foreign file into a board (`docs/adr/0012`).
@@ -50,11 +50,49 @@ import { type InterchangeFormat, type InterchangeImportCapability, type Intercha
  * whole blob and `addElement` writes it with everything else, which is the
  * whole-record LWW the field's own contract asks for (D2).
  *
+ * ## The reader's OWN names, and why there is a second map
+ *
+ * A source id is the file's, and there are two things a reader has to point at
+ * that the file never named: an element it MINTED (a framework artefact is
+ * routinely several elements — a shape, its compartments, and the group that
+ * makes them one thing), and the group membership between them. So a reader may
+ * also hand each element a provisional `id` of its own. `surface.addElement`
+ * overwrites it with a nanoid and is documented to, which is precisely what
+ * makes it safe to use as a local name: it reaches no document, and it is read
+ * here and nowhere else.
+ *
+ * A GROUP's `children` are therefore rewritten BEFORE the group is created, out
+ * of the map built so far — which costs nothing and asks the reader for the one
+ * thing it can always give: emit an element before the group that holds it. A
+ * connector is the opposite case (a flow may be written before either of its
+ * ends) and keeps its second pass.
+ *
+ * Source ids win over provisional ones wherever both could answer, so a reader
+ * that mints no local name behaves exactly as it did before this was here.
+ *
+ * ## Beside what is already drawn
+ *
+ * A reader writes the coordinates its FILE gave it, so importing the same file
+ * twice put the second board exactly on top of the first. The offset is applied
+ * here, once, for every framework, because the only thing that knows what the
+ * canvas already holds is the function doing the writing — see
+ * {@link importOffset}, and note that an empty surface is left alone.
+ *
+ * ## A read-only document is answered, not thrown at
+ *
+ * This is a public API — a host (labre-mcp) writes through it with no command
+ * in front of it — so the guard belongs here too and not only at the callers:
+ * a readonly document answers the empty array, which is the same "nothing was
+ * minted" every other refusal of this function returns, rather than an
+ * exception a caller would have to know to catch.
+ *
  * @param formatId the format whose payload key carries the source ids — the
  *   `id` of the capability's {@link InterchangeFormat}, and the ONLY thing this
  *   function ever knew about BPMN.
  */
-export declare function materializeInterchangeImport(std: BlockStdScope, formatId: string, elements: readonly SerializedElementProps[]): string[];
+export declare function materializeInterchangeImport(std: BlockStdScope, formatId: string, elements: readonly SerializedElementProps[], options?: {
+    onNote?: (note: InterchangeNote) => void;
+}): string[];
 /**
  * Say what the import did — the summary, and the remarks.
  *
@@ -109,7 +147,31 @@ export declare function reportInterchangeImport(std: BlockStdScope, format: Inte
  * deliberately so: a dialog a document cannot honour should never open in the
  * first place.
  */
-export declare function runInterchangeImportFile(std: BlockStdScope, capability: InterchangeImportCapability): Promise<void>;
+export declare function runInterchangeImportFile(std: BlockStdScope, capability: InterchangeImportCapability, options?: InterchangeImportOptions): Promise<void>;
+/** What a caller can put between the file's bytes and the declared reader. */
+export interface InterchangeImportOptions {
+    /**
+     * Turn the file's text into the text the reader takes — the seam for a
+     * format whose container is not the document.
+     *
+     * A reader is a PURE, synchronous function of text (`docs/adr/0012` P3), and
+     * that is not negotiable: it is what lets labre-mcp call the same function
+     * the command calls. Some containers put an asynchronous platform API between
+     * the bytes and the document all the same — a `.drawio` file holds its
+     * `<mxGraphModel>` as base64 of a raw deflate, and inflating it needs
+     * `DecompressionStream` (`gfx/uml/src/drawio-decode.ts`, `docs/adr/0019`);
+     * a zipped container would be the next one.
+     *
+     * So the unwrapping happens HERE, where a caller already has an editor and an
+     * `await`, and the reader keeps its purity. Anything this throws is shown as
+     * the import's failure notification, exactly as a reader's own refusal is —
+     * so the sentence it throws should name what is wrong with the file.
+     *
+     * Absent for every format whose file IS its document, which is all of them
+     * bar one.
+     */
+    decode?: (text: string, file: File) => string | Promise<string>;
+}
 /**
  * The import itself, over a file the caller ALREADY HAS: run the declared
  * capability (`docs/adr/0012`), write what it returned, bring it into view, and
@@ -147,7 +209,7 @@ export declare function runInterchangeImportFile(std: BlockStdScope, capability:
  * its refusals it was, so it is shown as it is rather than replaced with a
  * wording of our own that knows less.
  */
-export declare function importInterchangeFile(std: BlockStdScope, capability: InterchangeImportCapability, file: File): Promise<void>;
+export declare function importInterchangeFile(std: BlockStdScope, capability: InterchangeImportCapability, file: File, options?: InterchangeImportOptions): Promise<void>;
 /**
  * Every registered importer, indexed by the extensions it declares.
  *

package/dist/_pkgs/affine-block-surface/extensions/interchange-import.js

@@ -1,7 +1,7 @@
 import { ConnectorElementModel } from '../../affine-model/index.js';
-import { NotificationProvider, translateKey, } from '../../affine-shared/services/index.js';
+import { fillPlaceholders, NotificationProvider, translateKey, } from '../../affine-shared/services/index.js';
 import { openSingleFileWithSpec } from '../../affine-shared/utils/index.js';
-import { getCommonBound } from '../../global/gfx/index.js';
+import { Bound, getCommonBound } from '../../global/gfx/index.js';
 import { GfxControllerIdentifier } from '../../std/gfx/index.js';
 import { DefaultTool } from '../tool/default-tool.js';
 import { InterchangeImportError, interchangeCapabilities, } from './interchange.js';
@@ -55,17 +55,70 @@ import { InterchangeImportError, interchangeCapabilities, } from './interchange.
  * whole blob and `addElement` writes it with everything else, which is the
  * whole-record LWW the field's own contract asks for (D2).
  *
+ * ## The reader's OWN names, and why there is a second map
+ *
+ * A source id is the file's, and there are two things a reader has to point at
+ * that the file never named: an element it MINTED (a framework artefact is
+ * routinely several elements — a shape, its compartments, and the group that
+ * makes them one thing), and the group membership between them. So a reader may
+ * also hand each element a provisional `id` of its own. `surface.addElement`
+ * overwrites it with a nanoid and is documented to, which is precisely what
+ * makes it safe to use as a local name: it reaches no document, and it is read
+ * here and nowhere else.
+ *
+ * A GROUP's `children` are therefore rewritten BEFORE the group is created, out
+ * of the map built so far — which costs nothing and asks the reader for the one
+ * thing it can always give: emit an element before the group that holds it. A
+ * connector is the opposite case (a flow may be written before either of its
+ * ends) and keeps its second pass.
+ *
+ * Source ids win over provisional ones wherever both could answer, so a reader
+ * that mints no local name behaves exactly as it did before this was here.
+ *
+ * ## Beside what is already drawn
+ *
+ * A reader writes the coordinates its FILE gave it, so importing the same file
+ * twice put the second board exactly on top of the first. The offset is applied
+ * here, once, for every framework, because the only thing that knows what the
+ * canvas already holds is the function doing the writing — see
+ * {@link importOffset}, and note that an empty surface is left alone.
+ *
+ * ## A read-only document is answered, not thrown at
+ *
+ * This is a public API — a host (labre-mcp) writes through it with no command
+ * in front of it — so the guard belongs here too and not only at the callers:
+ * a readonly document answers the empty array, which is the same "nothing was
+ * minted" every other refusal of this function returns, rather than an
+ * exception a caller would have to know to catch.
+ *
  * @param formatId the format whose payload key carries the source ids — the
  *   `id` of the capability's {@link InterchangeFormat}, and the ONLY thing this
  *   function ever knew about BPMN.
  */
-export function materializeInterchangeImport(std, formatId, elements) {
+export function materializeInterchangeImport(std, formatId, elements, options = {}) {
     const surface = std.get(GfxControllerIdentifier).surface;
     if (!surface)
         return [];
+    if (std.store.readonly)
+        return [];
+    const shift = importOffset(surface.elementModels, elements);
     const bySource = new Map();
+    const byLocal = new Map();
+    const resolve = (name) => bySource.get(name) ?? byLocal.get(name);
     const created = elements.map(props => {
-        const id = surface.addElement({ ...props });
+        const written = shift
+            ? translateProps(props, shift)
+            : { ...props };
+        const children = written.children;
+        if (written.type === 'group' &&
+            children !== null &&
+            typeof children === 'object') {
+            written.children = Object.fromEntries(Object.keys(children).map(child => [
+                resolve(child) ?? child,
+                true,
+            ]));
+        }
+        const id = surface.addElement(written);
         const carried = props.interchange;
         const source = carried?.[formatId]?.id;
         // FIRST wins, matching a reader's own answer to a file that used one id
@@ -73,6 +126,31 @@ export function materializeInterchangeImport(std, formatId, elements) {
         // naming that id means the first of them.
         if (source !== undefined && !bySource.has(source))
             bySource.set(source, id);
+        const local = props.id;
+        if (typeof local === 'string') {
+            // FIRST wins here too, and for the same reason — but where a duplicated
+            // SOURCE id is the FILE's mistake and the reader has already reported it,
+            // a duplicated provisional name is the READER's, and nothing else in the
+            // pipeline is in a position to notice. So it is named: every element is
+            // still imported, and the remark says which of the two a group or a
+            // connector naming it will have landed on.
+            if (byLocal.has(local)) {
+                // The English is FILLED from the wording rather than restated beside
+                // it, so the sentence a host translates and the sentence a playground
+                // with no catalogue reads cannot drift apart.
+                const messageParams = { name: local };
+                options.onNote?.({
+                    kind: 'substituted-id',
+                    elementId: id,
+                    messageKey: IMPORT_DUPLICATE_NAME_KEY,
+                    message: fillPlaceholders(IMPORT_DUPLICATE_NAME_FALLBACK, messageParams),
+                    messageParams,
+                });
+            }
+            else {
+                byLocal.set(local, id);
+            }
+        }
         return id;
     });
     for (const id of created) {
@@ -83,16 +161,138 @@ export function materializeInterchangeImport(std, formatId, elements) {
             const end = model[side];
             if (end?.id === undefined)
                 continue;
-            model[side] = { ...end, id: bySource.get(end.id) ?? end.id };
+            model[side] = { ...end, id: resolve(end.id) ?? end.id };
         }
     }
     return created;
 }
+/* ── Beside what is already there ─────────────────────────────────────── */
+/**
+ * The space left between a board that is already drawn and one just imported.
+ *
+ * Wide enough that the two read as two documents rather than as one crowded
+ * sheet, and narrow enough that the viewport fit which follows still shows the
+ * new one at a useful zoom.
+ */
+const IMPORT_BESIDE_GAP = 200;
+/** A box off one element's props, or nothing — `[x,y,w,h]`, as the store holds it. */
+function propsBound(props) {
+    const xywh = props.xywh;
+    if (typeof xywh !== 'string')
+        return undefined;
+    try {
+        return Bound.deserialize(xywh);
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * How far to move an imported board so it lands BESIDE what is already drawn.
+ *
+ * ## Why this is the seam's job and not each reader's
+ *
+ * "What arrives is a NEW board, never a merge" is already this file's rule
+ * ({@link importInterchangeFile}) — but a reader has no surface to look at, so
+ * it writes the coordinates the FILE gave it, and a second import of the same
+ * file therefore landed exactly on top of the first. Every framework had the
+ * bug and none of them could fix it: the only thing that knows what the canvas
+ * already holds is the function doing the writing.
+ *
+ * `undefined` on an EMPTY surface, and deliberately: with nothing to avoid, the
+ * board keeps the file's own coordinates, which is what every golden and every
+ * round-trip assertion is written against. Only a second import moves, which is
+ * exactly the case that was wrong.
+ *
+ * Connectors are excluded from the measurement for the reason
+ * {@link importInterchangeFile} excludes them from the viewport fit: a
+ * connector's bound is derived from a path the router has not computed yet, and
+ * it answers `[0, 0, 0, 0]` — which would anchor every offset to the origin.
+ *
+ * The list is read defensively because a SURFACE is not the only thing that ever
+ * reaches this function: several framework specs drive the pipeline through a
+ * hand-built stub that answers `addElement` and little else. A stub with no
+ * elements is an empty canvas, which is the one case that must not move.
+ */
+function importOffset(drawn, arriving) {
+    const occupied = getCommonBound((drawn ?? [])
+        .map(model => model.elementBound)
+        .filter((bound) => !!bound && bound.w > 0 && bound.h > 0));
+    if (!occupied)
+        return undefined;
+    const boxes = arriving
+        .map(propsBound)
+        .filter((bound) => bound !== undefined);
+    const incoming = getCommonBound(boxes);
+    if (!incoming)
+        return undefined;
+    return {
+        x: occupied.x + occupied.w + IMPORT_BESIDE_GAP - incoming.x,
+        y: occupied.y - incoming.y,
+    };
+}
+/**
+ * One element's props, moved.
+ *
+ * `xywh` and the label boxes, with one exception: a connector end that names no
+ * element carries an ABSOLUTE position rather than an anchor within a shape, and
+ * an end left behind would stretch the line back to where the file drew it. An
+ * end WITH an id carries a fraction of its shape's box and must not be touched.
+ *
+ * A connector's three label boxes (`labelXYWH`, and ADR 0020's two per-end
+ * siblings) are absolute `[x, y, w, h]` in the same space as `xywh`, so they
+ * move with everything else. A reader that creates a connector with an end label
+ * already positioned — `gfx/uml`'s materializer does — would otherwise drop the
+ * text at the origin of a board it was not imported onto.
+ */
+function translateProps(props, shift) {
+    const moved = { ...props };
+    const bound = propsBound(props);
+    if (bound) {
+        moved.xywh = new Bound(bound.x + shift.x, bound.y + shift.y, bound.w, bound.h).serialize();
+    }
+    for (const key of ['labelXYWH', 'sourceLabelXYWH', 'targetLabelXYWH']) {
+        const box = props[key];
+        if (!Array.isArray(box) || box.length !== 4)
+            continue;
+        if (!box.every(each => typeof each === 'number'))
+            continue;
+        const [x, y, w, h] = box;
+        moved[key] = [x + shift.x, y + shift.y, w, h];
+    }
+    for (const side of ['source', 'target']) {
+        const end = props[side];
+        if (!end || end.id !== undefined || !Array.isArray(end.position))
+            continue;
+        moved[side] = {
+            ...end,
+            position: [end.position[0] + shift.x, end.position[1] + shift.y],
+        };
+    }
+    return moved;
+}
 /* ── Saying what it cost ──────────────────────────────────────────────── */
 const IMPORT_DONE_KEY = 'com.labre.interchange.import.done';
 const IMPORT_DONE_FALLBACK = 'file imported';
 const IMPORT_FAILED_KEY = 'com.labre.interchange.import.failed';
 const IMPORT_FAILED_FALLBACK = 'This file could not be imported';
+/**
+ * What an imported sheet is called when neither the file nor the source
+ * document names it — resolved HERE, at the creation site, because that is
+ * where `std` is (ADR 0023 §3: a seed is translated by whoever writes it, and
+ * a pure reader never can). The readers keep the same English text as their
+ * own last-resort default, so a headless call still produces a named sheet.
+ */
+const IMPORT_DEFAULT_NAME_KEY = 'com.labre.interchange.import.default-name';
+const IMPORT_DEFAULT_NAME_FALLBACK = 'Imported diagram';
+/**
+ * The document went read-only between the moment the file was accepted and the
+ * moment its board was about to be written — see the second guard in
+ * {@link importInterchangeFile}. Its own sentence rather than the reader's,
+ * because nothing is wrong with the FILE.
+ */
+const IMPORT_READONLY_KEY = 'com.labre.interchange.import.readonly';
+const IMPORT_READONLY_FALLBACK = 'This document became read-only while the file was being read, so nothing was imported.';
 const IMPORT_REMARKS_KEY = 'com.labre.interchange.import.remarks';
 const IMPORT_REMARKS_FALLBACK = 'What the import could not keep as it was';
 const IMPORT_CONSOLE_KEY = 'com.labre.interchange.import.console';
@@ -103,6 +303,16 @@ const IMPORT_CARRIED_KEY = 'com.labre.interchange.import.carried';
 const IMPORT_CARRIED_FALLBACK = 'carried';
 const IMPORT_QUARANTINED_KEY = 'com.labre.interchange.import.quarantined';
 const IMPORT_QUARANTINED_FALLBACK = 'quarantined';
+/**
+ * The one remark the MATERIALIZER raises itself (see the provisional-name note
+ * on `SerializedElementProps`) — this pipeline's own words about its own
+ * substitution, not a reader's, so it is keyed here with the rest of the
+ * pipeline's chrome rather than in any one format's table. `{{name}}` is the
+ * provisional name the reader minted, filled from `messageParams` by
+ * `resolveNoteMessage` exactly as a reader's own remark is.
+ */
+const IMPORT_DUPLICATE_NAME_KEY = 'com.labre.interchange.import.duplicate-provisional-name';
+const IMPORT_DUPLICATE_NAME_FALLBACK = 'Two imported elements were handed the same provisional name "{{name}}". Both are on the board; anything referring to that name points at the first of them.';
 /**
  * How many remarks the second notification spells out before it hands the
  * reader to the console.
@@ -265,7 +475,7 @@ export function reportInterchangeImport(std, format, report) {
  * deliberately so: a dialog a document cannot honour should never open in the
  * first place.
  */
-export async function runInterchangeImportFile(std, capability) {
+export async function runInterchangeImportFile(std, capability, options = {}) {
     const gfx = std.get(GfxControllerIdentifier);
     if (!gfx.surface || std.store.readonly)
         return;
@@ -278,7 +488,7 @@ export async function runInterchangeImportFile(std, capability) {
     // know what they just did.
     if (!file)
         return;
-    await importInterchangeFile(std, capability, file);
+    await importInterchangeFile(std, capability, file, options);
 }
 /**
  * The import itself, over a file the caller ALREADY HAS: run the declared
@@ -317,14 +527,23 @@ export async function runInterchangeImportFile(std, capability) {
  * its refusals it was, so it is shown as it is rather than replaced with a
  * wording of our own that knows less.
  */
-export async function importInterchangeFile(std, capability, file) {
+export async function importInterchangeFile(std, capability, file, options = {}) {
     const gfx = std.get(GfxControllerIdentifier);
     if (!gfx.surface || std.store.readonly)
         return;
     const { format } = capability;
     let result;
     try {
-        result = capability.run(await file.text(), { name: file.name });
+        const text = await file.text();
+        // The container, opened — see {@link InterchangeImportOptions.decode}. Inside
+        // the same `try` as the reader, deliberately: "this .drawio could not be
+        // inflated" and "this is not a BPMN document" are the same event to the
+        // person who picked the file, and they take the same notification.
+        const source = options.decode ? await options.decode(text, file) : text;
+        result = capability.run(source, {
+            name: file.name.trim() ||
+                translateKey(std, IMPORT_DEFAULT_NAME_KEY, IMPORT_DEFAULT_NAME_FALLBACK),
+        });
     }
     catch (error) {
         // `InterchangeImportError` checked FIRST: a reader that throws it declared
@@ -343,12 +562,33 @@ export async function importInterchangeFile(std, capability, file) {
         });
         return;
     }
+    // The guard at the top was a decision taken BEFORE two `await`s, and rights
+    // can be lost while they run: a remote cascade turning the store read-only
+    // between the picker and this line is the same class of defect as issue #324
+    // ("Cannot remove element in readonly mode"). Writing anyway rejects a
+    // promise nobody awaits, and returning in silence loses a file the user
+    // chose — so it is said, through the channel every other import failure uses.
+    if (std.store.readonly) {
+        notifyImport(std, {
+            title: translateKey(std, IMPORT_FAILED_KEY, IMPORT_FAILED_FALLBACK),
+            message: translateKey(std, IMPORT_READONLY_KEY, IMPORT_READONLY_FALLBACK),
+            accent: 'error',
+        });
+        return;
+    }
     // One undo step for the whole file, the way one lane gesture is one step:
     // `captureSync` before opens a boundary, the writes land inside it, and the
     // second one closes it. An import a user has to undo forty times is an import
     // they cannot undo.
+    // What the WRITING found that the reading could not: a provisional name the
+    // reader handed out twice. Collected here rather than pushed into the
+    // reader's own array, which is `readonly` and is the reader's statement about
+    // the file — this is a statement about the import.
+    const written = [];
     std.store.captureSync();
-    const created = materializeInterchangeImport(std, format.id, result.elements);
+    const created = materializeInterchangeImport(std, format.id, result.elements, {
+        onNote: note => written.push(note),
+    });
     std.store.captureSync();
     // …and then bring it into view, which is what template insertion does for
     // the same reason: a board that landed off-screen looks like a command that
@@ -381,7 +621,9 @@ export async function importInterchangeFile(std, capability, file) {
         gfx.viewport.setViewportByBound(bound, [padding, padding, padding, padding], true);
     }
     gfx.tool.setTool(DefaultTool);
-    reportInterchangeImport(std, format, result.report);
+    reportInterchangeImport(std, format, written.length === 0
+        ? result.report
+        : { ...result.report, notes: [...result.report.notes, ...written] });
 }
 /* ── What can read a file called this ─────────────────────────────────── */
 /**

package/dist/_pkgs/affine-block-surface/extensions/interchange.d.ts

@@ -69,6 +69,24 @@ export type InterchangeDirection = 'import' | 'export';
  * One element as it is handed to `surface.addElement` — the exact shape the
  * store already takes, so an importer's output is written with no translation
  * step in between and no live model in sight.
+ *
+ * ## The provisional `id`, and how a reader points at itself
+ *
+ * A reader names things the FILE named through `interchange[formatId].id`, and
+ * that is the identity `materializeInterchangeImport` remaps endpoints from. It
+ * is not enough on its own: a framework artefact is routinely several elements
+ * the file never mentioned — a shape, its compartment texts, and the group that
+ * makes them one thing — so a reader may also put an `id` of its own on each
+ * element. `surface.addElement` OVERWRITES it with a nanoid and is documented
+ * to, which is exactly what makes it safe as a local name: it reaches no
+ * document, it is read by the materializer and nowhere else, and it cannot
+ * collide with a real surface id. Two rules make it work — a reader emits an
+ * element BEFORE any group that holds it (a group's `children` are rewritten
+ * from the map built so far, in one pass, rather than deferred like a
+ * connector's two ends), and a SOURCE id wins wherever both could answer, so a
+ * reader that mints no local name behaves exactly as it did before this
+ * existed. A provisional name used twice resolves to the FIRST element that
+ * claimed it, and the import says so in a `substituted-id` note.
  */
 export type SerializedElementProps = Record<string, unknown> & {
     type: string;

package/dist/_pkgs/affine-block-surface/extensions/legend-toolbar.d.ts

@@ -0,0 +1,81 @@
+import { type ChromeWording, type FrameworkElementEvent, type ToolbarAction } from '../../affine-shared/services/index.js';
+import type { BlockStdScope, CommandOwner } from '../../std/index.js';
+import { type TemplateResult } from 'lit';
+/**
+ * The legend BUTTON — one factory and one emitter for every framework that has
+ * a legend, where there were seven copies of the same twenty lines.
+ *
+ * The legend deliberately stays a BUTTON and never becomes a command (PO
+ * arbitration of 27/08/2026, R6 of `docs/add-a-framework/02-framework-rules.md`):
+ * generating one belongs to a board you have SELECTED and to nothing else, so
+ * it is absent from the catalogue, the palette and Settings › Shortcuts — and
+ * the command registry's per-framework counts must not move because of it.
+ *
+ * The cost of staying outside `runCommand` is that the telemetry it owes is
+ * emitted by hand. {@link trackLegendCreated} is where, once, so the wire
+ * values cannot drift apart across seven files again.
+ */
+/**
+ * The HISTORICAL PostHog value of the `framework` dimension — `context-map`,
+ * not `ddd-context-map`, and `event-storming`, not `ddd-event-storming`. Taken
+ * from the event's own closed union rather than restated, so a framework that
+ * never joined the taxonomy cannot be passed here by mistake.
+ */
+export type LegendFramework = FrameworkElementEvent['framework'];
+/**
+ * Contextual-toolbar glyph — "generate the legend of what is on this board".
+ * One icon because it is one gesture; the Core Domain chart has drawn this exact
+ * box-and-rows since its legend button shipped and the others borrowed it.
+ *
+ * `html` rather than `svg`: a toolbar action's `icon` is rendered as a
+ * standalone template, unlike the senior-button glyphs that are interpolated
+ * into an outer `<svg>`.
+ */
+export declare const legendIcon: TemplateResult<1>;
+/**
+ * The ONE `FrameworkLegendCreated` emission, with the wire values every
+ * framework's own button has been sending.
+ *
+ * `framework` is the HISTORICAL PostHog value (`FrameworkDescriptor.
+ * telemetryKey`): `context-map`, not `ddd-context-map`. It is a parameter and
+ * not derived from anything, because the two spellings differ for three of the
+ * eight frameworks and a prefix rule would quietly rename a metric.
+ */
+export declare function trackLegendCreated(std: BlockStdScope, framework: LegendFramework, module: string): void;
+export interface LegendToolbarActionOptions<M extends {
+    xywh: string;
+}> {
+    /**
+     * Sort key inside the row, and NOT a constant across frameworks: the toolbar
+     * orders lexicographically by id, so a legend that must land after "remove a
+     * lane" is `c.legend` while C4's is `b.legend` and Wardley's `d.legend`.
+     * Defaults to `b.legend`, the commonest.
+     */
+    id?: string;
+    /** The board element this button documents — how it finds it in the selection. */
+    Model: abstract new (...args: any[]) => M;
+    /** Whose commands the rows are derived from. See {@link createBoardLegend}. */
+    owner: CommandOwner;
+    /** The HISTORICAL telemetry value. See {@link trackLegendCreated}. */
+    framework: LegendFramework;
+    /**
+     * The `module` dimension. Defaults to `` `${framework} toolbar` ``, which is
+     * what six of the seven buttons send; UML's is `uml toolbox` and says so.
+     */
+    module?: string;
+    tooltipWording?: ChromeWording;
+    icon?: TemplateResult;
+}
+/**
+ * The shared legend entry of a board's contextual toolbar.
+ *
+ * Registered by each framework in its OWN flag-gated module
+ * (`custom:affine:surface:<board>`), merged with `validationToolbarConfig`'s
+ * actions: a flavour may carry exactly one toolbar module, and generating a
+ * legend is tooling a flag may take away. What the gesture already WROTE is
+ * document content and keeps being painted with the flag off — the box is made
+ * of plain shapes, text and the framework's own always-on renderers.
+ */
+export declare function legendToolbarAction<M extends {
+    xywh: string;
+}>({ id, Model, owner, framework, module, tooltipWording, icon, }: LegendToolbarActionOptions<M>): ToolbarAction;