@formicoidea/labre-core 0.31.0 → 0.33.0

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

@@ -0,0 +1,431 @@
+import { createIdentifier } from '../../global/di/index.js';
+import { SurfaceSelection } from '../selection/index.js';
+import { ShortcutExtension, } from './shortcut.js';
+/**
+ * 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[]`).
+ *
+ * `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 const FRAMEWORK_IDS = [
+    'wardley',
+    'edgy',
+    'cynefin-estuarine',
+    'bpmn',
+    'c4',
+    'ddd-event-storming',
+    'ddd-core-domain',
+    'ddd-context-map',
+];
+/** Multi-instance: one registered {@link CommandDescriptor} per impl. */
+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`
+ * (which would close an import cycle through `extension/`): the gfx manager
+ * derives it from exactly these selections.
+ */
+export const isEditingOnCanvas = (std) => surfaceSelections(std).some(sel => sel.editing);
+const hasCanvasSelection = (std) => surfaceSelections(std).some(sel => sel.elements.length > 0);
+/**
+ * Evaluate a command's serializable precondition in-editor. `when` narrows it
+ * further and is evaluated by the callers, never folded in here — the two are
+ * deliberately separate so the manifest value stays the whole truth a host can
+ * see.
+ *
+ * `'selection:framework'` evaluates as `'selection'`; narrowing to the owner's
+ * element types is left to `when`. `validation.mapQuality` is the first command
+ * to declare it, and it is also why the narrowing has not moved here: what makes
+ * an element a framework's ROOT INSTANCE is a question for the validation
+ * engine (which rule declares a `backgroundRole` this element's role satisfies),
+ * and `@labre/std` neither knows nor should learn it. The serializable value
+ * stays the whole truth a host catalogue can see; the in-editor refinement stays
+ * in `when`. See ADR 0008 § Availability.
+ */
+export function isCommandAvailable(std, command) {
+    switch (command.availability ?? 'always') {
+        case 'always':
+            return true;
+        case 'selection':
+        case 'selection:framework':
+            return !isEditingOnCanvas(std) && hasCanvasSelection(std);
+        case 'editable':
+            return !std.store.readonly;
+    }
+}
+/**
+ * THE bottleneck: the one place a command runs, and therefore the one place
+ * 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 });
+}
+/**
+ * One of the three permanent projections out of {@link CommandDescriptor} —
+ * NOT a migration shim. It is TOTAL: keyless commands yield a descriptor with
+ * empty `defaultKeys` rather than being dropped, so a `ShortcutOverrides` entry
+ * on their id actually binds and Settings › Shortcuts can offer every command.
+ *
+ * `id`, `labelKey`, `defaultKeys`, `scope` and `owner` are carried over
+ * verbatim, which is what keeps hosts' persisted v0.29 override tables valid.
+ */
+export function toShortcutDescriptor(command) {
+    return {
+        id: command.id,
+        labelKey: command.labelKey,
+        defaultKeys: command.defaultKeys,
+        scope: command.scope,
+        owner: command.owner,
+        handler: std => ctx => {
+            // A keystroke aimed at a canvas text editor belongs to that editor.
+            if (command.scope === 'edgeless' && isEditingOnCanvas(std))
+                return false;
+            if (!isCommandAvailable(std, command))
+                return false;
+            if (command.when && !command.when(std))
+                return false;
+            ctx.get('defaultState').event.preventDefault();
+            runCommand(std, command, { surface: 'shortcut', source: 'shortcut' });
+            return true;
+        },
+    };
+}
+const zodDef = (schema) => schema?._def ?? {};
+const ZOD_KIND = {
+    ZodString: 'string',
+    ZodNumber: 'number',
+    ZodBoolean: 'boolean',
+    ZodEnum: 'string',
+};
+/** Unwraps at most a few modifier layers; a deeper nesting is not describable. */
+function describeParam(key, schema) {
+    let current = schema;
+    let required = true;
+    let nullable = false;
+    for (let depth = 0; depth < 4; depth++) {
+        const def = zodDef(current);
+        if (def.typeName === 'ZodOptional' || def.typeName === 'ZodDefault') {
+            required = false;
+            current = def.innerType;
+            continue;
+        }
+        if (def.typeName === 'ZodNullable') {
+            nullable = true;
+            current = def.innerType;
+            continue;
+        }
+        break;
+    }
+    const def = zodDef(current);
+    const kind = def.typeName === 'ZodArray'
+        ? zodDef(def.type).typeName === 'ZodString'
+            ? 'string[]'
+            : undefined
+        : ZOD_KIND[def.typeName ?? ''];
+    if (!kind)
+        return undefined;
+    return nullable ? { key, kind, required, nullable } : { key, kind, required };
+}
+/**
+ * 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
+ * manifest has no way to learn that `pivot.bind` needs a `pivotDocId`, and an
+ * argument-less call is a silent no-op.
+ *
+ * All or nothing on purpose. A partially described object would be worse than
+ * none: an agent would send what it was told and have its call rejected by the
+ * schema for a key the manifest never mentioned. So one undescribable property
+ * withdraws the whole contract, and the command reads as "parameters exist, but
+ * this seam cannot state them" — which is the honest answer.
+ */
+export function describeCommandParams(schema) {
+    const def = zodDef(schema);
+    if (def.typeName !== 'ZodObject' || typeof def.shape !== 'function') {
+        return undefined;
+    }
+    const params = [];
+    for (const [key, property] of Object.entries(def.shape())) {
+        const param = describeParam(key, property);
+        if (!param)
+            return undefined;
+        params.push(param);
+    }
+    return params.length ? params : undefined;
+}
+/** The serializable projection. Functions and templates stop here. */
+export function toCommandManifestEntry(command) {
+    return {
+        id: command.id,
+        owner: command.owner,
+        kind: command.kind,
+        labelKey: command.labelKey,
+        labelFallback: command.labelFallback,
+        descriptionKey: command.descriptionKey,
+        descriptionFallback: command.descriptionFallback,
+        category: command.category,
+        iconKey: command.iconKey,
+        keywords: command.keywords,
+        surfaces: command.surfaces,
+        order: command.order,
+        scope: command.scope,
+        defaultKeys: command.defaultKeys,
+        availability: command.availability ?? 'always',
+        params: describeCommandParams(command.params),
+        telemetry: command.telemetry,
+    };
+}
+let _commandId = 1;
+/**
+ * Register a package's commands. ONE call gives both faces: the enumerable
+ * registry (in-editor consumers) and — through {@link toShortcutDescriptor} —
+ * the keymap bindings. Registering inside a flag-gated view extension is what
+ * makes a disabled framework vanish from both at once.
+ */
+export function CommandExtension(commands, icons) {
+    return {
+        setup: di => {
+            commands.forEach(command => {
+                di.addImpl(CommandDescriptorIdentifier(`Command-${_commandId++}`), command);
+            });
+            if (icons) {
+                di.addImpl(CommandIconsIdentifier(`CommandIcons-${_commandId++}`), icons);
+            }
+            ShortcutExtension(commands.map(toShortcutDescriptor)).setup(di);
+        },
+    };
+}
+/** Every command registered in this editor assembly. */
+export function getRegisteredCommands(std) {
+    return [...std.provider.getAll(CommandDescriptorIdentifier).values()];
+}
+/**
+ * The commands one owner contributes to one surface, in `order` then
+ * declaration order. This is what a senior sub-menu renders — no hard-coded
+ * button list anywhere.
+ */
+export function getCommandsForSurface(std, owner, surface) {
+    return getRegisteredCommands(std)
+        .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)
+        return undefined;
+    for (const table of std.provider.getAll(CommandIconsIdentifier).values()) {
+        const icon = table[iconKey];
+        if (icon)
+            return icon;
+    }
+    return undefined;
+}

package/dist/_pkgs/std/extension/dnd/index.d.ts

@@ -130,5 +130,5 @@ export declare class DndController extends LifeCycleWatcher {
      */
     dropTarget<PayloadEntity extends DragEntity = DragEntity, DropData extends {} = {}, PayloadFrom extends DragFrom = DragFromBlockSuite>(args: DropTargetOption<PayloadEntity, PayloadFrom, DropPayload<DropData>>): import("@atlaskit/pragmatic-drag-and-drop/dist/cjs/entry-point/types.js").CleanupFn;
     monitor<PayloadEntity extends DragEntity = DragEntity, DropData extends {} = {}, PayloadFrom extends DragFrom = DragFromBlockSuite>(args: MonitorOption<PayloadEntity, PayloadFrom, DropPayload<DropData>>): import("@atlaskit/pragmatic-drag-and-drop/dist/cjs/entry-point/types.js").CleanupFn;
-    autoScroll<PayloadEntity extends DragEntity = DragEntity, PayloadFrom extends DragFrom = DragFromBlockSuite>(options: AutoScroll<PayloadEntity, PayloadFrom>): import("@atlaskit/pragmatic-drag-and-drop/dist/cjs/entry-point/types.js").CleanupFn;
+    autoScroll<PayloadEntity extends DragEntity = DragEntity, PayloadFrom extends DragFrom = DragFromBlockSuite>(options: AutoScroll<PayloadEntity, PayloadFrom>): () => void;
 }

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

@@ -1,4 +1,5 @@
 export * from './block-view.js';
+export * from './command-registry.js';
 export * from './config.js';
 export * from './dnd/index.js';
 export * from './editor-life-cycle.js';
@@ -8,4 +9,5 @@ export * from './lifecycle-watcher.js';
 export * from './service.js';
 export * from './shortcut.js';
 export * from './service-manager.js';
+export * from './translation-manifest.js';
 export * from './widget-view-map.js';

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

@@ -1,4 +1,5 @@
 export * from './block-view.js';
+export * from './command-registry.js';
 export * from './config.js';
 export * from './dnd/index.js';
 export * from './editor-life-cycle.js';
@@ -8,4 +9,5 @@ export * from './lifecycle-watcher.js';
 export * from './service.js';
 export * from './shortcut.js';
 export * from './service-manager.js';
+export * from './translation-manifest.js';
 export * from './widget-view-map.js';

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

@@ -0,0 +1,49 @@
+import { type AnyCommandDescriptor } from './command-registry.js';
+/**
+ * The translation-key manifest seam, declared here for the same reason
+ * {@link CommandManifestEntry} is: a manifest a framework CONTRIBUTES to must
+ * be describable by the framework itself, and `@labre/std` is the only layer
+ * every framework package already depends on.
+ *
+ * The manifest is assembled in `@labre/affine/translations`, but assembled from
+ * PARTS: the editor chrome's own entries plus one `…TranslationEntries` export
+ * per installed framework. That is what makes it survive the bundled
+ * distribution, where `@formicoidea/labre-core` ships WITHOUT the frameworks —
+ * 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 interface TranslationKeyManifestEntry {
+    key: string;
+    /**
+     * The English default the library renders when the host's catalogue has no
+     * entry. Absent for the keys that deliberately ship none (framework prose
+     * whose wording the library must not invent — see the `translateKey`
+     * docstring).
+     */
+    fallback?: string;
+    /** Which kind of declaration the key comes from. */
+    source: TranslationKeySource;
+}
+/**
+ * Deep-walk a declaration and collect every `…Key` string property holding a
+ * `com.labre.*` key, paired with its fallback by the repo's own conventions:
+ * `<stem>Key` ↔ `<stem>Fallback` (roles, rules, commands, conventions), and
+ * `labelKey` ↔ `fallback` (profiles, nudges, criteria, background labels).
+ *
+ * This is what makes the manifest DERIVED rather than restated: a key added to
+ * a rule or a role shows up with no further work.
+ */
+export declare function collectTranslationKeys(source: TranslationKeySource, value: unknown): TranslationKeyManifestEntry[];
+/**
+ * A command group's contribution. Walks the SERIALIZABLE projection, not the
+ * descriptors: `run` and the zod schemas carry no keys and walking them would
+ * mean walking zod internals.
+ */
+export declare function commandTranslationEntries(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
+ * key so two hosts composing the same parts get the same list.
+ */
+export declare function mergeTranslationEntries(...groups: readonly (readonly TranslationKeyManifestEntry[])[]): TranslationKeyManifestEntry[];

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

@@ -0,0 +1,71 @@
+import { toCommandManifestEntry, } from './command-registry.js';
+const KEY_PREFIX = 'com.labre.';
+function walk(source, value, out, seen) {
+    if (typeof value !== 'object' || value === null)
+        return;
+    if (seen.has(value))
+        return;
+    seen.add(value);
+    if (Array.isArray(value)) {
+        for (const item of value)
+            walk(source, item, out, seen);
+        return;
+    }
+    const record = value;
+    for (const [prop, propValue] of Object.entries(record)) {
+        if (typeof propValue === 'string' &&
+            prop.endsWith('Key') &&
+            propValue.startsWith(KEY_PREFIX)) {
+            if (out.has(propValue))
+                continue;
+            const stem = prop.slice(0, -'Key'.length);
+            const fallback = record[`${stem}Fallback`] ??
+                (prop === 'labelKey' ? record.fallback : undefined);
+            out.set(propValue, {
+                key: propValue,
+                ...(typeof fallback === 'string' ? { fallback } : {}),
+                source,
+            });
+        }
+        else {
+            walk(source, propValue, out, seen);
+        }
+    }
+}
+/**
+ * Deep-walk a declaration and collect every `…Key` string property holding a
+ * `com.labre.*` key, paired with its fallback by the repo's own conventions:
+ * `<stem>Key` ↔ `<stem>Fallback` (roles, rules, commands, conventions), and
+ * `labelKey` ↔ `fallback` (profiles, nudges, criteria, background labels).
+ *
+ * This is what makes the manifest DERIVED rather than restated: a key added to
+ * a rule or a role shows up with no further work.
+ */
+export function collectTranslationKeys(source, value) {
+    const out = new Map();
+    walk(source, value, out, new WeakSet());
+    return [...out.values()];
+}
+/**
+ * A command group's contribution. Walks the SERIALIZABLE projection, not the
+ * descriptors: `run` and the zod schemas carry no keys and walking them would
+ * mean walking zod internals.
+ */
+export function commandTranslationEntries(commands) {
+    return collectTranslationKeys('command', commands.map(toCommandManifestEntry));
+}
+/**
+ * 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
+ * key so two hosts composing the same parts get the same list.
+ */
+export function mergeTranslationEntries(...groups) {
+    const out = new Map();
+    for (const group of groups) {
+        for (const entry of group) {
+            if (!out.has(entry.key))
+                out.set(entry.key, entry);
+        }
+    }
+    return [...out.values()].sort((a, b) => a.key.localeCompare(b.key));
+}

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

@@ -1,6 +1,6 @@
 export { generateKeyBetweenV2 } from '../utils/fractional-indexing.js';
 export { compare as compareLayer, renderableInEdgeless, SortOrder, } from '../utils/layer.js';
-export { canSafeAddToContainer, descendantElementsImpl, getTopElements, hasDescendantElementImpl, } from '../utils/tree.js';
+export { batchAddChildren, batchRemoveChildren, canSafeAddToContainer, descendantElementsImpl, getTopElements, hasDescendantElementImpl, } from '../utils/tree.js';
 export { GfxController } from './controller.js';
 export type { CursorType, StandardCursor } from './cursor.js';
 export { GfxExtension, GfxExtensionIdentifier } from './extension.js';
@@ -13,10 +13,14 @@ export type { GfxCompatibleInterface, GfxElementGeometry, GfxGroupCompatibleInte
 export { gfxGroupCompatibleSymbol, isGfxGroupCompatibleModel, } from './model/base.js';
 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, initializeObservers, initializeWatchers, local, observe, updateDerivedProps, watch, } from './model/surface/decorators/index.js';
-export { type BaseElementProps, GfxGroupLikeElementModel, GfxPrimitiveElementModel, type SerializedElement, } from './model/surface/element-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, 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';
+export { ELEMENT_TAGS_FIELD, type ElementTags, elementTagValues, hasElementTagValue, readElementTags, setElementTag, tagsPropToY, } from './model/surface/tags.js';
 export { SURFACE_TEXT_UNIQ_IDENTIFIER, SURFACE_YMAP_UNIQ_IDENTIFIER, SurfaceBlockModel, type SurfaceBlockProps, type SurfaceMiddleware, } from './model/surface/surface-model.js';
+export { measureOperation } from './perf.js';
 export { GfxSelectionManager } from './selection.js';
 export { SurfaceMiddlewareBuilder, SurfaceMiddlewareExtension, } from './surface-middleware.js';
 export { BaseTool, type ToolOptions, type ToolOptionWithType, type ToolType, } from './tool/tool.js';

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

@@ -1,6 +1,6 @@
 export { generateKeyBetweenV2 } from '../utils/fractional-indexing.js';
 export { compare as compareLayer, renderableInEdgeless, SortOrder, } from '../utils/layer.js';
-export { canSafeAddToContainer, descendantElementsImpl, getTopElements, hasDescendantElementImpl, } from '../utils/tree.js';
+export { batchAddChildren, batchRemoveChildren, canSafeAddToContainer, descendantElementsImpl, getTopElements, hasDescendantElementImpl, } from '../utils/tree.js';
 export { GfxController } from './controller.js';
 export { GfxExtension, GfxExtensionIdentifier } from './extension.js';
 export { GridManager } from './grid.js';
@@ -10,10 +10,14 @@ export { LayerManager } from './layer.js';
 export { gfxGroupCompatibleSymbol, isGfxGroupCompatibleModel, } from './model/base.js';
 export { GfxBlockElementModel, GfxCompatibleBlockModel as GfxCompatible, } from './model/gfx-block-model.js';
 export { isPrimitiveModel } from './model/model.js';
-export { convert, convertProps, derive, field, getDerivedProps, getFieldPropsSet, initializeObservers, initializeWatchers, local, observe, updateDerivedProps, watch, } from './model/surface/decorators/index.js';
+export { convert, convertProps, derive, field, getDerivedProps, getFieldPropsSet, getLocalPropsSet, initializeObservers, initializeWatchers, local, observe, updateDerivedProps, watch, } from './model/surface/decorators/index.js';
 export { GfxGroupLikeElementModel, GfxPrimitiveElementModel, } from './model/surface/element-model.js';
 export { GfxLocalElementModel, prop, } from './model/surface/local-element-model.js';
+export { collectPivotOccurrences, isPivotBound, } from './model/surface/pivot.js';
+export { findRoleDef, isTypedEdgeRole, roleIsA, RoleVocabularyExtension, RoleVocabularyIdentifier, } from './model/surface/role.js';
+export { ELEMENT_TAGS_FIELD, elementTagValues, hasElementTagValue, readElementTags, setElementTag, tagsPropToY, } from './model/surface/tags.js';
 export { SURFACE_TEXT_UNIQ_IDENTIFIER, SURFACE_YMAP_UNIQ_IDENTIFIER, SurfaceBlockModel, } from './model/surface/surface-model.js';
+export { measureOperation } from './perf.js';
 export { GfxSelectionManager } from './selection.js';
 export { SurfaceMiddlewareBuilder, SurfaceMiddlewareExtension, } from './surface-middleware.js';
 export { BaseTool, } from './tool/tool.js';