@formicoidea/labre-core 0.32.0 → 0.33.0

package/dist/_pkgs/std/clipboard/utils.js

@@ -3,7 +3,10 @@
  * Used to embed plain text in the clipboard snapshot wrapper.
  */
 export function escapeHTML(value) {
-    return value.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+    return value
+        .replace(/&/g, '&amp;')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;');
 }
 export function onlyContainImgElement(ast) {
     if (ast.type === 'element') {

package/dist/_pkgs/std/extension/command-registry.d.ts

@@ -12,7 +12,7 @@ import { type ShortcutDescriptor, type ShortcutScope } from './shortcut.js';
  */
 export type ElementCreationSource = 'shortcut' | 'toolbar:general' | 'toolbar:dnd' | 'canvas:drop' | 'canvas:draw' | 'canvas:dbclick' | 'canvas:paste' | 'context-menu' | 'ai' | 'internal' | 'conversation' | 'manually save';
 /**
- * The seven framework modules that own commands. An EXPLICIT list, not a
+ * The eight framework modules that own commands. An EXPLICIT list, not a
  * subset assertion over `OPTIONAL_BLOCKS`: that list mixes frameworks with
  * plain blocks. `packages/affine/all/src/frameworks.ts` asserts that every id
  * here is a real flag key (`satisfies readonly OptionalBlock[]`).
@@ -20,7 +20,7 @@ export type ElementCreationSource = 'shortcut' | 'toolbar:general' | 'toolbar:dn
  * `ddd-aggregate` is deliberately absent: it ships DDD *templates* only — no
  * senior button, no commands — so it is a packaging bundle, not a framework.
  */
-export declare const FRAMEWORK_IDS: readonly ["wardley", "edgy", "cynefin-estuarine", "bpmn", "ddd-event-storming", "ddd-core-domain", "ddd-context-map"];
+export declare const FRAMEWORK_IDS: readonly ["wardley", "edgy", "cynefin-estuarine", "bpmn", "c4", "ddd-event-storming", "ddd-core-domain", "ddd-context-map"];
 export type FrameworkId = (typeof FRAMEWORK_IDS)[number];
 export type CommandOwner = 'core' | FrameworkId;
 /**
@@ -204,6 +204,13 @@ export interface FrameworkDescriptor {
     id: FrameworkId;
     /** Replaces the raw English `SeniorTool.name`. */
     labelKey: string;
+    /**
+     * The English wording behind {@link labelKey} — what a standalone editor
+     * shows and what every restatement of the name (senior button, tooltip)
+     * must agree with. Carried HERE so the manifest knows the fallback and the
+     * drift check can hold the restatements to it.
+     */
+    labelFallback: string;
     iconKey: string;
     order?: number;
     /** First keystroke of this framework's chords — allocated, not ad hoc. */
@@ -248,6 +255,37 @@ export type CommandTelemetryReporter = (report: {
     invocation: CommandInvocation;
 }) => void;
 export declare const CommandTelemetryIdentifier: import("../../global/di/types.js").ServiceIdentifier<CommandTelemetryReporter> & (<U extends CommandTelemetryReporter = CommandTelemetryReporter>(variant: import("../../global/di/types.js").ServiceVariant) => import("../../global/di/types.js").ServiceIdentifier<U>);
+/** What a {@link CommandUsageStore} knows about one command. */
+export interface CommandUsageStats {
+    count: number;
+    lastUsedAt: number;
+}
+/**
+ * Per-user recency and frequency, measured at the same bottleneck telemetry is
+ * emitted from — and deliberately NOT the same thing.
+ *
+ * Telemetry is analytics: it leaves for a product dashboard, it only covers
+ * commands that declare a `telemetry` field, and no in-editor decision may
+ * depend on it. Usage is local state read back BY the editor: PF6 shows only
+ * thirteen of a framework's commands in the senior sub-menu once the framework
+ * has more than fourteen artefacts, ranked as "seven most-recent + six
+ * most-used" (PO re-arbitration of 2026-08-28, superseding the 4 + 3 of
+ * 2026-08-26). That ranking needs a measure for EVERY command — a `core` action, a
+ * self-emitting one, one nobody ever thought to instrument — so the record call
+ * sits outside the telemetry condition and stays there.
+ *
+ * ADR 0008 listed this as an open question ("needs a host-side usage store; the
+ * registry only needs to accept an injected comparator"). This identifier is
+ * the measurement half of that answer; the selection half is
+ * {@link selectSeniorMenuCommands}.
+ */
+export interface CommandUsageStore {
+    /** One invocation happened. Called by {@link runCommand}, best-effort. */
+    record(command: AnyCommandDescriptor, invocation: CommandInvocation): void;
+    /** `undefined` when the command was never invoked by this user. */
+    statsOf(commandId: string): CommandUsageStats | undefined;
+}
+export declare const CommandUsageIdentifier: import("../../global/di/types.js").ServiceIdentifier<CommandUsageStore> & (<U extends CommandUsageStore = CommandUsageStore>(variant: import("../../global/di/types.js").ServiceVariant) => import("../../global/di/types.js").ServiceIdentifier<U>);
 /**
  * Mirrors `GfxSelectionManager.editing` without importing `@labre/std/gfx`
  * (which would close an import cycle through `extension/`): the gfx manager
@@ -272,9 +310,9 @@ export declare const isEditingOnCanvas: (std: BlockStdScope) => boolean;
 export declare function isCommandAvailable(std: BlockStdScope, command: AnyCommandDescriptor): boolean;
 /**
  * THE bottleneck: the one place a command runs, and therefore the one place
- * its telemetry is emitted. Every surface (sub-menu, shortcut, palette,
- * sidepanel, agent) goes through here, which is what removes the per-menu
- * `track()` duplicates.
+ * its telemetry is emitted and its usage measured. Every surface (sub-menu,
+ * shortcut, palette, sidepanel, agent) goes through here, which is what removes
+ * the per-menu `track()` duplicates.
  */
 export declare function runCommand(std: BlockStdScope, command: AnyCommandDescriptor, invocation: CommandInvocation, params?: unknown): void;
 /**
@@ -317,5 +355,121 @@ export declare function getRegisteredCommands(std: BlockStdScope): AnyCommandDes
  * button list anywhere.
  */
 export declare function getCommandsForSurface(std: BlockStdScope, owner: CommandOwner, surface: CommandSurface): AnyCommandDescriptor[];
+/**
+ * The senior sub-menu's hard cap: 14 buttons in one row of the popover. The
+ * registry test asserts no owner DECLARES more than this; the ranking below is
+ * what happens when an owner's whole catalogue outgrows it.
+ */
+export declare const SENIOR_MENU_CAP = 14;
+/**
+ * How many buttons survive once an owner overflows: {@link MENU_RECENT_SLOTS}
+ * by recency plus {@link MENU_USED_SLOTS} by frequency — thirteen (PO
+ * re-arbitration of 2026-08-28, superseding the 4 + 3 of 2026-08-26).
+ *
+ * Thirteen and not fourteen because the permanent "More artefacts…" button is
+ * the fourteenth: an overflowed sub-menu therefore renders exactly the cap, and
+ * the row a user meets past the cap is as wide as the one they meet below it.
+ */
+export declare const SENIOR_MENU_RANKED_SLOTS: number;
+/**
+ * How many rows the catalogue sidepanel's "Recent & frequent" head section
+ * holds: {@link HEAD_RECENT_SLOTS} + {@link HEAD_USED_SLOTS} = seven.
+ *
+ * Deliberately NOT {@link SENIOR_MENU_RANKED_SLOTS}, and this is the third
+ * decision of 2026-08-28 (architect's ruling on review of the two PO ones). The
+ * sub-menu's thirteen is argued from ITS geometry — a horizontal row of ~24px
+ * icon buttons, thirteen of them plus the More button making up the fourteen
+ * cap. None of that transfers to a vertical list of 44px rows in a panel
+ * `min(320px, 85vw)` wide: thirteen of those is ~604px of head section, which
+ * on a 13" laptop is the entire first screen, every row of it a duplicate of a
+ * row filed below, pushing the categories — the panel's actual information
+ * architecture — wholly under the fold. Worst for exactly the power user the
+ * section exists to serve.
+ *
+ * So the two surfaces share the ARBITRATION and not the MAGNITUDE: one
+ * algorithm, two parameterisations. Seven keeps the size the PO recette of
+ * 27/08/2026 signed off on, and the 4 + 3 split keeps both halves of a section
+ * labelled "Recent & frequent" — a plain `.slice(0, 7)` of the sub-menu's pick
+ * would have returned seven recency picks and zero frequency ones, quietly
+ * deleting the "& frequent" half.
+ */
+export declare const CATALOGUE_HEAD_RANKED_SLOTS: number;
+/**
+ * Which of an owner's commands the senior sub-menu actually shows.
+ *
+ * Pure — no `std`, no DOM, no store — because this is the arbitration between
+ * a framework's whole toolbox and fourteen buttons, and an arbitration nobody
+ * can run in a unit test is a design review in disguise (`docs/adr/0008`,
+ * amendment of 2026-08-26).
+ *
+ * Below the cap nothing is arbitrated: the sub-menu IS the framework's
+ * `'senior-menu'` surface, authored order and all. Past it the sub-menu becomes
+ * a shortcut to the thirteen commands THIS user reaches for, beside one button
+ * to the catalogue sidepanel where the rest live.
+ *
+ * **Eligibility is declared, never earned** (PO ruling of 2026-08-28). What
+ * gets ranked is the `'senior-menu'` surface — the ≤14 its author nominated —
+ * and NOT the whole catalogue. The trigger still reads the catalogue (an owner
+ * overflows when its total toolbox outgrows the cap), but a command that
+ * deliberately declines the sub-menu stays out of it however often it is
+ * invoked. `bpmn.exportXml` is the case that made the rule: its subject is the
+ * whole BOARD, it lives in the pool's "⋮" and in the catalogue, and usage alone
+ * used to drag it into a row of things you DRAW — where "Export BPMN" answers
+ * no question a user asked. A surface a command declines is a statement about
+ * where it belongs, not a default to be out-voted.
+ *
+ * The thirteen are chosen on two axes because one is not enough — frequency
+ * alone never surfaces what the user picked up yesterday, recency alone
+ * reshuffles every click. They are then laid out in **authored order**, not in
+ * rank order: a menu whose buttons swap places under the cursor is the dark
+ * pattern this whole feature exists to avoid, so what the ranking decides is
+ * membership, never position.
+ *
+ * With no usage recorded at all, both axes collapse to authored order and the
+ * result is the first thirteen of the nominated list — a deterministic cold
+ * start, not an empty menu.
+ *
+ * @param menu the owner's `'senior-menu'` commands, already order-sorted. It is
+ *   both the pool the ranking draws membership from and the authored order the
+ *   survivors are laid back out in.
+ * @param catalogue the owner's whole `'catalogue'` surface, already
+ *   order-sorted. Read only for its length, to decide whether the owner
+ *   overflows at all; it contributes no candidate.
+ * @param statsOf per-user measure; `undefined` for a command never invoked
+ */
+export declare function selectSeniorMenuCommands(menu: AnyCommandDescriptor[], catalogue: AnyCommandDescriptor[], statsOf: (id: string) => CommandUsageStats | undefined): {
+    commands: AnyCommandDescriptor[];
+    overflow: boolean;
+};
+/**
+ * The commands a user actually reaches for, for surfaces that lead with them —
+ * the catalogue sidepanel's "recent & frequent" head section (PO recette,
+ * 27/08/2026).
+ *
+ * Same arbitration as the senior sub-menu ({@link pickByUsage}) — one ranking,
+ * two consumers, never two opinions — with four deliberate differences:
+ *
+ * - it seats {@link CATALOGUE_HEAD_RANKED_SLOTS} (4 recent + 3 used), not the
+ *   sub-menu's thirteen. The two surfaces share the arbitration and not the
+ *   magnitude: see {@link CATALOGUE_HEAD_RANKED_SLOTS} for why thirteen 44px
+ *   rows in a 320px panel would bury the categories under the fold.
+ * - it ranks the CATALOGUE surface, and keeps doing so after the eligibility
+ *   ruling of 2026-08-28 narrowed the sub-menu to `'senior-menu'` declarers.
+ *   That ruling is about the sub-menu, which is a row of things you DRAW; the
+ *   sidepanel is the full-catalogue surface, the one place every command of a
+ *   framework is reachable, so a catalogue-only command like `bpmn.exportXml`
+ *   heading this section is the section working — "here is what you reach for"
+ *   over a panel that lists everything, not a board action smuggled into a
+ *   palette. Passing the menu surface here would hide a user's own habits from
+ *   the very panel built to show them.
+ * - only commands that CARRY a measure are returned. The sub-menu backfills
+ *   with authored order because it must always show something; a "recently
+ *   used" section padded with the never-used would be a label that lies, so
+ *   with no usage at all this returns `[]` and the section is simply absent.
+ * - the PICK order is kept (the recency ranks, then the frequency additions),
+ *   not re-sorted by authored order: the section's whole message is "yours,
+ *   latest first", and it only recomposes when the panel reopens.
+ */
+export declare function rankCommandsByUsage(catalogue: AnyCommandDescriptor[], statsOf: (id: string) => CommandUsageStats | undefined): AnyCommandDescriptor[];
 /** Resolve an `iconKey` through the registered icon tables. */
 export declare function getCommandIcon(std: BlockStdScope, iconKey: string | undefined): TemplateResult | undefined;

package/dist/_pkgs/std/extension/command-registry.js

@@ -2,7 +2,7 @@ import { createIdentifier } from '../../global/di/index.js';
 import { SurfaceSelection } from '../selection/index.js';
 import { ShortcutExtension, } from './shortcut.js';
 /**
- * The seven framework modules that own commands. An EXPLICIT list, not a
+ * The eight framework modules that own commands. An EXPLICIT list, not a
  * subset assertion over `OPTIONAL_BLOCKS`: that list mixes frameworks with
  * plain blocks. `packages/affine/all/src/frameworks.ts` asserts that every id
  * here is a real flag key (`satisfies readonly OptionalBlock[]`).
@@ -15,6 +15,7 @@ export const FRAMEWORK_IDS = [
     'edgy',
     'cynefin-estuarine',
     'bpmn',
+    'c4',
     'ddd-event-storming',
     'ddd-core-domain',
     'ddd-context-map',
@@ -24,6 +25,7 @@ export const CommandDescriptorIdentifier = createIdentifier('CommandDescriptor')
 /** Multi-instance: one `iconKey → template` table per contributing package. */
 export const CommandIconsIdentifier = createIdentifier('CommandIcons');
 export const CommandTelemetryIdentifier = createIdentifier('CommandTelemetry');
+export const CommandUsageIdentifier = createIdentifier('CommandUsage');
 const surfaceSelections = (std) => std.selection.filter(SurfaceSelection);
 /**
  * Mirrors `GfxSelectionManager.editing` without importing `@labre/std/gfx`
@@ -60,14 +62,17 @@ export function isCommandAvailable(std, command) {
 }
 /**
  * THE bottleneck: the one place a command runs, and therefore the one place
- * its telemetry is emitted. Every surface (sub-menu, shortcut, palette,
- * sidepanel, agent) goes through here, which is what removes the per-menu
- * `track()` duplicates.
+ * its telemetry is emitted and its usage measured. Every surface (sub-menu,
+ * shortcut, palette, sidepanel, agent) goes through here, which is what removes
+ * the per-menu `track()` duplicates.
  */
 export function runCommand(std, command, invocation, params) {
     const result = command.run(std, invocation, params);
     if (result instanceof Promise)
         result.catch(console.error);
+    // Before the telemetry gate on purpose: usage is measured for EVERY command,
+    // including the ones with no `telemetry` field and the self-emitting ones.
+    std.getOptional(CommandUsageIdentifier)?.record(command, invocation);
     if (!command.telemetry)
         return;
     std.getOptional(CommandTelemetryIdentifier)?.({ std, command, invocation });
@@ -220,6 +225,199 @@ export function getCommandsForSurface(std, owner, surface) {
         .filter(c => c.owner === owner && c.surfaces.includes(surface))
         .sort((a, b) => (a.order ?? 0) - (b.order ?? 0));
 }
+/**
+ * The senior sub-menu's hard cap: 14 buttons in one row of the popover. The
+ * registry test asserts no owner DECLARES more than this; the ranking below is
+ * what happens when an owner's whole catalogue outgrows it.
+ */
+export const SENIOR_MENU_CAP = 14;
+const MENU_RECENT_SLOTS = 7;
+const MENU_USED_SLOTS = 6;
+/**
+ * How many buttons survive once an owner overflows: {@link MENU_RECENT_SLOTS}
+ * by recency plus {@link MENU_USED_SLOTS} by frequency — thirteen (PO
+ * re-arbitration of 2026-08-28, superseding the 4 + 3 of 2026-08-26).
+ *
+ * Thirteen and not fourteen because the permanent "More artefacts…" button is
+ * the fourteenth: an overflowed sub-menu therefore renders exactly the cap, and
+ * the row a user meets past the cap is as wide as the one they meet below it.
+ */
+export const SENIOR_MENU_RANKED_SLOTS = MENU_RECENT_SLOTS + MENU_USED_SLOTS;
+const HEAD_RECENT_SLOTS = 4;
+const HEAD_USED_SLOTS = 3;
+/**
+ * How many rows the catalogue sidepanel's "Recent & frequent" head section
+ * holds: {@link HEAD_RECENT_SLOTS} + {@link HEAD_USED_SLOTS} = seven.
+ *
+ * Deliberately NOT {@link SENIOR_MENU_RANKED_SLOTS}, and this is the third
+ * decision of 2026-08-28 (architect's ruling on review of the two PO ones). The
+ * sub-menu's thirteen is argued from ITS geometry — a horizontal row of ~24px
+ * icon buttons, thirteen of them plus the More button making up the fourteen
+ * cap. None of that transfers to a vertical list of 44px rows in a panel
+ * `min(320px, 85vw)` wide: thirteen of those is ~604px of head section, which
+ * on a 13" laptop is the entire first screen, every row of it a duplicate of a
+ * row filed below, pushing the categories — the panel's actual information
+ * architecture — wholly under the fold. Worst for exactly the power user the
+ * section exists to serve.
+ *
+ * So the two surfaces share the ARBITRATION and not the MAGNITUDE: one
+ * algorithm, two parameterisations. Seven keeps the size the PO recette of
+ * 27/08/2026 signed off on, and the 4 + 3 split keeps both halves of a section
+ * labelled "Recent & frequent" — a plain `.slice(0, 7)` of the sub-menu's pick
+ * would have returned seven recency picks and zero frequency ones, quietly
+ * deleting the "& frequent" half.
+ */
+export const CATALOGUE_HEAD_RANKED_SLOTS = HEAD_RECENT_SLOTS + HEAD_USED_SLOTS;
+/**
+ * Which of an owner's commands the senior sub-menu actually shows.
+ *
+ * Pure — no `std`, no DOM, no store — because this is the arbitration between
+ * a framework's whole toolbox and fourteen buttons, and an arbitration nobody
+ * can run in a unit test is a design review in disguise (`docs/adr/0008`,
+ * amendment of 2026-08-26).
+ *
+ * Below the cap nothing is arbitrated: the sub-menu IS the framework's
+ * `'senior-menu'` surface, authored order and all. Past it the sub-menu becomes
+ * a shortcut to the thirteen commands THIS user reaches for, beside one button
+ * to the catalogue sidepanel where the rest live.
+ *
+ * **Eligibility is declared, never earned** (PO ruling of 2026-08-28). What
+ * gets ranked is the `'senior-menu'` surface — the ≤14 its author nominated —
+ * and NOT the whole catalogue. The trigger still reads the catalogue (an owner
+ * overflows when its total toolbox outgrows the cap), but a command that
+ * deliberately declines the sub-menu stays out of it however often it is
+ * invoked. `bpmn.exportXml` is the case that made the rule: its subject is the
+ * whole BOARD, it lives in the pool's "⋮" and in the catalogue, and usage alone
+ * used to drag it into a row of things you DRAW — where "Export BPMN" answers
+ * no question a user asked. A surface a command declines is a statement about
+ * where it belongs, not a default to be out-voted.
+ *
+ * The thirteen are chosen on two axes because one is not enough — frequency
+ * alone never surfaces what the user picked up yesterday, recency alone
+ * reshuffles every click. They are then laid out in **authored order**, not in
+ * rank order: a menu whose buttons swap places under the cursor is the dark
+ * pattern this whole feature exists to avoid, so what the ranking decides is
+ * membership, never position.
+ *
+ * With no usage recorded at all, both axes collapse to authored order and the
+ * result is the first thirteen of the nominated list — a deterministic cold
+ * start, not an empty menu.
+ *
+ * @param menu the owner's `'senior-menu'` commands, already order-sorted. It is
+ *   both the pool the ranking draws membership from and the authored order the
+ *   survivors are laid back out in.
+ * @param catalogue the owner's whole `'catalogue'` surface, already
+ *   order-sorted. Read only for its length, to decide whether the owner
+ *   overflows at all; it contributes no candidate.
+ * @param statsOf per-user measure; `undefined` for a command never invoked
+ */
+export function selectSeniorMenuCommands(menu, catalogue, statsOf) {
+    if (catalogue.length <= SENIOR_MENU_CAP) {
+        return { commands: menu, overflow: false };
+    }
+    const authored = new Map(menu.map((command, index) => [command, index]));
+    const order = (command) => authored.get(command) ?? 0;
+    // (7, 6): thirteen icon buttons, plus the "More artefacts…" one, is the cap.
+    const { commands } = pickByUsage(menu, statsOf, MENU_RECENT_SLOTS, MENU_USED_SLOTS);
+    return {
+        commands: commands.sort((a, b) => order(a) - order(b)),
+        overflow: true,
+    };
+}
+/**
+ * The shared arbitration, over whatever pool its caller hands it: `recentSlots`
+ * by recency plus `usedSlots` by frequency, deduplicated.
+ *
+ * The two slot counts are PARAMETERS rather than constants because the two
+ * consumers share this ranking and not its magnitude — the sub-menu passes
+ * (7, 6) for a row of icon buttons, the sidepanel head (4, 3) for a vertical
+ * list of 44px rows. One arbitration, two parameterisations, still never two
+ * opinions.
+ *
+ * Recency goes FIRST since the PO's re-arbitration of 2026-08-28 (it was 4
+ * most-used + 3 most-recent): what a user reached for this morning is what they
+ * are still working on, and a row that leads with the all-time workhorses is a
+ * row that takes weeks to notice a new habit. So a command that tops BOTH axes
+ * consumes a RECENT slot, and the most-used slot it would have taken goes to
+ * the next candidate down the frequency ranking — which is what the backfill
+ * loop below does by walking `mostUsed` whole rather than only its head.
+ *
+ * Returned in PICK order (the recency ranks first, the frequency additions
+ * after); each consumer imposes its own display order. The `stats` map is
+ * returned with them so a consumer that filters on "was this ever measured?"
+ * does not ask the store a second time — see {@link rankCommandsByUsage}.
+ */
+function pickByUsage(pool, statsOf, recentSlots, usedSlots) {
+    const authored = new Map(pool.map((command, index) => [command, index]));
+    const order = (command) => authored.get(command) ?? 0;
+    // One read per command per selection: the store answers from storage, and the
+    // two axes would otherwise ask it the same question twice.
+    const stats = new Map(pool.map(c => [c, statsOf(c.id)]));
+    const rankBy = (primary, secondary) => [...pool].sort((a, b) => {
+        const left = stats.get(a);
+        const right = stats.get(b);
+        // A command nobody ever invoked ranks after every command somebody did,
+        // on either axis — it has no measure, not a low one.
+        if (!left || !right) {
+            return left ? -1 : right ? 1 : order(a) - order(b);
+        }
+        return (primary(right) - primary(left) ||
+            secondary(right) - secondary(left) ||
+            order(a) - order(b));
+    });
+    const mostUsed = rankBy(used => used.count, used => used.lastUsedAt);
+    const mostRecent = rankBy(used => used.lastUsedAt, used => used.count);
+    const total = recentSlots + usedSlots;
+    const chosen = new Set();
+    for (const command of mostRecent.slice(0, recentSlots)) {
+        chosen.add(command);
+    }
+    // The `usedSlots` remaining seats, from the frequency ranking: walking it
+    // whole rather than only its head is what makes a double pick free its
+    // most-used slot for the next candidate instead of wasting it.
+    for (const command of mostUsed) {
+        if (chosen.size >= total)
+            break;
+        chosen.add(command);
+    }
+    return { commands: [...chosen].slice(0, total), stats };
+}
+/**
+ * The commands a user actually reaches for, for surfaces that lead with them —
+ * the catalogue sidepanel's "recent & frequent" head section (PO recette,
+ * 27/08/2026).
+ *
+ * Same arbitration as the senior sub-menu ({@link pickByUsage}) — one ranking,
+ * two consumers, never two opinions — with four deliberate differences:
+ *
+ * - it seats {@link CATALOGUE_HEAD_RANKED_SLOTS} (4 recent + 3 used), not the
+ *   sub-menu's thirteen. The two surfaces share the arbitration and not the
+ *   magnitude: see {@link CATALOGUE_HEAD_RANKED_SLOTS} for why thirteen 44px
+ *   rows in a 320px panel would bury the categories under the fold.
+ * - it ranks the CATALOGUE surface, and keeps doing so after the eligibility
+ *   ruling of 2026-08-28 narrowed the sub-menu to `'senior-menu'` declarers.
+ *   That ruling is about the sub-menu, which is a row of things you DRAW; the
+ *   sidepanel is the full-catalogue surface, the one place every command of a
+ *   framework is reachable, so a catalogue-only command like `bpmn.exportXml`
+ *   heading this section is the section working — "here is what you reach for"
+ *   over a panel that lists everything, not a board action smuggled into a
+ *   palette. Passing the menu surface here would hide a user's own habits from
+ *   the very panel built to show them.
+ * - only commands that CARRY a measure are returned. The sub-menu backfills
+ *   with authored order because it must always show something; a "recently
+ *   used" section padded with the never-used would be a label that lies, so
+ *   with no usage at all this returns `[]` and the section is simply absent.
+ * - the PICK order is kept (the recency ranks, then the frequency additions),
+ *   not re-sorted by authored order: the section's whole message is "yours,
+ *   latest first", and it only recomposes when the panel reopens.
+ */
+export function rankCommandsByUsage(catalogue, statsOf) {
+    const { commands, stats } = pickByUsage(catalogue, statsOf, HEAD_RECENT_SLOTS, HEAD_USED_SLOTS);
+    // Through the map the ranking already built, not a second round of store
+    // reads: "one read per command per selection" is a promise this function used
+    // to break once per returned row.
+    return commands.filter(command => stats.get(command) !== undefined);
+}
 /** Resolve an `iconKey` through the registered icon tables. */
 export function getCommandIcon(std, iconKey) {
     if (!iconKey)

package/dist/_pkgs/std/extension/shortcut.js

@@ -60,7 +60,8 @@ const LEGACY_MODIFIER = /^(mod|cmd|meta|ctrl|control|alt|shift)$/i;
  * folded: they are valid chord prefixes.
  */
 export function normalizeLegacyCombo(keys) {
-    if (keys.length > 1 && keys.slice(0, -1).every(k => LEGACY_MODIFIER.test(k))) {
+    if (keys.length > 1 &&
+        keys.slice(0, -1).every(k => LEGACY_MODIFIER.test(k))) {
         return [keys.join('-')];
     }
     return keys;

package/dist/_pkgs/std/gfx/grid.js

@@ -1,5 +1,5 @@
 import { DisposableGroup } from '../../global/disposable/index.js';
-import { Bound, getBoundWithRotation, intersects, } from '../../global/gfx/index.js';
+import { Bound, getBoundWithRotation, intersects } from '../../global/gfx/index.js';
 import { compare } from '../utils/layer.js';
 import { GfxExtension } from './extension.js';
 import { GfxBlockElementModel } from './model/gfx-block-model.js';

package/dist/_pkgs/std/gfx/index.d.ts

@@ -14,7 +14,7 @@ export { gfxGroupCompatibleSymbol, isGfxGroupCompatibleModel, } from './model/ba
 export { GfxBlockElementModel, type GfxCommonBlockProps, GfxCompatibleBlockModel as GfxCompatible, type GfxCompatibleProps, } from './model/gfx-block-model.js';
 export { type GfxModel, isPrimitiveModel } from './model/model.js';
 export { convert, convertProps, derive, field, getDerivedProps, getFieldPropsSet, getLocalPropsSet, initializeObservers, initializeWatchers, local, observe, updateDerivedProps, watch, } from './model/surface/decorators/index.js';
-export { type BaseElementProps, GfxGroupLikeElementModel, GfxPrimitiveElementModel, type SerializedElement, type ValidationException, } from './model/surface/element-model.js';
+export { type BaseElementProps, type ForeignInterchange, type InterchangeScope, GfxGroupLikeElementModel, GfxPrimitiveElementModel, type SerializedElement, type ValidationException, } from './model/surface/element-model.js';
 export { GfxLocalElementModel, prop, } from './model/surface/local-element-model.js';
 export { collectPivotOccurrences, isPivotBound, type PivotBoundElement, type PivotOccurrence, } from './model/surface/pivot.js';
 export { type EdgeDirectionDef, findRoleDef, isTypedEdgeRole, type RoleDef, type RoleDefs, type RoleId, roleIsA, type RoleKind, RoleVocabularyExtension, RoleVocabularyIdentifier, } from './model/surface/role.js';