@formicoidea/labre-core 0.31.0 → 0.32.0

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

@@ -0,0 +1,321 @@
+import type { ExtensionType } from '../../store/index.js';
+import type { TemplateResult } from 'lit';
+import type { z } from 'zod';
+import type { BlockStdScope } from '../scope/index.js';
+import { type ShortcutDescriptor, type ShortcutScope } from './shortcut.js';
+/**
+ * Where an element/tool creation was triggered from. Historically declared in
+ * `@labre/affine-shared`'s telemetry types; it moved down here (and is
+ * re-exported from there, unchanged) because {@link CommandInvocation} — the
+ * single source of the "which surface invoked this" dimension — lives in
+ * `@labre/std`. See `docs/adr/0008`.
+ */
+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
+ * 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 declare const FRAMEWORK_IDS: readonly ["wardley", "edgy", "cynefin-estuarine", "bpmn", "ddd-event-storming", "ddd-core-domain", "ddd-context-map"];
+export type FrameworkId = (typeof FRAMEWORK_IDS)[number];
+export type CommandOwner = 'core' | FrameworkId;
+/**
+ * Serializable precondition. Closed union; extended only by an amendment to
+ * `docs/adr/0008`. `'always'` is the default when omitted.
+ */
+export type Availability = 'always' | 'selection' | 'selection:framework' | 'editable';
+/**
+ * Which surfaces a command opts into. Absent from the array = absent from the
+ * surface. Settings › Shortcuts is NOT a member: EVERY command is bindable, so
+ * opting out of it is not expressible on purpose.
+ *
+ * `'contextual-toolbar'` joined the union with `docs/adr/0010`'s M3, the first
+ * command whose natural home is the toolbar of a selected element. The entry
+ * itself is still declared by the element's own `ToolbarModuleConfig` — a
+ * toolbar is a designed row, not an enumeration — but it INVOKES the registered
+ * command, so the behaviour, the availability rule and the single telemetry
+ * emission stay in one place, and `CommandInvocation.surface` reports where the
+ * user actually clicked instead of borrowing another surface's name.
+ */
+export type CommandSurface = 'senior-menu' | 'catalogue' | 'palette' | 'contextual-toolbar' | 'agent';
+export type CommandKind = 'artefact' | 'tool' | 'toggle' | 'legend' | 'action';
+/** Where the invocation came from — feeds `segment` / `module` / `control`. */
+export interface CommandInvocation {
+    surface: CommandSurface | 'shortcut';
+    source: ElementCreationSource;
+}
+/**
+ * The single source of truth for everything a framework offers. The keyboard
+ * binding is one FACET of a command — present, possibly empty, always
+ * rebindable — not a separate declaration.
+ *
+ * Two permanent projections derive from it and nothing else:
+ * {@link toShortcutDescriptor} (in-editor keymap + Settings › Shortcuts) and
+ * {@link toCommandManifestEntry} (the serializable catalogue seam).
+ */
+export interface CommandDescriptor<P = void> {
+    /** Stable id; same namespace as the shortcut ids: `'wardley.addComponent'`. */
+    id: string;
+    owner: CommandOwner;
+    kind: CommandKind;
+    /** i18n keys — resolved host-side, as `ShortcutDescriptor.labelKey` is. */
+    labelKey: string;
+    /**
+     * English default for the in-library chrome that has to SHOW the label (the
+     * senior sub-menu tooltip). Same seam and same rule as the framework
+     * background declarations: a host with no catalogue reads correctly, a host
+     * with one always wins. Without it the switchover would replace today's
+     * English tooltips with raw i18n keys.
+     */
+    labelFallback?: string;
+    descriptionKey?: string;
+    /**
+     * English default for {@link descriptionKey}, same seam and same rule as
+     * {@link labelFallback}: a host with a catalogue always wins, a host without
+     * one still reads a sentence instead of a raw key.
+     *
+     * It exists because a description is now SHOWN in-library — the senior
+     * sub-menu puts it under the label, which is where a tool announces what its
+     * gesture means (`docs/adr/0010` M1). Before that, `descriptionKey` crossed
+     * the manifest seam and was never rendered by this repository.
+     */
+    descriptionFallback?: string;
+    /** Sub-category inside the owner's catalogue, e.g. `'backgrounds'`. */
+    category?: string;
+    /**
+     * Stable asset key, NOT markup. Resolved to a template by the library's own
+     * icon registry ({@link CommandIconExtension}); a host may substitute its
+     * set, but need not.
+     */
+    iconKey?: string;
+    /** Extra search terms for the palette. */
+    keywords?: string[];
+    surfaces: CommandSurface[];
+    /** Ascending rank inside `senior-menu` / `catalogue`. */
+    order?: number;
+    scope: ShortcutScope;
+    /**
+     * Default chord. `{ mac: [], other: [] }` means "no default, still bindable"
+     * — the shipped `redo-windows` precedent. Never `undefined`.
+     */
+    defaultKeys: {
+        mac: string[];
+        other: string[];
+    };
+    /** Serializable precondition; defaults to `'always'`. Crosses the host seam. */
+    availability?: Availability;
+    /**
+     * In-library refinement of {@link availability} — never contradicting it,
+     * only narrowing. Not projected into either manifest.
+     */
+    when?: (std: BlockStdScope) => boolean;
+    /** THE new capability: invocable without a keyboard event. */
+    run: (std: BlockStdScope, invocation: CommandInvocation, params?: P) => void | Promise<void>;
+    /** Agent-facing parameter contract. */
+    params?: z.ZodType<P>;
+    /**
+     * Emitted centrally by {@link runCommand} — never by the command body.
+     * `framework` is the code-side id; the reporter maps it through
+     * `FrameworkDescriptor.telemetryKey` so the wire value stays historical.
+     */
+    telemetry?: {
+        framework: FrameworkId;
+        element: string;
+    };
+}
+/**
+ * A command with its parameter contract erased — what the REGISTRY holds.
+ *
+ * The registry is heterogeneous by design: nullary commands (`undo`,
+ * `wardley.addComponent`) sit in the same list as parameterised ones
+ * (`pivot.bind`, whose record id cannot come from the library). The default
+ * `CommandDescriptor` — i.e. `CommandDescriptor<void>` — cannot express that:
+ * under `strictFunctionTypes`, `run`'s parameter is contravariant and `params`
+ * covariant, so a `CommandDescriptor<P>` is assignable to neither direction of
+ * `CommandDescriptor<void>`.
+ *
+ * Erasure costs nothing at runtime: {@link runCommand} forwards `params`
+ * opaquely, and a parameterised command re-validates with its own zod schema
+ * inside `run` — which an agent-invocable command has to do regardless of what
+ * the static type promises.
+ */
+export type AnyCommandDescriptor = CommandDescriptor<any>;
+/**
+ * Value kinds a command parameter may take across the host seam. Closed and
+ * deliberately small: the seam describes what an agent must SEND, not the
+ * host's type system. Anything richer stays behind `CommandDescriptor.params`,
+ * which never crosses.
+ */
+export type CommandParamKind = 'string' | 'number' | 'boolean' | 'string[]';
+/** One parameter, described serializably. See {@link describeCommandParams}. */
+export interface CommandParam {
+    key: string;
+    kind: CommandParamKind;
+    /** `false` when the key may be omitted entirely. */
+    required: boolean;
+    /** `null` is an accepted value carrying a meaning of its own. */
+    nullable?: boolean;
+}
+/**
+ * The serializable catalogue projection — no functions, no `TemplateResult`.
+ * This is what crosses the host seam for the sidepanel, the palette and the
+ * agent (ADR 0006: the seam stays typed and render-free).
+ */
+export interface CommandManifestEntry {
+    id: string;
+    owner: CommandOwner;
+    kind: CommandKind;
+    labelKey: string;
+    labelFallback?: string;
+    descriptionKey?: string;
+    descriptionFallback?: string;
+    category?: string;
+    iconKey?: string;
+    keywords?: string[];
+    surfaces: CommandSurface[];
+    order?: number;
+    scope: ShortcutScope;
+    defaultKeys: {
+        mac: string[];
+        other: string[];
+    };
+    availability: Availability;
+    /**
+     * What an invoker must send. Absent = nullary, which is what almost every
+     * command is. Derived from `CommandDescriptor.params`, never authored twice.
+     */
+    params?: CommandParam[];
+    telemetry?: {
+        framework: FrameworkId;
+        element: string;
+    };
+}
+/**
+ * The per-framework identity consumers 2-5 need, and that nothing owned before
+ * — spelled five times across the repo and already drifted. It is also THE
+ * source for packaging: `scripts/build-bundles.mjs` derives its bundle entries
+ * from `FRAMEWORK_DESCRIPTORS` instead of a hand-maintained array.
+ */
+export interface FrameworkDescriptor {
+    id: FrameworkId;
+    /** Replaces the raw English `SeniorTool.name`. */
+    labelKey: string;
+    iconKey: string;
+    order?: number;
+    /** First keystroke of this framework's chords — allocated, not ad hoc. */
+    chordPrefix?: string;
+    /**
+     * Historical PostHog value for `FrameworkElementEvent.framework`, kept as-is
+     * so the identity unification stays code-side and analytics never break.
+     * e.g. id `'ddd-event-storming'` → telemetryKey `'event-storming'`.
+     */
+    telemetryKey: string;
+    /**
+     * Historical PostHog value for `TelemetryEvent.segment`. Not derivable from
+     * {@link telemetryKey} (the three DDD frameworks all emit `'ddd toolbox'`),
+     * and the "no analytics breakage" rule of ADR 0008 makes it load-bearing.
+     */
+    telemetrySegment: string;
+    /** Packaging: the published bundle name suffix, e.g. `'framework-wardley'`. */
+    bundle: string;
+    /** Packaging: the exported host-wiring descriptor name. */
+    info: string;
+    pkg: string;
+    dir: string;
+    extensions: {
+        flag?: string;
+        viewExtension: string;
+    }[];
+    /** Packaging: the framework contributes shortcut-manifest entries. */
+    shortcuts?: boolean;
+}
+/** Multi-instance: one registered {@link CommandDescriptor} per impl. */
+export declare const CommandDescriptorIdentifier: import("../../global/di/types.js").ServiceIdentifier<AnyCommandDescriptor> & (<U extends AnyCommandDescriptor = AnyCommandDescriptor>(variant: import("../../global/di/types.js").ServiceVariant) => import("../../global/di/types.js").ServiceIdentifier<U>);
+/** Multi-instance: one `iconKey → template` table per contributing package. */
+export declare const CommandIconsIdentifier: import("../../global/di/types.js").ServiceIdentifier<Record<string, TemplateResult>> & (<U extends Record<string, TemplateResult> = Record<string, TemplateResult>>(variant: import("../../global/di/types.js").ServiceVariant) => import("../../global/di/types.js").ServiceIdentifier<U>);
+/**
+ * Sink for the ONE telemetry emission per invocation. Declared here because
+ * {@link runCommand} is the bottleneck; implemented in the affine layer, which
+ * owns `TelemetryProvider` and the `telemetryKey` mapping.
+ */
+export type CommandTelemetryReporter = (report: {
+    std: BlockStdScope;
+    command: AnyCommandDescriptor;
+    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>);
+/**
+ * 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 declare const isEditingOnCanvas: (std: BlockStdScope) => boolean;
+/**
+ * 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 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.
+ */
+export declare function runCommand(std: BlockStdScope, command: AnyCommandDescriptor, invocation: CommandInvocation, params?: unknown): void;
+/**
+ * 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 declare function toShortcutDescriptor(command: AnyCommandDescriptor): ShortcutDescriptor;
+/**
+ * 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 declare function describeCommandParams(schema: unknown): CommandParam[] | undefined;
+/** The serializable projection. Functions and templates stop here. */
+export declare function toCommandManifestEntry(command: AnyCommandDescriptor): CommandManifestEntry;
+/**
+ * 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 declare function CommandExtension(commands: AnyCommandDescriptor[], icons?: Record<string, TemplateResult>): ExtensionType;
+/** Every command registered in this editor assembly. */
+export declare function getRegisteredCommands(std: BlockStdScope): AnyCommandDescriptor[];
+/**
+ * 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 declare function getCommandsForSurface(std: BlockStdScope, owner: CommandOwner, surface: CommandSurface): 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

@@ -0,0 +1,233 @@
+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
+ * 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',
+    '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');
+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. 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);
+    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));
+}
+/** 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/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[];