@formicoidea/labre-core 0.31.0 → 0.32.0

package/dist/_pkgs/affine-shared/services/telemetry-service/lifecycle.d.ts

@@ -1,3 +1,4 @@
+import type { FrameworkId } from '../../../std/index.js';
 import type { TelemetryEvent } from './types.js';
 /**
  * Per-block lifecycle taxonomy. Every block flavour reports the same five
@@ -36,8 +37,189 @@ export interface FrameworkElementEvent extends TelemetryEvent {
     framework: 'wardley' | 'edgy' | 'cynefin' | 'bpmn' | 'event-storming' | 'core-domain' | 'context-map';
     element: string;
 }
+/**
+ * A rung of the promotion ladder was crossed (MF1 / ADR 0007 § 7):
+ * shape → role → component (a pivot record) → materialities. Promotion is
+ * never a conversion — no element is created, destroyed or swapped, and no
+ * geometry moves.
+ *
+ * **A new event name, deliberately.** An earlier draft reused
+ * `FrameworkElementAdded` under a "no new event names" rule; that was a
+ * taxonomy break. ADR 0003 § 2 defines the creation event as UI intent emitted
+ * at INSERTION sites, and a promotion inserts nothing — so drawing a shape and
+ * then binding it would emit `FrameworkElementAdded` twice and permanently
+ * inflate "elements added per framework". A new event is cheaper than a
+ * corrupted funnel.
+ *
+ * Ids only, never board content: which rung was crossed, in which direction,
+ * under which role.
+ */
+export interface FrameworkPromotionEvent extends TelemetryEvent {
+    page?: 'whiteboard editor';
+    /**
+     * Owning framework, when the element has one — derived from the namespace of
+     * its `role` (`wardley:component` → `wardley`).
+     *
+     * OPTIONAL, which is a deviation from ADR 0007 § 7's `framework: FrameworkId`.
+     * That ADR's own § 6 states no rung requires the previous one: an element may
+     * carry a `pivotDocId` with no `role` at all, and a plain rectangle bound to
+     * a record belongs to no framework. Requiring the field would force the
+     * library to invent an identity it does not have — the one thing the
+     * `FrameworkId` unification exists to stop. Absent rather than `'unknown'`,
+     * per the repo convention.
+     */
+    framework?: FrameworkId;
+    /** Which rung was crossed. */
+    rung: 'role' | 'pivot' | 'tag';
+    /** Forward (`shape`→`role`) or the reverse gesture. */
+    direction: 'promote' | 'demote';
+    /** Role id at the time of the gesture, when there is one. */
+    role?: string;
+    /** How many elements the single gesture wrote to. */
+    elementCount: number;
+}
+/**
+ * The persisted direction of a TYPED EDGE was reversed (`docs/adr/0010` M3):
+ * `source` and `target` swapped, in one undo step, by the only supported
+ * inversion.
+ *
+ * Worth its own event for the same reason an exception is worth one: this is
+ * the correction gesture of a decision the user could not previously see, so
+ * how often it is used is the measurement of whether the DRAWING gesture (M1)
+ * announces itself well enough. A framework whose links are reversed constantly
+ * is a framework whose hint is wrong.
+ *
+ * Ids only — the role and the framework its namespace names — never board
+ * content, and never the two element ids.
+ */
+export interface EdgeDirectionEvent extends TelemetryEvent {
+    page?: 'whiteboard editor';
+    /** Role id of the inverted edges, when they all carry the same one. */
+    role?: string;
+    /** Its namespace, when that names a framework: `wardley:dependency` → `wardley`. */
+    framework?: string;
+    /** How many edges the single gesture reversed. */
+    elementCount: number;
+}
 export type FrameworkDiagramEvents = {
     FrameworkElementAdded: FrameworkElementEvent;
     FrameworkToolPicked: FrameworkElementEvent;
     FrameworkLegendCreated: FrameworkElementEvent;
+    FrameworkElementPromoted: FrameworkPromotionEvent;
+    EdgeDirectionInverted: EdgeDirectionEvent;
+};
+/**
+ * A user arbitration on a validation rule (PF8): "no rule is a wall", so every
+ * rule can be waived — and every waiver is worth knowing about. A rule that
+ * gets waived constantly is a rule that is wrong, and this is the only place
+ * that says so.
+ *
+ * `ruleId` is the framework-namespaced rule id (`wardley.change-arrow-against-evolution`)
+ * and never carries user content — the event describes which RULE was arbitrated
+ * on, never what the board contains.
+ */
+export interface ValidationExceptionEvent extends TelemetryEvent {
+    page?: 'whiteboard editor';
+    /** Namespaced rule id, e.g. `wardley.change-arrow-against-evolution`. */
+    ruleId: string;
+    /** Owning framework of the rule, when it is registered. */
+    framework?: string;
+    /** `element` = this one element; `map` = every element the map frames. */
+    scope: 'element' | 'map';
+    /** How many elements the single gesture wrote to. */
+    elementCount: number;
+}
+/**
+ * A change of the level of requirement a framework instance is checked against
+ * (PF9). Worth knowing about for the same reason an exception is: a profile
+ * nobody ever leaves is a default that is right, and one everybody escapes on
+ * the first day is a default that is wrong.
+ *
+ * Ids only — the framework's own namespaced profile ids — never user content.
+ */
+export interface ValidationProfileEvent extends TelemetryEvent {
+    page?: 'whiteboard editor';
+    /** Owning framework of the profile, e.g. `wardley`. */
+    framework: string;
+    /** Namespaced profile id now in force, e.g. `wardley.strict`. */
+    profileId: string;
+    /** The one it replaces, when it is known. */
+    previousProfileId?: string;
+}
+/**
+ * A map-quality NUDGE ticked or unticked (PF7.10). Worth knowing about for the
+ * same reason an exception is, and for one more: a nudge everybody ticks
+ * immediately is a reminder nobody needed, and one nobody ever ticks is an
+ * expectation the tool has failed to make actionable. Neither is visible any
+ * other way, because nothing here is ever computed.
+ *
+ * Ids only — the framework's own namespaced nudge ids — never board content.
+ */
+export interface MapQualityNudgeEvent extends TelemetryEvent {
+    page?: 'whiteboard editor';
+    /** Owning framework of the nudge, e.g. `wardley`. */
+    framework: string;
+    /** Namespaced nudge id, e.g. `wardley.q1-title`. */
+    nudgeId: string;
+    /** `true` = ticked ("I have taken care of this"), `false` = taken back. */
+    checked: boolean;
+}
+export type ValidationEvents = {
+    ValidationExceptionGranted: ValidationExceptionEvent;
+    ValidationExceptionRevoked: ValidationExceptionEvent;
+    ValidationProfileChanged: ValidationProfileEvent;
+    MapQualityNudgeToggled: MapQualityNudgeEvent;
+};
+/**
+ * An AI audit run (PF14.1) — level 3, executed app-side by the Labre Assistant
+ * through the `AuditProvider` seam.
+ *
+ * Three events rather than one, because the three questions are different: how
+ * often is an audit asked for (started), does it ever finish (completed), and
+ * how often does it not (interrupted). A single event with a status field would
+ * answer the first and lose the other two the moment a run never resolves.
+ *
+ * Ids and counts only — criterion ids and how many findings came back. The
+ * board's content, the criteria's prompts and the findings' wording never leave
+ * the editor through this bus.
+ */
+export interface MapAuditEvent extends TelemetryEvent {
+    page?: 'whiteboard editor';
+    /** Owning framework of the criteria, when the run carries only one. */
+    framework?: string;
+    /** How many criteria the run was given. */
+    criterionCount: number;
+    /** How many framework frames the facts described. */
+    frameCount: number;
+}
+export interface MapAuditCompletedEvent extends MapAuditEvent {
+    /** How many findings came back, after the library's normalisation. */
+    findingCount: number;
+    /** Wall-clock duration of the run, in milliseconds. */
+    durationMs: number;
+}
+export interface MapAuditInterruptedEvent extends MapAuditEvent {
+    /**
+     * Why it did not complete.
+     *
+     * `unavailable` is a first-class member and not an error: no assistant is
+     * wired in this assembly, or the one that is declared itself unable to answer
+     * (feature flag, quota, no model configured). Knowing how often a user
+     * reaches for an audit that cannot run is precisely the number that decides
+     * whether the affordance should be there at all.
+     *
+     * `superseded` means a newer run for the same editor started while this one
+     * was in flight, so its answer was dropped rather than published. It is
+     * reported here rather than as a completion because a `findingCount` for
+     * findings nobody will see is a metric that lies — and a rising `superseded`
+     * count is itself the signal that audits are slow enough that users ask
+     * twice.
+     */
+    reason: 'aborted' | 'error' | 'unavailable' | 'superseded';
+    durationMs: number;
+}
+export type AuditEvents = {
+    MapAuditStarted: MapAuditEvent;
+    MapAuditCompleted: MapAuditCompletedEvent;
+    MapAuditInterrupted: MapAuditInterruptedEvent;
 };

package/dist/_pkgs/affine-shared/services/telemetry-service/telemetry-service.d.ts

@@ -2,12 +2,12 @@ import type { ExtensionType } from '../../../store/index.js';
 import type { CitationEvents } from './citation.js';
 import type { CodeBlockEvents } from './code-block.js';
 import type { OutDatabaseAllEvents } from './database.js';
-import type { BlockLifecycleEvents, FrameworkDiagramEvents } from './lifecycle.js';
+import type { AuditEvents, BlockLifecycleEvents, FrameworkDiagramEvents, ValidationEvents } from './lifecycle.js';
 import type { LinkToolbarEvents } from './link.js';
 import type { NoteEvents } from './note.js';
 import type { SlashMenuEvents } from './slash-menu.js';
 import type { AttachmentReloadedEvent, AttachmentReloadedEventInToolbar, AttachmentUpgradedEvent, AttachmentUploadedEvent, BlockCreationEvent, DocCreatedEvent, EdgelessToolPickedEvent, ElementCreationEvent, ElementLockEvent, ElementUpdatedEvent, LatexEvent, LinkedDocCreatedEvent, LinkEvent, MindMapCollapseEvent, TelemetryEvent } from './types.js';
-export type TelemetryEventMap = OutDatabaseAllEvents & LinkToolbarEvents & SlashMenuEvents & CodeBlockEvents & NoteEvents & CitationEvents & BlockLifecycleEvents & FrameworkDiagramEvents & {
+export type TelemetryEventMap = OutDatabaseAllEvents & LinkToolbarEvents & SlashMenuEvents & CodeBlockEvents & NoteEvents & CitationEvents & BlockLifecycleEvents & FrameworkDiagramEvents & ValidationEvents & AuditEvents & {
     DocCreated: DocCreatedEvent;
     Link: TelemetryEvent;
     LinkedDocCreated: LinkedDocCreatedEvent;

package/dist/_pkgs/affine-shared/services/telemetry-service/types.d.ts

@@ -1,4 +1,9 @@
-export type ElementCreationSource = 'shortcut' | 'toolbar:general' | 'toolbar:dnd' | 'canvas:drop' | 'canvas:draw' | 'canvas:dbclick' | 'canvas:paste' | 'context-menu' | 'ai' | 'internal' | 'conversation' | 'manually save';
+/**
+ * Re-exported, unchanged, from `@labre/std`: `CommandInvocation.source` is
+ * typed on it and the command registry sits below this layer (ADR 0008).
+ */
+import type { ElementCreationSource } from '../../../std/index.js';
+export type { ElementCreationSource };
 export interface TelemetryEvent {
     page?: string;
     segment?: string;

package/dist/_pkgs/affine-shared/services/toolbar-service/action.d.ts

@@ -12,6 +12,16 @@ type ActionBase = {
     when?: ((cx: ToolbarContext) => boolean) | boolean;
     active?: ((cx: ToolbarContext) => boolean) | boolean;
     placement?: ActionPlacement;
+    /**
+     * How hard this entry holds its place when the row runs out of room —
+     * **higher stays on the row longer**. Defaults to `0`, and among equals the
+     * entry rendered LAST gives way first, so an action that says nothing keeps
+     * the order the toolbar already has (see `layout.ts`).
+     *
+     * Declaring it is how an entry escapes that default: a rare, wordy entry that
+     * happens to sort early asks to give way sooner with a negative number.
+     */
+    priority?: number;
 };
 export type ToolbarAction = ActionBase & {
     label?: string;

package/dist/_pkgs/affine-shared/services/toolbar-service/index.d.ts

@@ -2,5 +2,6 @@ export * from './action.js';
 export * from './config.js';
 export * from './context.js';
 export { Flag as ToolbarFlag } from './flags.js';
+export * from './layout.js';
 export * from './module.js';
 export * from './registry.js';

package/dist/_pkgs/affine-shared/services/toolbar-service/index.js

@@ -2,5 +2,6 @@ export * from './action.js';
 export * from './config.js';
 export * from './context.js';
 export { Flag as ToolbarFlag } from './flags.js';
+export * from './layout.js';
 export * from './module.js';
 export * from './registry.js';

package/dist/_pkgs/affine-shared/services/toolbar-service/layout.d.ts

@@ -0,0 +1,134 @@
+/**
+ * **Priority collapse** — how a contextual toolbar stays on ONE line.
+ *
+ * The PO's arbitration of 02/08/2026 killed the previous answer, which was to
+ * let the toolbar wrap onto a second row: the "⋮" button ended up alone on a
+ * line of its own, and a toolbar whose height changes with the selection is a
+ * toolbar that moves under the cursor. The replacement is the one every desktop
+ * toolbar has used for thirty years — when the row runs out of room, the least
+ * important entries give way, in that order, into the overflow menu that is
+ * already there.
+ *
+ * ## Why the algorithm lives here and not in the widget
+ *
+ * Nothing below touches the DOM. It takes the entries' DECLARED priority and a
+ * handful of measured widths and answers "which entries give way, and how" —
+ * which makes it a pure function the unit suite can pin down entirely, and
+ * leaves the widget with only the two things that genuinely need a browser:
+ * measuring, and re-rendering.
+ *
+ * It also keeps the rule where the rule belongs. `priority` is a field of
+ * {@link ToolbarAction}, so an entry decides its own fate from its own config
+ * file; the widget never learns that a framework exists.
+ *
+ * ## The two ways an entry gives way, in order
+ *
+ * 1. **Icon only.** An entry that renders an icon AND a label drops its label
+ *    first, keeping the label as its tooltip. A wordy entry costs three times
+ *    an icon, and losing the word to a hover is a far smaller loss than losing
+ *    the entry to a menu.
+ * 2. **Into the "⋮" menu.** Only then does the entry leave the row, keeping its
+ *    full label and its behaviour as an entry of the menu.
+ *
+ * Every entry that CAN shrink shrinks before any entry moves — a row of icons
+ * is still a row of things you can click, and a menu is not.
+ *
+ * ## When a plan is worth remaking
+ *
+ * The arithmetic above answers "what should the row look like at this width".
+ * It does NOT answer "is this width worth answering for", and the PO's second
+ * pass of 02/08/2026 is about that second question: during a zoom the room the
+ * row has moves sixty times a second, and a row that replans on every one of
+ * those frames visibly hesitates between several compositions — and, since its
+ * width is what the positioner anchors, between several places.
+ *
+ * Two answers are refused, both of them pure and both of them here:
+ * {@link toolbarRoomChanged} refuses a change too small to mean anything, and
+ * {@link TOOLBAR_SETTLE_DELAY} is how long the room must hold still before the
+ * widget bothers to ask at all.
+ */
+/**
+ * How much the room must move before the row is worth re-composing, in pixels.
+ *
+ * A few pixels, deliberately: less than the narrowest thing the row could give
+ * up, so no real degradation is ever delayed by it, and more than the noise the
+ * measurements carry — a fractional zoom, a rounded rect, a scrollbar coming
+ * and going. Two measurements that differ by a hair are the same measurement,
+ * and treating them as two is how a composition ends up alternating forever.
+ */
+export declare const TOOLBAR_ROOM_HYSTERESIS = 4;
+/**
+ * How long the room must hold still before the row is replanned, in ms.
+ *
+ * Long enough to bridge the frames of a gesture — a zoom, a pan, a window being
+ * dragged — so the row keeps ONE composition for the whole of it, and short
+ * enough that letting go feels like the row simply followed.
+ */
+export declare const TOOLBAR_SETTLE_DELAY = 150;
+/**
+ * Whether the room the row has really changed since the plan on screen.
+ *
+ * `Infinity` is a value like any other here: a row nothing has positioned yet
+ * has all the room in the world, and going from that to a finite cap (or back)
+ * is always a change, however large the numbers are.
+ */
+export declare function toolbarRoomChanged(planned: number, measured: number, threshold?: number): boolean;
+/** One entry of the row, as the planner sees it. */
+export interface ToolbarLayoutItem {
+    id: string;
+    /**
+     * Higher stays on the row longer. `0` unless the entry says otherwise; among
+     * equals the one rendered LAST gives way first, so leaving every entry alone
+     * reproduces the order the toolbar already has.
+     */
+    priority: number;
+    /** Renders an icon and a label today, so it has a label to drop. */
+    shrinkable: boolean;
+    /** The widget knows how to re-render it as an entry of the "⋮" menu. */
+    collapsible: boolean;
+}
+/** One degradation, applied to one entry. */
+export type ToolbarLayoutStep = {
+    kind: 'shrink';
+    id: string;
+} | {
+    kind: 'collapse';
+    id: string;
+};
+/** What the row currently measures, in CSS pixels. */
+export interface ToolbarMetrics {
+    /** Width the entries occupy when nothing has given way yet. */
+    content: number;
+    /** Width they may occupy. `Infinity` when nothing constrains the row. */
+    available: number;
+    /** Width freed by dropping an entry's label, by action id. */
+    label: Readonly<Record<string, number>>;
+    /** Width freed by moving an entry into the menu, by action id. */
+    entry: Readonly<Record<string, number>>;
+    /** What the "⋮" button costs on a row that has none yet. */
+    menuCost: number;
+    /** Whether the row already carries a "⋮" button. */
+    hasMenu: boolean;
+}
+/**
+ * Every degradation available for this row, in the order they must be spent.
+ *
+ * All the shrinks first, then all the collapses; within each phase, the least
+ * important entry first. An entry that can do both appears twice — which is
+ * exactly the arbitration's "icon only BEFORE it is a candidate for the ⋮".
+ */
+export declare function toolbarDegradationSteps(items: readonly ToolbarLayoutItem[]): ToolbarLayoutStep[];
+/**
+ * The shortest prefix of `steps` that brings the row back within `available`.
+ *
+ * Spends steps one at a time, cheapest loss first, and stops the moment the row
+ * fits — a toolbar that collapses more than it must is a toolbar that hides
+ * things for nothing. A step that would free nothing is skipped rather than
+ * spent: dropping a label of zero width, or opening a "⋮" that costs more than
+ * the entry it swallows, is a change with no benefit.
+ *
+ * Returns `[]` when the row already fits, and may return fewer steps than are
+ * needed when the row cannot fit at all — the caller renders what it can and
+ * the row stays one line, which is the whole point.
+ */
+export declare function planToolbarLayout(steps: readonly ToolbarLayoutStep[], metrics: ToolbarMetrics): ToolbarLayoutStep[];

package/dist/_pkgs/affine-shared/services/toolbar-service/layout.js

@@ -0,0 +1,146 @@
+/**
+ * **Priority collapse** — how a contextual toolbar stays on ONE line.
+ *
+ * The PO's arbitration of 02/08/2026 killed the previous answer, which was to
+ * let the toolbar wrap onto a second row: the "⋮" button ended up alone on a
+ * line of its own, and a toolbar whose height changes with the selection is a
+ * toolbar that moves under the cursor. The replacement is the one every desktop
+ * toolbar has used for thirty years — when the row runs out of room, the least
+ * important entries give way, in that order, into the overflow menu that is
+ * already there.
+ *
+ * ## Why the algorithm lives here and not in the widget
+ *
+ * Nothing below touches the DOM. It takes the entries' DECLARED priority and a
+ * handful of measured widths and answers "which entries give way, and how" —
+ * which makes it a pure function the unit suite can pin down entirely, and
+ * leaves the widget with only the two things that genuinely need a browser:
+ * measuring, and re-rendering.
+ *
+ * It also keeps the rule where the rule belongs. `priority` is a field of
+ * {@link ToolbarAction}, so an entry decides its own fate from its own config
+ * file; the widget never learns that a framework exists.
+ *
+ * ## The two ways an entry gives way, in order
+ *
+ * 1. **Icon only.** An entry that renders an icon AND a label drops its label
+ *    first, keeping the label as its tooltip. A wordy entry costs three times
+ *    an icon, and losing the word to a hover is a far smaller loss than losing
+ *    the entry to a menu.
+ * 2. **Into the "⋮" menu.** Only then does the entry leave the row, keeping its
+ *    full label and its behaviour as an entry of the menu.
+ *
+ * Every entry that CAN shrink shrinks before any entry moves — a row of icons
+ * is still a row of things you can click, and a menu is not.
+ *
+ * ## When a plan is worth remaking
+ *
+ * The arithmetic above answers "what should the row look like at this width".
+ * It does NOT answer "is this width worth answering for", and the PO's second
+ * pass of 02/08/2026 is about that second question: during a zoom the room the
+ * row has moves sixty times a second, and a row that replans on every one of
+ * those frames visibly hesitates between several compositions — and, since its
+ * width is what the positioner anchors, between several places.
+ *
+ * Two answers are refused, both of them pure and both of them here:
+ * {@link toolbarRoomChanged} refuses a change too small to mean anything, and
+ * {@link TOOLBAR_SETTLE_DELAY} is how long the room must hold still before the
+ * widget bothers to ask at all.
+ */
+/**
+ * How much the room must move before the row is worth re-composing, in pixels.
+ *
+ * A few pixels, deliberately: less than the narrowest thing the row could give
+ * up, so no real degradation is ever delayed by it, and more than the noise the
+ * measurements carry — a fractional zoom, a rounded rect, a scrollbar coming
+ * and going. Two measurements that differ by a hair are the same measurement,
+ * and treating them as two is how a composition ends up alternating forever.
+ */
+export const TOOLBAR_ROOM_HYSTERESIS = 4;
+/**
+ * How long the room must hold still before the row is replanned, in ms.
+ *
+ * Long enough to bridge the frames of a gesture — a zoom, a pan, a window being
+ * dragged — so the row keeps ONE composition for the whole of it, and short
+ * enough that letting go feels like the row simply followed.
+ */
+export const TOOLBAR_SETTLE_DELAY = 150;
+/**
+ * Whether the room the row has really changed since the plan on screen.
+ *
+ * `Infinity` is a value like any other here: a row nothing has positioned yet
+ * has all the room in the world, and going from that to a finite cap (or back)
+ * is always a change, however large the numbers are.
+ */
+export function toolbarRoomChanged(planned, measured, threshold = TOOLBAR_ROOM_HYSTERESIS) {
+    if (planned === measured)
+        return false;
+    if (!Number.isFinite(planned) || !Number.isFinite(measured))
+        return true;
+    return Math.abs(measured - planned) > threshold;
+}
+/**
+ * Every degradation available for this row, in the order they must be spent.
+ *
+ * All the shrinks first, then all the collapses; within each phase, the least
+ * important entry first. An entry that can do both appears twice — which is
+ * exactly the arbitration's "icon only BEFORE it is a candidate for the ⋮".
+ */
+export function toolbarDegradationSteps(items) {
+    const order = items
+        .map((item, index) => ({ item, index }))
+        // Least important first: by declared priority, then — for the entries that
+        // declared nothing, which is most of them — by reverse rendered order.
+        .sort((a, b) => a.item.priority - b.item.priority || b.index - a.index);
+    return [
+        ...order
+            .filter(({ item }) => item.shrinkable)
+            .map(({ item }) => ({ kind: 'shrink', id: item.id })),
+        ...order
+            .filter(({ item }) => item.collapsible)
+            .map(({ item }) => ({
+            kind: 'collapse',
+            id: item.id,
+        })),
+    ];
+}
+/**
+ * The shortest prefix of `steps` that brings the row back within `available`.
+ *
+ * Spends steps one at a time, cheapest loss first, and stops the moment the row
+ * fits — a toolbar that collapses more than it must is a toolbar that hides
+ * things for nothing. A step that would free nothing is skipped rather than
+ * spent: dropping a label of zero width, or opening a "⋮" that costs more than
+ * the entry it swallows, is a change with no benefit.
+ *
+ * Returns `[]` when the row already fits, and may return fewer steps than are
+ * needed when the row cannot fit at all — the caller renders what it can and
+ * the row stays one line, which is the whole point.
+ */
+export function planToolbarLayout(steps, metrics) {
+    const { available } = metrics;
+    let width = metrics.content;
+    if (width <= available)
+        return [];
+    let hasMenu = metrics.hasMenu;
+    const applied = [];
+    for (const step of steps) {
+        if (width <= available)
+            break;
+        if (step.kind === 'shrink') {
+            const saved = metrics.label[step.id] ?? 0;
+            if (saved <= 0)
+                continue;
+            width -= saved;
+        }
+        else {
+            const saved = (metrics.entry[step.id] ?? 0) - (hasMenu ? 0 : metrics.menuCost);
+            if (saved <= 0)
+                continue;
+            width -= saved;
+            hasMenu = true;
+        }
+        applied.push(step);
+    }
+    return applied;
+}

package/dist/_pkgs/affine-shared/services/translation-service/index.d.ts

@@ -0,0 +1,68 @@
+import type { BlockStdScope } from '../../../std/index.js';
+import type { ExtensionType } from '../../../store/index.js';
+/**
+ * The library holds no prose: every human-readable string it produces —
+ * shortcut labels, role names, validation messages — is an i18n KEY
+ * (`com.labre.wardley.validation.change-arrow-against-evolution`). Historically those
+ * keys never had to be rendered here: `getShortcutManifest` hands them to the
+ * host, which owns the catalogue and the settings panel.
+ *
+ * PF7 is the first library UI that has to SHOW one — a violation bubble names
+ * the rule it reports. This is the seam for it, and nothing more: the host
+ * injects a catalogue, the library asks it for a key. There is no bundled
+ * catalogue, no locale negotiation and no pluralisation. Those belong to the
+ * host, which already runs an i18n stack.
+ *
+ * Mirrors `TelemetryExtension` / `KeymapOverrideExtension`: an optional
+ * host-injected service, absent by default, with a graceful fallback at every
+ * call site (see {@link translateKey}).
+ *
+ * A host builds its catalogue from `getTranslationKeyManifest()`
+ * (`@labre/affine/translations`) — every key the library can ask for, with its
+ * English fallback — rather than chasing call sites. See `./README.md`.
+ */
+export interface TranslationService {
+    /**
+     * Resolve an i18n key. Return `undefined` when the catalogue has no entry,
+     * so the caller can fall back rather than render an empty bubble.
+     */
+    t(key: string): string | undefined;
+    /**
+     * The language the catalogue is currently serving, as a BCP-47 tag
+     * (`'fr'`, `'en-GB'`). Optional, and NOT locale negotiation — the library
+     * still holds no catalogue and still chooses nothing.
+     *
+     * It exists for the one kind of statement the library cannot make without
+     * knowing the language: a suggestion ABOUT WORDS. A naming convention is a
+     * motif in one language (see `ReadingNamingConvention.lang`), and applying an
+     * English motif to a board named in French produces a confident wrong answer
+     * in both directions. The host that owns the catalogue is the only thing here
+     * that knows which language the user is working in; a host that does not say
+     * gets silence rather than a guess.
+     */
+    language?: string;
+}
+/**
+ * The primary subtag of the host's language, lower-cased — `'fr'` for
+ * `'fr-CA'` — or `undefined` when no host said.
+ *
+ * Primary subtag only: a naming motif is a property of a LANGUAGE, and no
+ * framework has a convention that holds in `en-GB` and not in `en-US`.
+ */
+export declare function hostLanguage(std: BlockStdScope): string | undefined;
+export declare const TranslationProvider: import("../../../global/di/types.js").ServiceIdentifier<TranslationService> & (<U extends TranslationService = TranslationService>(variant: import("../../../global/di/types.js").ServiceVariant) => import("../../../global/di/types.js").ServiceIdentifier<U>);
+export declare const TranslationExtension: (service: TranslationService) => ExtensionType;
+/**
+ * Resolve `key`, falling back to `fallback` — which defaults to the key itself.
+ *
+ * Two deliberate cases:
+ *
+ * - **Framework prose** (a rule message, a role name) passes NO fallback. With
+ *   no catalogue registered the raw key is shown. It is ugly, and that is the
+ *   point: the library must never invent the wording of somebody else's rule,
+ *   and a dangling key is a bug the host has to see rather than a sentence we
+ *   made up.
+ * - **Chrome** (the word "Warning" on a severity chip) passes an English
+ *   default, so a standalone playground reads correctly without a catalogue.
+ */
+export declare function translateKey(std: BlockStdScope, key: string, fallback?: string): string;

package/dist/_pkgs/affine-shared/services/translation-service/index.js

@@ -0,0 +1,39 @@
+import { createIdentifier } from '../../../global/di/index.js';
+/**
+ * The primary subtag of the host's language, lower-cased — `'fr'` for
+ * `'fr-CA'` — or `undefined` when no host said.
+ *
+ * Primary subtag only: a naming motif is a property of a LANGUAGE, and no
+ * framework has a convention that holds in `en-GB` and not in `en-US`.
+ */
+export function hostLanguage(std) {
+    const tag = std.getOptional(TranslationProvider)?.language;
+    if (typeof tag !== 'string' || tag.length === 0)
+        return undefined;
+    return tag.split('-')[0].toLowerCase();
+}
+export const TranslationProvider = createIdentifier('AffineTranslationService');
+export const TranslationExtension = (service) => {
+    return {
+        setup: di => {
+            di.override(TranslationProvider, () => service);
+        },
+    };
+};
+/**
+ * Resolve `key`, falling back to `fallback` — which defaults to the key itself.
+ *
+ * Two deliberate cases:
+ *
+ * - **Framework prose** (a rule message, a role name) passes NO fallback. With
+ *   no catalogue registered the raw key is shown. It is ugly, and that is the
+ *   point: the library must never invent the wording of somebody else's rule,
+ *   and a dangling key is a bug the host has to see rather than a sentence we
+ *   made up.
+ * - **Chrome** (the word "Warning" on a severity chip) passes an English
+ *   default, so a standalone playground reads correctly without a catalogue.
+ */
+export function translateKey(std, key, fallback = key) {
+    const resolved = std.getOptional(TranslationProvider)?.t(key);
+    return resolved !== undefined && resolved !== '' ? resolved : fallback;
+}