@formicoidea/labre-core 0.30.1 → 0.32.0

package/dist/_pkgs/std/event/dispatcher.js

@@ -49,6 +49,15 @@ const eventNames = [
     'nativeDragLeave',
     ...bypassEventNames,
 ];
+/**
+ * Events the dispatcher synthesizes itself: `click`, `doubleClick` and
+ * `tripleClick` are all derived from a single native `pointerup`. Stopping
+ * propagation of that shared native event when a synthetic handler consumes
+ * the click would also silence unrelated pointer listeners bound higher up
+ * (document-level drag/pan/auto-complete teardown), so it is skipped for them.
+ * Consuming a synthetic event still stops the dispatcher's own runner chain.
+ */
+const syntheticEventNames = new Set(['click', 'doubleClick', 'tripleClick']);
 export class UIEventDispatcher extends LifeCycleWatcher {
     static { this._activeDispatcher = null; }
     static { this.key = 'UIEventDispatcher'; }
@@ -157,6 +166,20 @@ export class UIEventDispatcher extends LifeCycleWatcher {
                 this._setActive(false);
             }
         });
+        // When the selection is outside the host, the event dispatcher should be
+        // inactive. Selecting text in a plain (non-focusable) element outside the
+        // editor fires neither `focusout` with a relatedTarget nor `blur`, so
+        // without this the editor would keep handling keystrokes aimed elsewhere.
+        this.disposables.addFromEvent(document, 'selectionchange', () => {
+            const sel = document.getSelection();
+            if (!sel || sel.rangeCount === 0)
+                return;
+            const { anchorNode, focusNode } = sel;
+            if ((anchorNode && !this.host.contains(anchorNode)) ||
+                (focusNode && !this.host.contains(focusNode))) {
+                this._setActive(false);
+            }
+        });
     }
     _buildEventScopeBySelection(name) {
         const handlers = this._handlersMap[name];
@@ -321,7 +344,10 @@ export class UIEventDispatcher extends LifeCycleWatcher {
             const { fn } = runner;
             const result = fn(context);
             if (result) {
-                context.get('defaultState').event.stopPropagation();
+                // Only stop propagation for non-synthetic events
+                if (!syntheticEventNames.has(name)) {
+                    context.get('defaultState').event.stopPropagation();
+                }
                 return;
             }
         }

package/dist/_pkgs/std/event/keymap.js

@@ -197,13 +197,23 @@ export function bindKeymap(bindings, interceptors) {
                 return true;
             }
         }
-        // none standard keyboard, fallback to keyCode
-        const special = event.shiftKey ||
-            event.altKey ||
-            event.metaKey ||
-            name.charCodeAt(0) > 127;
+        // For non-standard keyboards, fallback to keyCode only when modifier keys
+        // are pressed. Do NOT fallback when the key produces a non-ASCII character
+        // (e.g. Cyrillic 'х' on a Russian layout), because the user intends to type
+        // that character, not to trigger a shortcut bound to the physical key.
+        // See: https://github.com/toeverything/AFFiNE/issues/14059
+        const hasModifier = event.shiftKey || event.altKey || event.ctrlKey || event.metaKey;
         const baseName = base[event.keyCode];
-        if (special && baseName && baseName !== name) {
+        const isSingleAscii = name.length === 1 && name.charCodeAt(0) <= 0x7e;
+        const isAltInputChar = event.altKey && !event.ctrlKey && !event.metaKey && !isSingleAscii;
+        // Keep supporting existing Alt+digit shortcuts (e.g. Alt-0/1/2 in edgeless)
+        // while preventing Alt-based locale input characters from triggering letter
+        // shortcuts.
+        const isDigitBaseKey = baseName != null && baseName.length === 1 && /[0-9]/.test(baseName);
+        if (hasModifier &&
+            baseName &&
+            baseName !== name &&
+            !(isAltInputChar && !isDigitBaseKey)) {
             const fromCode = map[modifiers(baseName, event)];
             if (fromCode && fromCode(ctx)) {
                 return true;

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

@@ -1,6 +1,6 @@
-import { type ElementGetFeedbackArgs } from '@atlaskit/pragmatic-drag-and-drop/element/adapter';
-import type { DropTargetRecord } from '@atlaskit/pragmatic-drag-and-drop/types';
-import { type Edge } from '@atlaskit/pragmatic-drag-and-drop-hitbox/closest-edge';
+import { type ElementGetFeedbackArgs } from '@atlaskit/pragmatic-drag-and-drop/dist/cjs/entry-point/element/adapter.js';
+import type { DropTargetRecord } from '@atlaskit/pragmatic-drag-and-drop/dist/cjs/entry-point/types.js';
+import { type Edge } from '@atlaskit/pragmatic-drag-and-drop-hitbox/dist/cjs/closest-edge.js';
 import type { ServiceIdentifier } from '../../../global/di/index.js';
 import { LifeCycleWatcher } from '../lifecycle-watcher.js';
 import type { ElementDragEventBaseArgs, ElementDragEventMap, ElementDropEventMap, ElementDropTargetFeedbackArgs, ElementMonitorFeedbackArgs, OriginalAutoScrollOption, OriginalDraggableOption } from './types.js';
@@ -124,11 +124,11 @@ export declare class DndController extends LifeCycleWatcher {
     /**
      * Make an element draggable.
      */
-    draggable<PayloadEntity extends DragEntity = DragEntity, DropData extends {} = {}>(args: DraggableOption<PayloadEntity, DragFromBlockSuite, DropPayload<DropData>>): import("@atlaskit/pragmatic-drag-and-drop/types").CleanupFn;
+    draggable<PayloadEntity extends DragEntity = DragEntity, DropData extends {} = {}>(args: DraggableOption<PayloadEntity, DragFromBlockSuite, DropPayload<DropData>>): import("@atlaskit/pragmatic-drag-and-drop/dist/cjs/entry-point/types.js").CleanupFn;
     /**
      * Make an element a drop target.
      */
-    dropTarget<PayloadEntity extends DragEntity = DragEntity, DropData extends {} = {}, PayloadFrom extends DragFrom = DragFromBlockSuite>(args: DropTargetOption<PayloadEntity, PayloadFrom, DropPayload<DropData>>): import("@atlaskit/pragmatic-drag-and-drop/types").CleanupFn;
-    monitor<PayloadEntity extends DragEntity = DragEntity, DropData extends {} = {}, PayloadFrom extends DragFrom = DragFromBlockSuite>(args: MonitorOption<PayloadEntity, PayloadFrom, DropPayload<DropData>>): import("@atlaskit/pragmatic-drag-and-drop/types").CleanupFn;
-    autoScroll<PayloadEntity extends DragEntity = DragEntity, PayloadFrom extends DragFrom = DragFromBlockSuite>(options: AutoScroll<PayloadEntity, PayloadFrom>): import("@atlaskit/pragmatic-drag-and-drop/types").CleanupFn;
+    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>): () => void;
 }