@formicoidea/labre-core 0.32.0 → 0.34.1

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;
 /**
@@ -287,6 +325,42 @@ export declare function runCommand(std: BlockStdScope, command: AnyCommandDescri
  * verbatim, which is what keeps hosts' persisted v0.29 override tables valid.
  */
 export declare function toShortcutDescriptor(command: AnyCommandDescriptor): ShortcutDescriptor;
+/**
+ * The DATA-ONLY shortcut projection: what a host's Settings › Shortcuts pane
+ * reads to draw a row, and nothing else. No `handler`, no `run`, no `params` —
+ * so a module holding these entries carries no reference to the action graph
+ * behind the command and can be published on its own subpath (each framework
+ * bundle's `./commands-manifest`).
+ *
+ * It is the SIX fields the panel needs. `labelFallback` is one of them and that
+ * is deliberate: the projection used to drop it, which left a host with no
+ * catalogue rendering raw i18n keys for the rows it could not translate, and
+ * forced every host to re-project from the main entry to recover a wording the
+ * library already knew.
+ *
+ * `owner` is a {@link CommandOwner} rather than `ShortcutDescriptor`'s open
+ * `string`: the panel groups by owner, and the closed union is what makes that
+ * grouping exhaustive host-side.
+ */
+export interface ShortcutManifestEntry {
+    id: string;
+    labelKey: string;
+    /** English default behind {@link labelKey}; see {@link CommandDescriptor.labelFallback}. */
+    labelFallback?: string;
+    defaultKeys: {
+        mac: string[];
+        other: string[];
+    };
+    scope: ShortcutScope;
+    owner: CommandOwner;
+}
+/**
+ * The third permanent projection out of {@link CommandDescriptor}, beside
+ * {@link toShortcutDescriptor} and {@link toCommandManifestEntry}. TOTAL for
+ * the same reason the shortcut descriptor is: a keyless command still yields a
+ * row, so Settings › Shortcuts can bind it.
+ */
+export declare function toShortcutManifestEntry(command: AnyCommandDescriptor): ShortcutManifestEntry;
 /**
  * Project a command's zod parameter contract onto the serializable seam, so the
  * `'agent'` surface is usable end to end: without it an agent reading the
@@ -317,5 +391,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 });
@@ -102,6 +107,22 @@ export function toShortcutDescriptor(command) {
         },
     };
 }
+/**
+ * The third permanent projection out of {@link CommandDescriptor}, beside
+ * {@link toShortcutDescriptor} and {@link toCommandManifestEntry}. TOTAL for
+ * the same reason the shortcut descriptor is: a keyless command still yields a
+ * row, so Settings › Shortcuts can bind it.
+ */
+export function toShortcutManifestEntry(command) {
+    return {
+        id: command.id,
+        labelKey: command.labelKey,
+        labelFallback: command.labelFallback,
+        defaultKeys: command.defaultKeys,
+        scope: command.scope,
+        owner: command.owner,
+    };
+}
 const zodDef = (schema) => schema?._def ?? {};
 const ZOD_KIND = {
     ZodString: 'string',
@@ -220,6 +241,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/extension/translation-manifest.d.ts

@@ -12,7 +12,17 @@ import { type AnyCommandDescriptor } from './command-registry.js';
  * exactly the composition the command registry already does (see
  * `packages/affine/all/src/commands.ts` and `scripts/build-bundles.mjs`).
  */
-export type TranslationKeySource = 'command' | 'framework' | 'role' | 'background' | 'rule' | 'nudge' | 'profile' | 'audit-criterion' | 'reading' | 'chrome';
+export type TranslationKeySource = 'command' | 'framework' | 'role' | 'background' | 'rule' | 'nudge' | 'profile' | 'audit-criterion' | 'reading'
+/**
+ * The words a framework WRITES ONTO THE CANVAS when an artefact is placed —
+ * the "Task" a fresh BPMN task is captioned with, the "People" under an EDGY
+ * person. Document content and not chrome, which is why they are a source of
+ * their own: they are resolved ONCE, at placement, and what lands in the
+ * document is a string the author then owns and edits. Changing the
+ * catalogue afterwards renames nothing, exactly as renaming a shape by hand
+ * would not.
+ */
+ | 'seed' | 'chrome';
 export interface TranslationKeyManifestEntry {
     key: string;
     /**
@@ -41,6 +51,41 @@ export declare function collectTranslationKeys(source: TranslationKeySource, val
  * mean walking zod internals.
  */
 export declare function commandTranslationEntries(commands: readonly AnyCommandDescriptor[]): TranslationKeyManifestEntry[];
+/** The i18n key prefix every artefact-catalogue group header is looked up under. */
+export declare const CATALOGUE_CATEGORY_KEY_PREFIX = "com.labre.catalogue.category.";
+/**
+ * The English default for a category header, derived from the category id.
+ *
+ * `'backgrounds'` → `'Backgrounds'`, `'value-flow'` → `'Value flow'`,
+ * `'boundedContext'` → `'Bounded context'`. Sentence case, not title case: a
+ * header is a phrase, and capitalising every word turns `'change arrows'` into
+ * a product name.
+ *
+ * It is a FALLBACK and nothing more. A host with a catalogue answers
+ * `com.labre.catalogue.category.<id>` and this is never seen; a standalone
+ * playground reads a word instead of a raw key. The library still invents no
+ * framework prose — a category id is the framework's own word, only respelled.
+ *
+ * It lives in `@labre/std` rather than beside the panel that renders it because
+ * a FRAMEWORK has to derive the same fallback for its own contribution to the
+ * key manifest (see {@link commandCategoryTranslationEntries}), and `@labre/std`
+ * is the only layer every framework package already depends on. The catalogue
+ * widget re-exports it, so the panel and the manifest cannot drift.
+ */
+export declare function humanizeCategory(category: string): string;
+/**
+ * The catalogue group headers a command group implies: one entry per distinct
+ * `category` it declares, with the panel's own humanised fallback.
+ *
+ * A framework contributes these WITH its commands, for the reason the command
+ * entries themselves ship with the framework: `@formicoidea/labre-core` is the
+ * editor minus the frameworks, so a header key derived from core's registry
+ * alone knows nothing about "events", "gateways" or "swimlanes" — and a bundled
+ * host ended up drawing translated catalogue entries under English headers
+ * (#183). Deriving them from the same `commands` array on both sides makes the
+ * monorepo assembly and the composed bundle produce the same list.
+ */
+export declare function commandCategoryTranslationEntries(commands: readonly AnyCommandDescriptor[]): TranslationKeyManifestEntry[];
 /**
  * Compose contributions into one manifest: first occurrence of a key wins (so
  * the caller's order decides which `source` a shared key reports), sorted by

package/dist/_pkgs/std/extension/translation-manifest.js

@@ -54,6 +54,64 @@ export function collectTranslationKeys(source, value) {
 export function commandTranslationEntries(commands) {
     return collectTranslationKeys('command', commands.map(toCommandManifestEntry));
 }
+/** The i18n key prefix every artefact-catalogue group header is looked up under. */
+export const CATALOGUE_CATEGORY_KEY_PREFIX = 'com.labre.catalogue.category.';
+/**
+ * The English default for a category header, derived from the category id.
+ *
+ * `'backgrounds'` → `'Backgrounds'`, `'value-flow'` → `'Value flow'`,
+ * `'boundedContext'` → `'Bounded context'`. Sentence case, not title case: a
+ * header is a phrase, and capitalising every word turns `'change arrows'` into
+ * a product name.
+ *
+ * It is a FALLBACK and nothing more. A host with a catalogue answers
+ * `com.labre.catalogue.category.<id>` and this is never seen; a standalone
+ * playground reads a word instead of a raw key. The library still invents no
+ * framework prose — a category id is the framework's own word, only respelled.
+ *
+ * It lives in `@labre/std` rather than beside the panel that renders it because
+ * a FRAMEWORK has to derive the same fallback for its own contribution to the
+ * key manifest (see {@link commandCategoryTranslationEntries}), and `@labre/std`
+ * is the only layer every framework package already depends on. The catalogue
+ * widget re-exports it, so the panel and the manifest cannot drift.
+ */
+export function humanizeCategory(category) {
+    const words = category
+        // camelCase and PascalCase boundaries, before the separators are split on:
+        // `'boundedContext'` has no separator to find otherwise.
+        .replace(/([a-z0-9])([A-Z])/g, '$1 $2')
+        .split(/[-_\s]+/)
+        .filter(Boolean)
+        .map(word => word.toLowerCase());
+    if (!words.length)
+        return category;
+    const [first, ...rest] = words;
+    return [first.charAt(0).toUpperCase() + first.slice(1), ...rest].join(' ');
+}
+/**
+ * The catalogue group headers a command group implies: one entry per distinct
+ * `category` it declares, with the panel's own humanised fallback.
+ *
+ * A framework contributes these WITH its commands, for the reason the command
+ * entries themselves ship with the framework: `@formicoidea/labre-core` is the
+ * editor minus the frameworks, so a header key derived from core's registry
+ * alone knows nothing about "events", "gateways" or "swimlanes" — and a bundled
+ * host ended up drawing translated catalogue entries under English headers
+ * (#183). Deriving them from the same `commands` array on both sides makes the
+ * monorepo assembly and the composed bundle produce the same list.
+ */
+export function commandCategoryTranslationEntries(commands) {
+    const categories = new Set();
+    for (const command of commands) {
+        if (command.category)
+            categories.add(command.category);
+    }
+    return [...categories].map(category => ({
+        key: `${CATALOGUE_CATEGORY_KEY_PREFIX}${category}`,
+        fallback: humanizeCategory(category),
+        source: 'chrome',
+    }));
+}
 /**
  * Compose contributions into one manifest: first occurrence of a key wins (so
  * the caller's order decides which `source` a shared key reports), sorted by

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';