@formicoidea/labre-core 0.26.1 → 0.29.0

package/dist/_pkgs/affine-shared/services/keymap-override-service.d.ts

@@ -0,0 +1,15 @@
+import { type ShortcutConflictReporter, type ShortcutOverrides } from '../../std/index.js';
+import type { ExtensionType } from '../../store/index.js';
+/**
+ * Host-injected shortcut rebinding table. Each entry maps a shortcut id to a
+ * combo (array of keys, e.g. `['Ctrl', 'Shift', 'Z']`) or `'disabled'`. The
+ * effective keymap is `override ?? default`; `'disabled'` removes the binding.
+ *
+ * Mirrors `TelemetryExtension` / `EditorSettingExtension`.
+ */
+export declare function KeymapOverrideExtension(overrides: ShortcutOverrides): ExtensionType;
+/**
+ * Host-injected sink for combo conflicts detected within a scope. Without it,
+ * conflicts are logged to the console.
+ */
+export declare function ShortcutConflictReporterExtension(reporter: ShortcutConflictReporter): ExtensionType;

package/dist/_pkgs/affine-shared/services/keymap-override-service.js

@@ -0,0 +1,26 @@
+import { ShortcutConflictReporterIdentifier, ShortcutOverrideIdentifier, } from '../../std/index.js';
+/**
+ * Host-injected shortcut rebinding table. Each entry maps a shortcut id to a
+ * combo (array of keys, e.g. `['Ctrl', 'Shift', 'Z']`) or `'disabled'`. The
+ * effective keymap is `override ?? default`; `'disabled'` removes the binding.
+ *
+ * Mirrors `TelemetryExtension` / `EditorSettingExtension`.
+ */
+export function KeymapOverrideExtension(overrides) {
+    return {
+        setup: di => {
+            di.override(ShortcutOverrideIdentifier, () => overrides);
+        },
+    };
+}
+/**
+ * Host-injected sink for combo conflicts detected within a scope. Without it,
+ * conflicts are logged to the console.
+ */
+export function ShortcutConflictReporterExtension(reporter) {
+    return {
+        setup: di => {
+            di.override(ShortcutConflictReporterIdentifier, () => reporter);
+        },
+    };
+}

package/dist/_pkgs/affine-shared/services/linked-doc-content-service.d.ts

@@ -0,0 +1,42 @@
+import type { BlockStdScope } from '../../std/index.js';
+import type { ExtensionType } from '../../store/index.js';
+/**
+ * Host seam for hydrating a linked doc's content on demand. An app that does not
+ * preload its whole corpus into the workspace (so a referenced doc has no
+ * content in memory) implements this to fetch/load that doc when its
+ * preview/embed needs it.
+ */
+export interface LinkedDocContentResolver {
+    /**
+     * Load the referenced doc's content into the workspace. May resolve before
+     * the content actually arrives — the preview also watches for the doc's root
+     * and is bounded by {@link LinkedDocContentResolver.timeoutMs}.
+     */
+    resolve: (docId: string) => void | Promise<void>;
+    /** Max time the preview waits for content before degrading. Default 8000ms. */
+    timeoutMs?: number;
+}
+export declare const LinkedDocContentResolverIdentifier: import("../../global/di/types.js").ServiceIdentifier<LinkedDocContentResolver> & (<U extends LinkedDocContentResolver = LinkedDocContentResolver>(variant: import("../../global/di/types.js").ServiceVariant) => import("../../global/di/types.js").ServiceIdentifier<U>);
+/** Inject a host {@link LinkedDocContentResolver}. */
+export declare function LinkedDocContentResolverExtension(resolver: LinkedDocContentResolver): ExtensionType;
+export declare const DEFAULT_LINKED_DOC_CONTENT_TIMEOUT_MS = 8000;
+/** Minimal shape of a loadable doc store the preview waits on. */
+interface AwaitableDoc {
+    root: object | null;
+    slots: {
+        rootAdded: {
+            subscribe: (cb: () => void) => {
+                unsubscribe: () => void;
+            };
+        };
+    };
+}
+/**
+ * Resolve a linked doc's content for preview, **bounded in time**. If a host
+ * {@link LinkedDocContentResolver} is registered it is asked to hydrate the doc
+ * first. Returns `true` once the doc has a root (content available), or `false`
+ * if it timed out — in which case the caller should render a degraded preview
+ * (title only) instead of spinning forever.
+ */
+export declare function whenLinkedDocContentReady(std: BlockStdScope, doc: AwaitableDoc, docId: string): Promise<boolean>;
+export {};

package/dist/_pkgs/affine-shared/services/linked-doc-content-service.js

@@ -0,0 +1,47 @@
+import { createIdentifier } from '../../global/di/index.js';
+export const LinkedDocContentResolverIdentifier = createIdentifier('AffineLinkedDocContentResolver');
+/** Inject a host {@link LinkedDocContentResolver}. */
+export function LinkedDocContentResolverExtension(resolver) {
+    return {
+        setup: di => {
+            di.override(LinkedDocContentResolverIdentifier, () => resolver);
+        },
+    };
+}
+export const DEFAULT_LINKED_DOC_CONTENT_TIMEOUT_MS = 8000;
+/**
+ * Resolve a linked doc's content for preview, **bounded in time**. If a host
+ * {@link LinkedDocContentResolver} is registered it is asked to hydrate the doc
+ * first. Returns `true` once the doc has a root (content available), or `false`
+ * if it timed out — in which case the caller should render a degraded preview
+ * (title only) instead of spinning forever.
+ */
+export async function whenLinkedDocContentReady(std, doc, docId) {
+    if (doc.root)
+        return true;
+    const resolver = std.getOptional(LinkedDocContentResolverIdentifier);
+    if (resolver) {
+        try {
+            await resolver.resolve(docId);
+        }
+        catch (e) {
+            console.error(e);
+        }
+        if (doc.root)
+            return true;
+    }
+    const timeoutMs = resolver?.timeoutMs ?? DEFAULT_LINKED_DOC_CONTENT_TIMEOUT_MS;
+    return new Promise(resolve => {
+        let settled = false;
+        const finish = (ready) => {
+            if (settled)
+                return;
+            settled = true;
+            subscription.unsubscribe();
+            clearTimeout(timer);
+            resolve(ready);
+        };
+        const subscription = doc.slots.rootAdded.subscribe(() => finish(true));
+        const timer = setTimeout(() => finish(false), timeoutMs);
+    });
+}

package/dist/_pkgs/affine-widget-edgeless-selected-rect/edgeless-element-link.d.ts

@@ -0,0 +1,29 @@
+import type { RootBlockModel } from '../affine-model/index.js';
+import { WidgetComponent } from '../std/index.js';
+import { nothing } from 'lit';
+export declare const EDGELESS_ELEMENT_LINK_WIDGET = "edgeless-element-link";
+/**
+ * Shows a clickable arrow when hovering a drawing element that carries a link
+ * ({@link GfxPrimitiveElementModel.linkedDocId} or `.externalLink`). Clicking it
+ * opens the linked doc (host side-view via `docLinkClicked`) or the URL.
+ *
+ * ponytail: hover is resolved via `getElementByPoint`, which returns the topmost
+ * leaf — a link set on a group only shows when a child is hovered. Good enough
+ * for v1 (shapes/text/connectors are hit directly).
+ */
+export declare class EdgelessElementLinkWidget extends WidgetComponent<RootBlockModel> {
+    static styles: import("lit").CSSResult;
+    private _hideTimer;
+    private accessor _target;
+    private accessor _rect;
+    get gfx(): import("../std/gfx/controller.js").GfxController;
+    private readonly _updateRect;
+    private _hasLink;
+    private _setTarget;
+    /** The hovered element if it carries a link, else its nearest linked group. */
+    private _resolveLinked;
+    private readonly _open;
+    private readonly _onKeydown;
+    firstUpdated(): void;
+    render(): import("lit-html").TemplateResult<1> | typeof nothing;
+}

package/dist/_pkgs/affine-widget-edgeless-selected-rect/edgeless-element-link.js

@@ -0,0 +1,233 @@
+var __esDecorate = (this && this.__esDecorate) || function (ctor, descriptorIn, decorators, contextIn, initializers, extraInitializers) {
+    function accept(f) { if (f !== void 0 && typeof f !== "function") throw new TypeError("Function expected"); return f; }
+    var kind = contextIn.kind, key = kind === "getter" ? "get" : kind === "setter" ? "set" : "value";
+    var target = !descriptorIn && ctor ? contextIn["static"] ? ctor : ctor.prototype : null;
+    var descriptor = descriptorIn || (target ? Object.getOwnPropertyDescriptor(target, contextIn.name) : {});
+    var _, done = false;
+    for (var i = decorators.length - 1; i >= 0; i--) {
+        var context = {};
+        for (var p in contextIn) context[p] = p === "access" ? {} : contextIn[p];
+        for (var p in contextIn.access) context.access[p] = contextIn.access[p];
+        context.addInitializer = function (f) { if (done) throw new TypeError("Cannot add initializers after decoration has completed"); extraInitializers.push(accept(f || null)); };
+        var result = (0, decorators[i])(kind === "accessor" ? { get: descriptor.get, set: descriptor.set } : descriptor[key], context);
+        if (kind === "accessor") {
+            if (result === void 0) continue;
+            if (result === null || typeof result !== "object") throw new TypeError("Object expected");
+            if (_ = accept(result.get)) descriptor.get = _;
+            if (_ = accept(result.set)) descriptor.set = _;
+            if (_ = accept(result.init)) initializers.unshift(_);
+        }
+        else if (_ = accept(result)) {
+            if (kind === "field") initializers.unshift(_);
+            else descriptor[key] = _;
+        }
+    }
+    if (target) Object.defineProperty(target, contextIn.name, descriptor);
+    done = true;
+};
+var __runInitializers = (this && this.__runInitializers) || function (thisArg, initializers, value) {
+    var useValue = arguments.length > 2;
+    for (var i = 0; i < initializers.length; i++) {
+        value = useValue ? initializers[i].call(thisArg, value) : initializers[i].call(thisArg);
+    }
+    return useValue ? value : void 0;
+};
+import { RefNodeSlotsProvider } from '../affine-inline-reference/index.js';
+import { requestThrottledConnectedFrame } from '../affine-shared/utils/index.js';
+import { WidgetComponent } from '../std/index.js';
+import { GfxControllerIdentifier, GfxPrimitiveElementModel, } from '../std/gfx/index.js';
+import { OpenInNewIcon, RightSidebarIcon } from '@blocksuite/icons/lit';
+import { css, html, nothing } from 'lit';
+import { state } from 'lit/decorators.js';
+import { styleMap } from 'lit/directives/style-map.js';
+export const EDGELESS_ELEMENT_LINK_WIDGET = 'edgeless-element-link';
+/**
+ * Shows a clickable arrow when hovering a drawing element that carries a link
+ * ({@link GfxPrimitiveElementModel.linkedDocId} or `.externalLink`). Clicking it
+ * opens the linked doc (host side-view via `docLinkClicked`) or the URL.
+ *
+ * ponytail: hover is resolved via `getElementByPoint`, which returns the topmost
+ * leaf — a link set on a group only shows when a child is hovered. Good enough
+ * for v1 (shapes/text/connectors are hit directly).
+ */
+let EdgelessElementLinkWidget = (() => {
+    let _classSuper = WidgetComponent;
+    let __target_decorators;
+    let __target_initializers = [];
+    let __target_extraInitializers = [];
+    let __rect_decorators;
+    let __rect_initializers = [];
+    let __rect_extraInitializers = [];
+    return class EdgelessElementLinkWidget extends _classSuper {
+        constructor() {
+            super(...arguments);
+            this._hideTimer = null;
+            this.#_target_accessor_storage = __runInitializers(this, __target_initializers, null);
+            this.#_rect_accessor_storage = (__runInitializers(this, __target_extraInitializers), __runInitializers(this, __rect_initializers, null));
+            this._updateRect = (__runInitializers(this, __rect_extraInitializers), requestThrottledConnectedFrame(() => {
+                const el = this._target;
+                if (!el) {
+                    this._rect = null;
+                    return;
+                }
+                const bound = el.elementBound;
+                const { viewport } = this.gfx;
+                const [left, top] = viewport.toViewCoord(bound.x, bound.y);
+                this._rect = {
+                    left,
+                    top,
+                    width: bound.w * viewport.zoom,
+                    height: bound.h * viewport.zoom,
+                };
+            }, this));
+            this._open = (e) => {
+                e.stopPropagation();
+                const el = this._target;
+                if (!el)
+                    return;
+                if (el.linkedDocId) {
+                    this.std.getOptional(RefNodeSlotsProvider)?.docLinkClicked.next({
+                        pageId: el.linkedDocId,
+                        host: this.std.host,
+                    });
+                }
+                else if (el.externalLink) {
+                    window.open(el.externalLink, '_blank', 'noopener,noreferrer');
+                }
+            };
+            this._onKeydown = (e) => {
+                if (e.key === 'Enter' || e.key === ' ') {
+                    e.preventDefault();
+                    this._open(e);
+                }
+            };
+        }
+        static {
+            const _metadata = typeof Symbol === "function" && Symbol.metadata ? Object.create(_classSuper[Symbol.metadata] ?? null) : void 0;
+            __target_decorators = [state()];
+            __rect_decorators = [state()];
+            __esDecorate(this, null, __target_decorators, { kind: "accessor", name: "_target", static: false, private: false, access: { has: obj => "_target" in obj, get: obj => obj._target, set: (obj, value) => { obj._target = value; } }, metadata: _metadata }, __target_initializers, __target_extraInitializers);
+            __esDecorate(this, null, __rect_decorators, { kind: "accessor", name: "_rect", static: false, private: false, access: { has: obj => "_rect" in obj, get: obj => obj._rect, set: (obj, value) => { obj._rect = value; } }, metadata: _metadata }, __rect_initializers, __rect_extraInitializers);
+            if (_metadata) Object.defineProperty(this, Symbol.metadata, { enumerable: true, configurable: true, writable: true, value: _metadata });
+        }
+        static { this.styles = css `
+    :host {
+      position: absolute;
+      top: 0;
+      left: 0;
+      z-index: 1;
+      pointer-events: none;
+    }
+
+    .open-link-button {
+      position: absolute;
+      display: flex;
+      align-items: center;
+      justify-content: center;
+      width: 24px;
+      height: 24px;
+      border-radius: 4px;
+      background: var(--affine-background-overlay-panel-color, #fff);
+      box-shadow: var(--affine-shadow-1);
+      color: var(--affine-icon-color);
+      cursor: pointer;
+      pointer-events: auto;
+      transform: translate(-50%, -50%);
+    }
+
+    .open-link-button:hover {
+      background: var(--affine-hover-color);
+    }
+
+    .open-link-button svg {
+      width: 16px;
+      height: 16px;
+    }
+  `; }
+        #_target_accessor_storage;
+        get _target() { return this.#_target_accessor_storage; }
+        set _target(value) { this.#_target_accessor_storage = value; }
+        #_rect_accessor_storage;
+        get _rect() { return this.#_rect_accessor_storage; }
+        set _rect(value) { this.#_rect_accessor_storage = value; }
+        get gfx() {
+            return this.std.get(GfxControllerIdentifier);
+        }
+        _hasLink(el) {
+            return (el instanceof GfxPrimitiveElementModel &&
+                Boolean(el.linkedDocId || el.externalLink));
+        }
+        _setTarget(el) {
+            if (el) {
+                if (this._hideTimer) {
+                    clearTimeout(this._hideTimer);
+                    this._hideTimer = null;
+                }
+                this._target = el;
+                this._updateRect();
+                return;
+            }
+            // Delay hiding so the pointer can travel from the element to the button.
+            if (this._target && !this._hideTimer) {
+                this._hideTimer = setTimeout(() => {
+                    this._hideTimer = null;
+                    this._target = null;
+                    this._rect = null;
+                }, 200);
+            }
+        }
+        /** The hovered element if it carries a link, else its nearest linked group. */
+        _resolveLinked(hit) {
+            if (this._hasLink(hit))
+                return hit;
+            const groups = hit instanceof GfxPrimitiveElementModel ? hit.groups : [];
+            for (const group of groups) {
+                if (this._hasLink(group))
+                    return group;
+            }
+            return null;
+        }
+        firstUpdated() {
+            const { _disposables, gfx } = this;
+            _disposables.add(this.std.host.event.add('pointerMove', ctx => {
+                const evt = ctx.get('pointerState');
+                const [x, y] = gfx.viewport.toModelCoord(evt.x, evt.y);
+                this._setTarget(this._resolveLinked(gfx.getElementByPoint(x, y)));
+            }));
+            _disposables.add(gfx.viewport.viewportUpdated.subscribe(() => {
+                if (this._target)
+                    this._updateRect();
+            }));
+            _disposables.add(() => {
+                if (this._hideTimer)
+                    clearTimeout(this._hideTimer);
+            });
+        }
+        render() {
+            const rect = this._rect;
+            const target = this._target;
+            if (!target || !rect)
+                return nothing;
+            const isDoc = Boolean(target.linkedDocId);
+            const label = isDoc ? 'Open linked doc' : 'Open link';
+            return html `<div
+      class="open-link-button"
+      role="button"
+      tabindex="0"
+      title=${label}
+      aria-label=${label}
+      style=${styleMap({
+                left: `${rect.left + rect.width}px`,
+                top: `${rect.top}px`,
+            })}
+      @click=${this._open}
+      @keydown=${this._onKeydown}
+      @pointerenter=${() => this._setTarget(target)}
+      @pointerleave=${() => this._setTarget(null)}
+    >
+      ${isDoc ? RightSidebarIcon() : OpenInNewIcon()}
+    </div>`;
+        }
+    };
+})();
+export { EdgelessElementLinkWidget };

package/dist/_pkgs/affine-widget-edgeless-selected-rect/effects.js

@@ -1,8 +1,10 @@
 import { EdgelessAutoCompletePanel } from './auto-complete-panel';
 import { EdgelessAutoComplete } from './edgeless-auto-complete';
+import { EDGELESS_ELEMENT_LINK_WIDGET, EdgelessElementLinkWidget, } from './edgeless-element-link';
 import { EDGELESS_SELECTED_RECT_WIDGET, EdgelessSelectedRectWidget, } from './edgeless-selected-rect';
 export function effects() {
     customElements.define('edgeless-auto-complete-panel', EdgelessAutoCompletePanel);
     customElements.define('edgeless-auto-complete', EdgelessAutoComplete);
     customElements.define(EDGELESS_SELECTED_RECT_WIDGET, EdgelessSelectedRectWidget);
+    customElements.define(EDGELESS_ELEMENT_LINK_WIDGET, EdgelessElementLinkWidget);
 }

package/dist/_pkgs/affine-widget-edgeless-selected-rect/spec.d.ts

@@ -1 +1,2 @@
 export declare const edgelessSelectedRectWidget: import("../store/index.js").ExtensionType;
+export declare const edgelessElementLinkWidget: import("../store/index.js").ExtensionType;

package/dist/_pkgs/affine-widget-edgeless-selected-rect/spec.js

@@ -1,4 +1,6 @@
 import { WidgetViewExtension } from '../std/index.js';
 import { literal, unsafeStatic } from 'lit/static-html.js';
+import { EDGELESS_ELEMENT_LINK_WIDGET } from './edgeless-element-link';
 import { EDGELESS_SELECTED_RECT_WIDGET } from './edgeless-selected-rect';
 export const edgelessSelectedRectWidget = WidgetViewExtension('affine:page', EDGELESS_SELECTED_RECT_WIDGET, literal `${unsafeStatic(EDGELESS_SELECTED_RECT_WIDGET)}`);
+export const edgelessElementLinkWidget = WidgetViewExtension('affine:page', EDGELESS_ELEMENT_LINK_WIDGET, literal `${unsafeStatic(EDGELESS_ELEMENT_LINK_WIDGET)}`);

package/dist/_pkgs/affine-widget-edgeless-selected-rect/view.js

@@ -1,6 +1,6 @@
 import { ViewExtensionProvider, } from '../affine-ext-loader/index.js';
 import { effects } from './effects';
-import { edgelessSelectedRectWidget } from './spec';
+import { edgelessElementLinkWidget, edgelessSelectedRectWidget } from './spec';
 export class EdgelessSelectedRectViewExtension extends ViewExtensionProvider {
     constructor() {
         super(...arguments);
@@ -14,6 +14,7 @@ export class EdgelessSelectedRectViewExtension extends ViewExtensionProvider {
         super.setup(context);
         if (this.isEdgeless(context.scope)) {
             context.register(edgelessSelectedRectWidget);
+            context.register(edgelessElementLinkWidget);
         }
     }
 }

package/dist/_pkgs/data-view/core/data-source/base.d.ts

@@ -129,4 +129,10 @@ export declare abstract class DataSourceBase implements DataSource {
         index: number;
     } | undefined;
     isFixedProperty(propertyId: string): boolean;
+    /**
+     * Tear down anything the source subscribed to (e.g. external observers).
+     * No-op by default — the inline blob source holds no subscriptions. The
+     * owning block calls this when it rebuilds the source or disconnects.
+     */
+    dispose(): void;
 }

package/dist/_pkgs/data-view/core/data-source/base.js

@@ -80,4 +80,10 @@ export class DataSourceBase {
         }
         return false;
     }
+    /**
+     * Tear down anything the source subscribed to (e.g. external observers).
+     * No-op by default — the inline blob source holds no subscriptions. The
+     * owning block calls this when it rebuilds the source or disconnects.
+     */
+    dispose() { }
 }

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

@@ -6,5 +6,6 @@ export * from './flavour.js';
 export * from './keymap.js';
 export * from './lifecycle-watcher.js';
 export * from './service.js';
+export * from './shortcut.js';
 export * from './service-manager.js';
 export * from './widget-view-map.js';

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

@@ -6,5 +6,6 @@ export * from './flavour.js';
 export * from './keymap.js';
 export * from './lifecycle-watcher.js';
 export * from './service.js';
+export * from './shortcut.js';
 export * from './service-manager.js';
 export * from './widget-view-map.js';

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

@@ -0,0 +1,69 @@
+import type { ExtensionType } from '../../store/index.js';
+import type { UIEventHandler } from '../event/index.js';
+import type { BlockStdScope } from '../scope/index.js';
+export type ShortcutScope = 'global' | 'page' | 'edgeless';
+/**
+ * An enumerable, rebindable keyboard shortcut. A descriptor is both a manifest
+ * entry (for a host "Shortcuts" settings panel) and the source of the actual
+ * binding. The `handler` is a factory receiving the std scope (mirroring
+ * {@link KeymapExtension}); the manifest the host consumes only needs the
+ * metadata fields, not the handler.
+ */
+export interface ShortcutDescriptor {
+    /** Stable id, e.g. `'undo'`, `'wardley.addNode'`. */
+    id: string;
+    /** i18n key; the label is resolved by the host. */
+    labelKey: string;
+    /** Default key combos per platform, each as an array, e.g. `['Mod', 'z']`. */
+    defaultKeys: {
+        mac: string[];
+        other: string[];
+    };
+    scope: ShortcutScope;
+    /** `'core'` or the owning optional-block flag, for per-framework filtering. */
+    owner: string;
+    /** Optional activation context (host-interpreted). */
+    when?: string;
+    handler: (std: BlockStdScope) => UIEventHandler;
+}
+/** Host-provided rebinding table: combo array per id, or `'disabled'`. */
+export type ShortcutOverrides = Record<string, string[] | 'disabled'>;
+export interface ShortcutConflict {
+    /** Canonical combo that more than one shortcut resolved to. */
+    combo: string;
+    scope: ShortcutScope;
+    /** Ids competing for the combo (first is the one actually bound). */
+    ids: string[];
+}
+export type ShortcutConflictReporter = (conflicts: ShortcutConflict[]) => void;
+/**
+ * Register shortcut descriptors. Each becomes a manifest entry and, once the
+ * installer ({@link ShortcutKeymapExtension}) runs, an effective binding.
+ */
+export declare function ShortcutExtension(descriptors: ShortcutDescriptor[]): ExtensionType;
+/**
+ * Canonicalize a combo (array of keys) so equivalent spellings compare equal:
+ * modifiers are lowercased/sorted and `Mod` resolves to the platform modifier;
+ * the final key is lowercased (Shift is a separate modifier).
+ */
+export declare function canonicalCombo(keys: string[]): string;
+/**
+ * Build the effective keymap for one scope from the registered descriptors and
+ * the override table. `'disabled'` ids are dropped; combo conflicts within the
+ * scope are reported (and only the first descriptor for a combo is bound — the
+ * duplicates are never bound silently).
+ */
+export declare function resolveKeymap(descriptors: ShortcutDescriptor[], overrides: ShortcutOverrides, scope: ShortcutScope, std: BlockStdScope): {
+    keymap: Record<string, UIEventHandler>;
+    conflicts: ShortcutConflict[];
+};
+/**
+ * Install the effective keymap for a scope. Reads every registered
+ * {@link ShortcutDescriptor} plus the host override table, resolves conflicts,
+ * and binds via the normal dispatcher keymap mechanism. Re-runs whenever the
+ * specs are rebuilt (e.g. a framework is toggled on/off).
+ *
+ * Only `'global'` scope is wired today; `'page'`/`'edgeless'` scoping is a
+ * follow-up.
+ */
+export declare function ShortcutKeymapExtension(scope?: ShortcutScope): ExtensionType;

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

@@ -0,0 +1,106 @@
+import { IS_MAC } from '../../global/env/index.js';
+import { ShortcutConflictReporterIdentifier, ShortcutIdentifier, ShortcutOverrideIdentifier, } from '../identifier.js';
+import { KeymapExtension } from './keymap.js';
+let _shortcutId = 1;
+/**
+ * Register shortcut descriptors. Each becomes a manifest entry and, once the
+ * installer ({@link ShortcutKeymapExtension}) runs, an effective binding.
+ */
+export function ShortcutExtension(descriptors) {
+    return {
+        setup: di => {
+            descriptors.forEach(descriptor => {
+                di.addImpl(ShortcutIdentifier(`Shortcut-${_shortcutId++}`), descriptor);
+            });
+        },
+    };
+}
+const platformKeys = (d) => IS_MAC ? d.defaultKeys.mac : d.defaultKeys.other;
+/**
+ * Canonicalize a combo (array of keys) so equivalent spellings compare equal:
+ * modifiers are lowercased/sorted and `Mod` resolves to the platform modifier;
+ * the final key is lowercased (Shift is a separate modifier).
+ */
+export function canonicalCombo(keys) {
+    const key = (keys.at(-1) ?? '').toLowerCase();
+    const mods = keys
+        .slice(0, -1)
+        .map(m => {
+        const l = m.toLowerCase();
+        if (l === 'mod')
+            return IS_MAC ? 'meta' : 'ctrl';
+        if (l === 'cmd' || l === 'm' || l === 'meta')
+            return 'meta';
+        if (l === 'control' || l === 'c' || l === 'ctrl')
+            return 'ctrl';
+        if (l === 'a' || l === 'alt')
+            return 'alt';
+        if (l === 's' || l === 'shift')
+            return 'shift';
+        return l;
+    })
+        .sort();
+    return [...mods, key].join('-');
+}
+/**
+ * Build the effective keymap for one scope from the registered descriptors and
+ * the override table. `'disabled'` ids are dropped; combo conflicts within the
+ * scope are reported (and only the first descriptor for a combo is bound — the
+ * duplicates are never bound silently).
+ */
+export function resolveKeymap(descriptors, overrides, scope, std) {
+    const keymap = {};
+    const conflicts = [];
+    const boundBy = new Map(); // canonical combo -> bound id
+    for (const d of descriptors) {
+        if (d.scope !== scope)
+            continue;
+        const override = overrides[d.id];
+        if (override === 'disabled')
+            continue;
+        const keys = override ?? platformKeys(d);
+        if (!keys.length)
+            continue;
+        const canonical = canonicalCombo(keys);
+        const existing = boundBy.get(canonical);
+        if (existing) {
+            const conflict = conflicts.find(c => c.combo === canonical);
+            if (conflict) {
+                if (!conflict.ids.includes(d.id))
+                    conflict.ids.push(d.id);
+            }
+            else {
+                conflicts.push({ combo: canonical, scope, ids: [existing, d.id] });
+            }
+            continue; // do not silently bind a second action to the same combo
+        }
+        boundBy.set(canonical, d.id);
+        keymap[keys.join('-')] = d.handler(std);
+    }
+    return { keymap, conflicts };
+}
+/**
+ * Install the effective keymap for a scope. Reads every registered
+ * {@link ShortcutDescriptor} plus the host override table, resolves conflicts,
+ * and binds via the normal dispatcher keymap mechanism. Re-runs whenever the
+ * specs are rebuilt (e.g. a framework is toggled on/off).
+ *
+ * Only `'global'` scope is wired today; `'page'`/`'edgeless'` scoping is a
+ * follow-up.
+ */
+export function ShortcutKeymapExtension(scope = 'global') {
+    // No flavour/blockId option → a global keymap (like `fallbackKeymap`).
+    return KeymapExtension(std => {
+        const descriptors = [...std.provider.getAll(ShortcutIdentifier).values()];
+        const overrides = std.getOptional(ShortcutOverrideIdentifier) ?? {};
+        const { keymap, conflicts } = resolveKeymap(descriptors, overrides, scope, std);
+        if (conflicts.length) {
+            const report = std.getOptional(ShortcutConflictReporterIdentifier);
+            if (report)
+                report(conflicts);
+            else
+                console.warn('[shortcut] combo conflicts (duplicates not bound):', conflicts);
+        }
+        return keymap;
+    });
+}