@formicoidea/labre-core 0.31.0 → 0.33.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
@@ -33,11 +34,264 @@ export type BlockLifecycleEvents = {
  * manipulated ('background:classic', 'node:market', 'connector:link'…).
  */
 export interface FrameworkElementEvent extends TelemetryEvent {
-    framework: 'wardley' | 'edgy' | 'cynefin' | 'bpmn' | 'event-storming' | 'core-domain' | 'context-map';
+    framework: 'wardley' | 'edgy' | 'cynefin' | 'bpmn' | 'c4' | '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;
+}
+/**
+ * A framework element became a NEARBY kind of itself — a task said more
+ * precisely as a user task, a start event as a timer start — from its own
+ * contextual toolbar, in one atomic write.
+ *
+ * **A new event name, for the reason {@link FrameworkPromotionEvent} gives.**
+ * ADR 0003 § 2 defines the creation event as UI intent emitted at INSERTION
+ * sites, and a morph inserts nothing: no element is created, destroyed or
+ * swapped, no id changes, no geometry moves and no connector is re-pointed.
+ * Reusing `FrameworkElementAdded` would count a drawn-then-refined artefact
+ * twice and inflate "elements added per framework" permanently.
+ *
+ * Worth measuring on its own, too. The set of reachable kinds is DATA a
+ * framework declares by hand, and the only evidence that a declared family is
+ * the right family is how often it is actually crossed — a pair nobody ever
+ * morphs between did not need to be offered, and a morph users reach for
+ * constantly says the palette led them to the wrong artefact first.
+ *
+ * Ids only: the two roles, and their framework. Never a kind's board content,
+ * never the element ids, never the label anybody typed.
+ */
+export interface FrameworkElementMorphedEvent extends TelemetryEvent {
+    page?: 'whiteboard editor';
+    /**
+     * Owning framework — the declaration's own wire key, matching what
+     * `reportCommandTelemetry` sends for that framework's commands.
+     *
+     * OPTIONAL for the same reason it is on {@link FrameworkPromotionEvent}: the
+     * capability is generic, and an element type may one day declare a morph
+     * without belonging to a framework the union names. Absent rather than
+     * `'unknown'`, per the repo convention.
+     */
+    framework?: FrameworkId;
+    /** Role id the selection carried, when they all carried the same one. */
+    fromRole?: string;
+    /** Role id it now carries. */
+    toRole?: string;
+    /** How many elements the single gesture actually rewrote. */
+    elementCount: number;
+}
+/**
+ * A framework VIEW was told which level it draws — a C4 board set to Context,
+ * Container or Component, or put back to a free sketch.
+ *
+ * **A new event name, for the reason {@link FrameworkPromotionEvent} gives.**
+ * Nothing is inserted, nothing is morphed and no level of requirement changes:
+ * the author is stating what the sheet IS, which is a fact none of the existing
+ * events describes. Reusing one of them would corrupt the funnel it belongs to.
+ *
+ * Worth measuring on its own, and for the same reason a profile change is: this
+ * is an OPTIONAL declaration nothing forces, so how often it is made is the only
+ * evidence that asking for it was worth the toolbar entry — and a level users
+ * set and then clear is a rule pack that argued with a drawing they meant.
+ *
+ * Ids only: the framework and the level's own closed vocabulary. Never the
+ * board's title, never what is drawn on it.
+ */
+export interface FrameworkViewLevelEvent extends TelemetryEvent {
+    page?: 'whiteboard editor';
+    /** Owning framework of the view, e.g. `c4`. */
+    framework: FrameworkId;
+    /**
+     * The level now in force, from the framework's own closed vocabulary —
+     * `'none'` when the view has been put back to declaring nothing, which is a
+     * value the dashboard needs as much as the others.
+     */
+    level: string;
+    /** The one it replaces, when the view declared one. */
+    previousLevel?: string;
+}
 export type FrameworkDiagramEvents = {
     FrameworkElementAdded: FrameworkElementEvent;
     FrameworkToolPicked: FrameworkElementEvent;
     FrameworkLegendCreated: FrameworkElementEvent;
+    FrameworkElementPromoted: FrameworkPromotionEvent;
+    FrameworkElementMorphed: FrameworkElementMorphedEvent;
+    FrameworkViewLevelSet: FrameworkViewLevelEvent;
+    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;
+}