@formicoidea/labre-core 0.40.0 → 0.42.0

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

@@ -1,10 +1,10 @@
 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 { interchangeCapabilities, } from './interchange.js';
+import { InterchangeImportError, interchangeCapabilities, } 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`).
@@ -55,17 +55,70 @@ import { interchangeCapabilities, } from './interchange.js';
  * 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,129 @@ 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';
+/**
+ * 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 +294,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.
@@ -126,18 +327,28 @@ const REMARKS_IN_A_NOTIFICATION = 5;
  */
 const formatLabel = (format) => format.id.toUpperCase();
 /**
- * One remark, as the line a reader sees.
+ * One remark's own wording — the reader that produced it had no `std` and
+ * could not translate it (P3), so this is where a remark that declared a key
+ * (`InterchangeNote.messageKey`) gets it, `{{name}}` holes filled from
+ * `messageParams` with no host catalogue exactly as they were filled by the
+ * reader's own string interpolation before either field existed. A remark
+ * with no key is one that names something out of the file with no sentence
+ * shape worth sharing, and is shown as the reader wrote it.
  *
- * The reader that produced it had no `std` and could not translate it (P3), so
- * this is where a remark that declared a key gets its wording — with its own
- * `message` as the English default, exactly like every other `translateKey`
- * call site. A remark with no key is one that names something out of the file
- * and is shown as the reader wrote it (see `InterchangeNote.messageKey`).
+ * The one function every READER of `note.message` goes through — the
+ * notification line below (`remarkLine`) and the console table
+ * (`reportInterchangeImport`) both resolve through it, so a note keyed via
+ * the `TABLE.key[1]` pattern (its OWN fallback, not a hand-rebuilt literal)
+ * reads identically in both rather than showing raw `{{tag}}` in the console.
  */
-function remarkLine(std, note) {
-    const message = note.messageKey
-        ? translateKey(std, note.messageKey, note.message)
+function resolveNoteMessage(std, note) {
+    return note.messageKey
+        ? translateKey(std, note.messageKey, note.message, note.messageParams)
         : note.message;
+}
+/** One remark, as the line a reader sees. */
+function remarkLine(std, note) {
+    const message = resolveNoteMessage(std, note);
     const subject = note.sourceId ?? note.element;
     return subject ? `${subject}: ${message}` : message;
 }
@@ -220,7 +431,7 @@ export function reportInterchangeImport(std, format, report) {
         kind: note.kind,
         source: note.sourceId ?? '',
         element: note.element ?? '',
-        message: note.message,
+        message: resolveNoteMessage(std, note),
     })));
     notifyImport(std, {
         title: translateKey(std, IMPORT_REMARKS_KEY, IMPORT_REMARKS_FALLBACK),
@@ -255,7 +466,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;
@@ -268,7 +479,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
@@ -307,19 +518,48 @@ 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 });
     }
     catch (error) {
+        // `InterchangeImportError` checked FIRST: a reader that throws it declared
+        // a key for its own refusal, resolved exactly like a note's `messageKey`
+        // (see `remarkLine`, above). Any other `Error` (or a non-`Error` throw)
+        // reads as it always did.
+        const message = error instanceof InterchangeImportError && error.messageKey
+            ? translateKey(std, error.messageKey, error.message, error.messageParams)
+            : error instanceof Error
+                ? error.message
+                : String(error);
         notifyImport(std, {
             title: translateKey(std, IMPORT_FAILED_KEY, IMPORT_FAILED_FALLBACK),
-            message: error instanceof Error ? error.message : String(error),
+            message,
+            accent: 'error',
+        });
+        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;
@@ -328,8 +568,15 @@ export async function importInterchangeFile(std, capability, file) {
     // `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
@@ -362,7 +609,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;
@@ -97,21 +115,26 @@ export interface InterchangeNote {
     message: string;
     /**
      * The i18n key {@link message} is the English default of — set only when the
-     * remark is a FIXED sentence.
+     * remark is a FIXED sentence, one per SHAPE of sentence rather than one per
+     * exact string (a `{{name}}` hole is filled by {@link messageParams}, not by
+     * minting a new key for every value the file happens to carry).
      *
      * A reader is a pure function of text (`docs/adr/0012`, P3): it has no `std`,
      * so it cannot reach the host's catalogue and hands the key over instead, and
      * `reportInterchangeImport` resolves it when it draws the report. That is the
-     * whole of the seam here, and it deliberately covers only the remarks that
-     * say the same thing every time.
+     * whole of the seam here.
      *
-     * A remark that NAMES something out of the file — an element, an id, a count
-     * of lanes — carries no key and stays English. The seam has no interpolation
-     * and no pluralisation (both are the host's), so the alternative would be to
-     * invent a grammar for sentences with holes in them, which is exactly what
-     * the three interchange count labels already refuse to do.
+     * A remark that names something out of the file with no sentence shape worth
+     * sharing (a raw dump, a one-off diagnostic) carries no key and stays
+     * English — the seam still has no pluralisation, which is the host's.
      */
     messageKey?: string;
+    /**
+     * `{{name}}`-style values for {@link messageKey}'s placeholders — the file's
+     * own words (a unit, a tag name), never a sentence of their own. Ignored
+     * when {@link messageKey} is absent.
+     */
+    messageParams?: Record<string, string | number>;
 }
 /**
  * The five things worth saying about one item, and no sixth.
@@ -161,6 +184,33 @@ export interface InterchangeReport {
      */
     sourceVersion?: string;
 }
+/**
+ * A reader's own refusal — THROWN, not returned, because the report's three
+ * counts (`InterchangeReport`) cannot say "this is not a file I can read": a
+ * report of three zeroes would claim an empty document where there was none
+ * (see `importInterchangeFile`, "Failure is an exception, and it says which
+ * one", `interchange-import.ts`).
+ *
+ * Carries the reader's own English sentence as `Error.message`, so every
+ * existing `catch` site that only ever did `error.message` keeps reading
+ * exactly what it read before — plus the same optional key/params pair
+ * {@link InterchangeNote} carries, on the same seam: a reader has no `std`
+ * (`docs/adr/0012`, P3) and cannot translate its own refusal, so the catch
+ * site that DOES have one (`importInterchangeFile`) resolves it exactly as
+ * `remarkLine` resolves a note.
+ *
+ * Optional and additive: a reader that still throws a plain `Error` (or any
+ * other capability's failure) is caught exactly as before — this class only
+ * gives the catch site a SECOND thing to check, never a first requirement.
+ */
+export declare class InterchangeImportError extends Error {
+    readonly messageKey?: string;
+    readonly messageParams?: Record<string, string | number>;
+    constructor(message: string, options?: {
+        messageKey?: string;
+        messageParams?: Record<string, string | number>;
+    });
+}
 /** What the caller tells an exporter about the document it is producing. */
 export interface InterchangeExportContext {
     /**

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

@@ -1,4 +1,31 @@
 import { createIdentifier } from '../../global/di/index.js';
+/**
+ * A reader's own refusal — THROWN, not returned, because the report's three
+ * counts (`InterchangeReport`) cannot say "this is not a file I can read": a
+ * report of three zeroes would claim an empty document where there was none
+ * (see `importInterchangeFile`, "Failure is an exception, and it says which
+ * one", `interchange-import.ts`).
+ *
+ * Carries the reader's own English sentence as `Error.message`, so every
+ * existing `catch` site that only ever did `error.message` keeps reading
+ * exactly what it read before — plus the same optional key/params pair
+ * {@link InterchangeNote} carries, on the same seam: a reader has no `std`
+ * (`docs/adr/0012`, P3) and cannot translate its own refusal, so the catch
+ * site that DOES have one (`importInterchangeFile`) resolves it exactly as
+ * `remarkLine` resolves a note.
+ *
+ * Optional and additive: a reader that still throws a plain `Error` (or any
+ * other capability's failure) is caught exactly as before — this class only
+ * gives the catch site a SECOND thing to check, never a first requirement.
+ */
+export class InterchangeImportError extends Error {
+    constructor(message, options) {
+        super(message);
+        this.name = 'InterchangeImportError';
+        this.messageKey = options?.messageKey;
+        this.messageParams = options?.messageParams;
+    }
+}
 /** The separator the triple is built from, and therefore reserved in its parts. */
 const ID_SEPARATOR = ':';
 /** The one way to spell a capability's id. */

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;