@formicoidea/labre-core 0.32.0 → 0.33.0

package/dist/_pkgs/std/gfx/model/surface/element-model.d.ts

@@ -34,6 +34,100 @@ export type ValidationException = {
     /** Epoch ms, taken at the moment of the gesture. */
     at: number;
 };
+/**
+ * A SCOPE: which part of the source document a carried fragment came off.
+ *
+ * One Labre element routinely stands for several source elements — a BPMN pool
+ * is a `participant` AND its `process`, plus a `laneSet`, every `lane`, the
+ * `BPMNShape` that draws it, and (for the first pool of a document) the
+ * `collaboration` and `definitions` themselves. Everything they carry lands in
+ * ONE payload, so an unscoped `Record<name, value>` has two defects, and the
+ * first one destroys data: two lanes carrying the same foreign attribute
+ * overwrite each other silently, and nothing records which element an attribute
+ * belonged to, so no exporter can ever put it back where it came from.
+ *
+ * A scope is therefore either of exactly two things, and they cannot collide:
+ *
+ * - **the source element's id, verbatim** — the normal case, and the one that
+ *   lets an exporter put a fragment back on the element that had it;
+ * - **an `@`-prefixed ROLE key** for a source element with no id of its own, or
+ *   one whose identity is its relation to this element rather than a name:
+ *   `@self` (the element this payload is on), `@shape` (the diagram element
+ *   that draws it), and whatever else the format needs. **`@` is not an XML
+ *   NameStartChar**, so a role key can never be mistaken for an id, whatever a
+ *   file calls its elements.
+ *
+ * The role vocabulary past `@self` and `@shape` belongs to each format's
+ * importer, which is the only thing that knows what parts a document has;
+ * `.bpmn`'s is documented in `gfx/bpmn/src/import.ts`. The base model stores
+ * strings and never learns what any of them mean.
+ */
+export type InterchangeScope = string;
+/**
+ * Verbatim foreign matter one interchange import kept on one element, for one
+ * format (ADR 0012 § D2).
+ *
+ * Document DATA in the same sense {@link ValidationException} is: it records
+ * what a file actually said, so it outlives the tab, the framework flag and the
+ * client version that imported it. Deliberately format-agnostic — the base
+ * model stores fragments and attributes, and never learns what they mean.
+ *
+ * Every member is optional and absent rather than empty: an importer writes the
+ * ones it has, and a reader that finds none of them has an element that met an
+ * import and carried nothing.
+ *
+ * The three carrying members are keyed by {@link InterchangeScope}, so that
+ * what came off two different source elements stays apart. That shape is what
+ * makes the payload sufficient for re-emission, and it is the one thing here
+ * that could not be changed later: this value is persisted, so a document
+ * written under a shape that loses data cannot be repaired without the original
+ * file. One `Y.Map` entry all the same — the whole record is written once, as a
+ * blob, and never mutated.
+ */
+export type ForeignInterchange = {
+    /**
+     * The element's id in the SOURCE file, verbatim. The surface element keeps
+     * its own nanoid — surface identity is Labre's and never the file's — and an
+     * export prefers this id back when it is still usable, which is what makes
+     * the id map a fixed point after one cycle (ADR 0012 § D3).
+     */
+    id?: string;
+    /**
+     * The source element's name, when the element itself was CARRIED rather than
+     * mapped, e.g. `bpmn:boundaryEvent`.
+     */
+    element?: string;
+    /**
+     * Attributes the importer does not model — foreign-namespaced and standard
+     * alike — by {@link InterchangeScope}, then by attribute name.
+     *
+     * `{ 'Lane_1': { 'camunda:owner': 'alice' }, 'Lane_2': { 'camunda:owner':
+     * 'bob' } }`: two lanes of one pool, two owners, and both still here.
+     */
+    attrs?: Record<InterchangeScope, Record<string, string>>;
+    /**
+     * Child fragments, serialized — extension subtrees, unmodelled children, and
+     * whole carried elements — by the {@link InterchangeScope} of the element
+     * they were children OF. The scope is where an exporter has to put them back.
+     */
+    children?: Record<InterchangeScope, string[]>;
+    /**
+     * Diagram-interchange fragments, by the {@link InterchangeScope} of what they
+     * draw: `@shape` for the parts of this element's own diagram element that the
+     * importer did not model, a source id for the diagram of something carried.
+     */
+    di?: Record<InterchangeScope, string[]>;
+    /**
+     * Fragments kept but deliberately NOT re-emitted, each with the reason
+     * (ADR 0012 § D5). Preserved so a reader can see what was dropped and why;
+     * never a place the exporter reads for output — which is why this one is a
+     * flat list and needs no scope: nothing has to know where to put it back.
+     */
+    quarantined?: {
+        fragment: string;
+        reason: string;
+    }[];
+};
 export type SerializedElement = Record<string, unknown> & {
     type: string;
     xywh: SerializedXYWH;
@@ -351,6 +445,72 @@ export declare abstract class GfxPrimitiveElementModel<Props extends BaseElement
      * not pruned: the tooling comes and goes with a flag, the decision does not.
      */
     accessor qualityChecklist: string[] | undefined;
+    /**
+     * Verbatim foreign matter from an interchange import, keyed by FORMAT id
+     * (`bpmn`, `owm`, …) — never by framework, because a `.bpmn` and an OWM file
+     * make different promises about the same element (ADR 0012 § D2).
+     *
+     * This field is dumb storage, and that is the whole design. ADR 0012 sorts
+     * every node of an imported file into three states — **mapped** (there is a
+     * Labre artefact, re-emitted from the drawing), **carried** (no artefact,
+     * kept verbatim here, re-emitted in place) and **quarantined** (kept, but
+     * re-emitting it would contradict the document, so it is not). That contract
+     * lives entirely in the importers and exporters; the base model neither
+     * classifies, validates, dereferences nor re-emits anything, and knows no
+     * format. No renderer, hit-test, layout or `@derive` / `@convert` chain reads
+     * it, so nothing here can move, resize or restyle an element.
+     *
+     * Declared on the BASE class for the same reason as {@link role} and
+     * {@link validationExceptions}, and for one more: a BPMN `sequenceFlow`
+     * carrying a `conditionExpression` is a plain **connector**, and
+     * `ConnectorElementModel` is shared plumbing that will never be a BPMN class.
+     * An element re-created from props (paste, duplicate, alt-drag clone,
+     * template insertion) only reaches the Y.Map through keys that have a
+     * declared accessor, so a payload declared per subclass would be silently
+     * dropped on copy — the exact loss `docs/spikes/us-1-8-unknown-props-preservation.md`
+     * exists to prevent. Declaring it, rather than leaning on that spike's
+     * verbatim fallback for undeclared keys, is what makes it a contract: a field
+     * nothing declares is a field nothing can test, strip or find.
+     *
+     * `undefined` = this element never met an import, and no key is written for
+     * it, so it stays byte-identical to one created before the field existed:
+     * optional field, no schema version bump, no migration. An import writes no
+     * key for a visual-tier capability, and none for an element that carried
+     * nothing. Clearing goes through {@link clearField}, which removes the key
+     * rather than leaving a tombstone.
+     *
+     * Flat JSON on purpose — a value a Yjs update can encode is the contract
+     * enforced by `_assignElementProp`, and the whole payload is ONE Y.Map entry,
+     * written once at import and never mutated afterwards. Two peers writing it
+     * concurrently therefore resolve last-write-wins on the whole blob, which is
+     * `lanes`' trade (ADR 0007): nobody edits this value, so the window is the
+     * import itself.
+     *
+     * ## Writing it, for the importer
+     *
+     * - **Write the whole blob in one assignment**, the way an import already
+     *   produces it. Never read-modify-write it key by key: the Y.Map entry is the
+     *   entire `Record`, so a partial update is still a last-write-wins overwrite
+     *   of everything, and two of them racing lose a whole format's payload rather
+     *   than merging.
+     * - **Key what you carry by its {@link InterchangeScope}.** One Labre element
+     *   stands for several source elements, and an unscoped map lets what came off
+     *   one overwrite what came off another — a silent loss, into a persisted
+     *   value, of exactly the data this field exists to keep. The scope is also
+     *   the only record of where a fragment has to be put back.
+     * - **Write no key at all** when there is nothing to carry — an element the
+     *   import mapped cleanly, or any visual-tier capability, which by contract
+     *   writes none (ADR 0012 P2). Absent and empty are NOT equivalent here:
+     *   `{}` costs every element a Y.Map entry and makes P2's "writes no
+     *   `interchange` key" untestable.
+     * - **Removing it is {@link clearField}**, never an assignment to `undefined`
+     *   — the former deletes the key, the latter can leave a tombstone.
+     * - **Nothing caps the size of this value** (ADR 0012, open question 3). A
+     *   pathological file would produce a document that is mostly foreign matter;
+     *   a cap that dropped data would contradict D2, so the only honest cap is a
+     *   refusal at import time. That is the importer's call, not the model's.
+     */
+    accessor interchange: Record<string, ForeignInterchange> | undefined;
     accessor lockedBySelf: boolean | undefined;
     accessor opacity: number;
     accessor responseExtension: [number, number];

package/dist/_pkgs/std/gfx/model/surface/element-model.js

@@ -127,6 +127,9 @@ let GfxPrimitiveElementModel = (() => {
     let _qualityChecklist_decorators;
     let _qualityChecklist_initializers = [];
     let _qualityChecklist_extraInitializers = [];
+    let _interchange_decorators;
+    let _interchange_initializers = [];
+    let _interchange_extraInitializers = [];
     let _lockedBySelf_decorators;
     let _lockedBySelf_initializers = [];
     let _lockedBySelf_extraInitializers = [];
@@ -156,6 +159,7 @@ let GfxPrimitiveElementModel = (() => {
             _validationExceptions_decorators = [field()];
             _validationProfile_decorators = [field()];
             _qualityChecklist_decorators = [field()];
+            _interchange_decorators = [field()];
             _lockedBySelf_decorators = [field()];
             _opacity_decorators = [local()];
             _responseExtension_decorators = [local()];
@@ -172,6 +176,7 @@ let GfxPrimitiveElementModel = (() => {
             __esDecorate(this, null, _validationExceptions_decorators, { kind: "accessor", name: "validationExceptions", static: false, private: false, access: { has: obj => "validationExceptions" in obj, get: obj => obj.validationExceptions, set: (obj, value) => { obj.validationExceptions = value; } }, metadata: _metadata }, _validationExceptions_initializers, _validationExceptions_extraInitializers);
             __esDecorate(this, null, _validationProfile_decorators, { kind: "accessor", name: "validationProfile", static: false, private: false, access: { has: obj => "validationProfile" in obj, get: obj => obj.validationProfile, set: (obj, value) => { obj.validationProfile = value; } }, metadata: _metadata }, _validationProfile_initializers, _validationProfile_extraInitializers);
             __esDecorate(this, null, _qualityChecklist_decorators, { kind: "accessor", name: "qualityChecklist", static: false, private: false, access: { has: obj => "qualityChecklist" in obj, get: obj => obj.qualityChecklist, set: (obj, value) => { obj.qualityChecklist = value; } }, metadata: _metadata }, _qualityChecklist_initializers, _qualityChecklist_extraInitializers);
+            __esDecorate(this, null, _interchange_decorators, { kind: "accessor", name: "interchange", static: false, private: false, access: { has: obj => "interchange" in obj, get: obj => obj.interchange, set: (obj, value) => { obj.interchange = value; } }, metadata: _metadata }, _interchange_initializers, _interchange_extraInitializers);
             __esDecorate(this, null, _lockedBySelf_decorators, { kind: "accessor", name: "lockedBySelf", static: false, private: false, access: { has: obj => "lockedBySelf" in obj, get: obj => obj.lockedBySelf, set: (obj, value) => { obj.lockedBySelf = value; } }, metadata: _metadata }, _lockedBySelf_initializers, _lockedBySelf_extraInitializers);
             __esDecorate(this, null, _opacity_decorators, { kind: "accessor", name: "opacity", static: false, private: false, access: { has: obj => "opacity" in obj, get: obj => obj.opacity, set: (obj, value) => { obj.opacity = value; } }, metadata: _metadata }, _opacity_initializers, _opacity_extraInitializers);
             __esDecorate(this, null, _responseExtension_decorators, { kind: "accessor", name: "responseExtension", static: false, private: false, access: { has: obj => "responseExtension" in obj, get: obj => obj.responseExtension, set: (obj, value) => { obj.responseExtension = value; } }, metadata: _metadata }, _responseExtension_initializers, _responseExtension_extraInitializers);
@@ -260,7 +265,8 @@ let GfxPrimitiveElementModel = (() => {
             this.#validationExceptions_accessor_storage = (__runInitializers(this, _tags_extraInitializers), __runInitializers(this, _validationExceptions_initializers, undefined));
             this.#validationProfile_accessor_storage = (__runInitializers(this, _validationExceptions_extraInitializers), __runInitializers(this, _validationProfile_initializers, undefined));
             this.#qualityChecklist_accessor_storage = (__runInitializers(this, _validationProfile_extraInitializers), __runInitializers(this, _qualityChecklist_initializers, undefined));
-            this.#lockedBySelf_accessor_storage = (__runInitializers(this, _qualityChecklist_extraInitializers), __runInitializers(this, _lockedBySelf_initializers, false));
+            this.#interchange_accessor_storage = (__runInitializers(this, _qualityChecklist_extraInitializers), __runInitializers(this, _interchange_initializers, undefined));
+            this.#lockedBySelf_accessor_storage = (__runInitializers(this, _interchange_extraInitializers), __runInitializers(this, _lockedBySelf_initializers, false));
             this.#opacity_accessor_storage = (__runInitializers(this, _lockedBySelf_extraInitializers), __runInitializers(this, _opacity_initializers, 1));
             this.#responseExtension_accessor_storage = (__runInitializers(this, _opacity_extraInitializers), __runInitializers(this, _responseExtension_initializers, [0, 0]));
             this.#seed_accessor_storage = (__runInitializers(this, _responseExtension_extraInitializers), __runInitializers(this, _seed_initializers, void 0));
@@ -663,6 +669,74 @@ let GfxPrimitiveElementModel = (() => {
          */
         get qualityChecklist() { return this.#qualityChecklist_accessor_storage; }
         set qualityChecklist(value) { this.#qualityChecklist_accessor_storage = value; }
+        #interchange_accessor_storage;
+        /**
+         * Verbatim foreign matter from an interchange import, keyed by FORMAT id
+         * (`bpmn`, `owm`, …) — never by framework, because a `.bpmn` and an OWM file
+         * make different promises about the same element (ADR 0012 § D2).
+         *
+         * This field is dumb storage, and that is the whole design. ADR 0012 sorts
+         * every node of an imported file into three states — **mapped** (there is a
+         * Labre artefact, re-emitted from the drawing), **carried** (no artefact,
+         * kept verbatim here, re-emitted in place) and **quarantined** (kept, but
+         * re-emitting it would contradict the document, so it is not). That contract
+         * lives entirely in the importers and exporters; the base model neither
+         * classifies, validates, dereferences nor re-emits anything, and knows no
+         * format. No renderer, hit-test, layout or `@derive` / `@convert` chain reads
+         * it, so nothing here can move, resize or restyle an element.
+         *
+         * Declared on the BASE class for the same reason as {@link role} and
+         * {@link validationExceptions}, and for one more: a BPMN `sequenceFlow`
+         * carrying a `conditionExpression` is a plain **connector**, and
+         * `ConnectorElementModel` is shared plumbing that will never be a BPMN class.
+         * An element re-created from props (paste, duplicate, alt-drag clone,
+         * template insertion) only reaches the Y.Map through keys that have a
+         * declared accessor, so a payload declared per subclass would be silently
+         * dropped on copy — the exact loss `docs/spikes/us-1-8-unknown-props-preservation.md`
+         * exists to prevent. Declaring it, rather than leaning on that spike's
+         * verbatim fallback for undeclared keys, is what makes it a contract: a field
+         * nothing declares is a field nothing can test, strip or find.
+         *
+         * `undefined` = this element never met an import, and no key is written for
+         * it, so it stays byte-identical to one created before the field existed:
+         * optional field, no schema version bump, no migration. An import writes no
+         * key for a visual-tier capability, and none for an element that carried
+         * nothing. Clearing goes through {@link clearField}, which removes the key
+         * rather than leaving a tombstone.
+         *
+         * Flat JSON on purpose — a value a Yjs update can encode is the contract
+         * enforced by `_assignElementProp`, and the whole payload is ONE Y.Map entry,
+         * written once at import and never mutated afterwards. Two peers writing it
+         * concurrently therefore resolve last-write-wins on the whole blob, which is
+         * `lanes`' trade (ADR 0007): nobody edits this value, so the window is the
+         * import itself.
+         *
+         * ## Writing it, for the importer
+         *
+         * - **Write the whole blob in one assignment**, the way an import already
+         *   produces it. Never read-modify-write it key by key: the Y.Map entry is the
+         *   entire `Record`, so a partial update is still a last-write-wins overwrite
+         *   of everything, and two of them racing lose a whole format's payload rather
+         *   than merging.
+         * - **Key what you carry by its {@link InterchangeScope}.** One Labre element
+         *   stands for several source elements, and an unscoped map lets what came off
+         *   one overwrite what came off another — a silent loss, into a persisted
+         *   value, of exactly the data this field exists to keep. The scope is also
+         *   the only record of where a fragment has to be put back.
+         * - **Write no key at all** when there is nothing to carry — an element the
+         *   import mapped cleanly, or any visual-tier capability, which by contract
+         *   writes none (ADR 0012 P2). Absent and empty are NOT equivalent here:
+         *   `{}` costs every element a Y.Map entry and makes P2's "writes no
+         *   `interchange` key" untestable.
+         * - **Removing it is {@link clearField}**, never an assignment to `undefined`
+         *   — the former deletes the key, the latter can leave a tombstone.
+         * - **Nothing caps the size of this value** (ADR 0012, open question 3). A
+         *   pathological file would produce a document that is mostly foreign matter;
+         *   a cap that dropped data would contradict D2, so the only honest cap is a
+         *   refusal at import time. That is the importer's call, not the model's.
+         */
+        get interchange() { return this.#interchange_accessor_storage; }
+        set interchange(value) { this.#interchange_accessor_storage = value; }
         #lockedBySelf_accessor_storage;
         get lockedBySelf() { return this.#lockedBySelf_accessor_storage; }
         set lockedBySelf(value) { this.#lockedBySelf_accessor_storage = value; }

package/dist/_pkgs/std/gfx/model/surface/role.js

@@ -20,9 +20,11 @@
  */
 import { createIdentifier } from '../../../../global/di/index.js';
 /**
- * Deepest specialisation chain {@link roleIsA} walks. Real vocabularies are
- * one or two levels deep; the bound exists so a malformed `parent` cycle
- * cannot hang the caller. Chains longer than this are NOT supported.
+ * Deepest specialisation chain {@link roleIsA} walks. Real vocabularies run two
+ * or three levels deep — BPMN's descriptive profile is three on two branches
+ * (`bpmn:message-start-event` → `bpmn:start-event` → `bpmn:event`) — and the
+ * bound is far above them, so that a malformed `parent` cycle cannot hang the
+ * caller. Chains longer than this are NOT supported.
  */
 const MAX_ROLE_DEPTH = 32;
 /**

package/dist/_pkgs/std/gfx/model/surface/surface-model.js

@@ -67,7 +67,8 @@ const UNSAFE_ELEMENT_PROP_KEYS = new Set([
  * (data descriptor, no setter) and a getter-only accessor both answer `false`.
  */
 function isDeclaredElementProp(element, key) {
-    if (getFieldPropsSet(element).has(key) || getLocalPropsSet(element).has(key)) {
+    if (getFieldPropsSet(element).has(key) ||
+        getLocalPropsSet(element).has(key)) {
         return true;
     }
     for (let proto = Object.getPrototypeOf(element); proto !== null; proto = Object.getPrototypeOf(proto)) {

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

@@ -1,5 +1,5 @@
 import { DisposableGroup } from '../../global/disposable/index.js';
-import { getCommonBoundWithRotation, } from '../../global/gfx/index.js';
+import { getCommonBoundWithRotation } from '../../global/gfx/index.js';
 import { assertType } from '../../global/utils/index.js';
 import groupBy from 'lodash-es/groupBy.js';
 import { Subject } from 'rxjs';

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

@@ -1,4 +1,4 @@
-import { Bound, clamp, Vec, } from '../../global/gfx/index.js';
+import { Bound, clamp, Vec } from '../../global/gfx/index.js';
 import debounce from 'lodash-es/debounce.js';
 import { BehaviorSubject, debounceTime, Subject } from 'rxjs';
 function cutoff(value, ref, sign) {

package/dist/_pkgs/std/inline/extensions/inline-manager.js

@@ -1,4 +1,4 @@
-import { createIdentifier, } from '../../../global/di/index.js';
+import { createIdentifier } from '../../../global/di/index.js';
 import { baseTextAttributes, } from '../../../store/index.js';
 import { z } from 'zod';
 import { StdIdentifier } from '../../identifier.js';

package/dist/_pkgs/std/inline/extensions/markdown-matcher.js

@@ -1,4 +1,4 @@
-import { createIdentifier, } from '../../../global/di/index.js';
+import { createIdentifier } from '../../../global/di/index.js';
 export const MarkdownMatcherIdentifier = createIdentifier('AffineMarkdownMatcher');
 export function InlineMarkdownExtension(matcher) {
     const identifier = MarkdownMatcherIdentifier(matcher.name);

package/dist/_pkgs/store/model/store/crud.js

@@ -195,7 +195,10 @@ export class DocCRUD {
             // be answered before indexing.
             if (index === 0)
                 return null;
-            return parent.get('sys:children').toArray().at(index - 1) ?? null;
+            return (parent
+                .get('sys:children')
+                .toArray()
+                .at(index - 1) ?? null);
         });
     }
     moveBlocks(blocksToMove, newParent, targetSibling = null, shouldInsertBeforeSibling = true) {

package/dist/commands.js

@@ -1,5 +1,5 @@
 import { coreCommands, pivotCommands, readingCommands, tagCommands, } from './_pkgs/affine-block-root/index.js';
-import { auditCommands, mapQualityCommands, } from './_pkgs/affine-block-surface/index.js';
+import { auditCommands, mapQualityCommands } from './_pkgs/affine-block-surface/index.js';
 import { edgeDirectionCommands } from './_pkgs/affine-gfx-connector/index.js';
 import { shapeCommands } from './_pkgs/affine-gfx-shape/index.js';
 import { toCommandManifestEntry, } from './_pkgs/std/index.js';

package/dist/extensions/command-usage.d.ts

@@ -0,0 +1,23 @@
+import { type ViewExtensionContext, ViewExtensionProvider } from '../_pkgs/affine-ext-loader/index.js';
+import type { ExtensionType } from '../_pkgs/store/index.js';
+/**
+ * The DEFAULT command usage measure: `localStorage`, this browser only.
+ *
+ * `runCommand` records every invocation into whatever answers
+ * `CommandUsageIdentifier`; without a default nothing would be measured at all
+ * until a host wired a store, and PF6's "seven most-recent + six most-used"
+ * sub-menu would have nothing to rank in a standalone editor. A host that owns
+ * a per-user database replaces this with `CommandUsageExtension(store)`, whose
+ * `di.override` beats the `addImpl` below.
+ */
+export declare const CommandUsageDefaultExtension: ExtensionType;
+/**
+ * Registered unconditionally by `getInternalViewExtensions`, next to
+ * `CommandTelemetryViewExtension` and for the same reason: measuring which
+ * commands a user reaches for is not a framework's business, and a framework
+ * toggled off simply never invokes a command.
+ */
+export declare class CommandUsageViewExtension extends ViewExtensionProvider {
+    name: string;
+    setup(context: ViewExtensionContext): void;
+}

package/dist/extensions/command-usage.js

@@ -0,0 +1,37 @@
+import { ViewExtensionProvider, } from '../_pkgs/affine-ext-loader/index.js';
+import { createLocalCommandUsageStore } from '../_pkgs/affine-shared/services/index.js';
+import { CommandUsageIdentifier } from '../_pkgs/std/index.js';
+/**
+ * The DEFAULT command usage measure: `localStorage`, this browser only.
+ *
+ * `runCommand` records every invocation into whatever answers
+ * `CommandUsageIdentifier`; without a default nothing would be measured at all
+ * until a host wired a store, and PF6's "seven most-recent + six most-used"
+ * sub-menu would have nothing to rank in a standalone editor. A host that owns
+ * a per-user database replaces this with `CommandUsageExtension(store)`, whose
+ * `di.override` beats the `addImpl` below.
+ */
+export const CommandUsageDefaultExtension = {
+    // Factory form, not value form — as for the telemetry reporter: the container
+    // calls a function argument as a factory, so the store is built here and the
+    // service provider is never passed to it.
+    setup: di => {
+        di.addImpl(CommandUsageIdentifier, () => createLocalCommandUsageStore());
+    },
+};
+/**
+ * Registered unconditionally by `getInternalViewExtensions`, next to
+ * `CommandTelemetryViewExtension` and for the same reason: measuring which
+ * commands a user reaches for is not a framework's business, and a framework
+ * toggled off simply never invokes a command.
+ */
+export class CommandUsageViewExtension extends ViewExtensionProvider {
+    constructor() {
+        super(...arguments);
+        this.name = 'affine-command-usage';
+    }
+    setup(context) {
+        super.setup(context);
+        context.register(CommandUsageDefaultExtension);
+    }
+}

package/dist/extensions/view.js

@@ -58,6 +58,7 @@ import { ToolbarViewExtension } from '../_pkgs/affine-widget-toolbar/view.js';
 import { ViewportOverlayViewExtension } from '../_pkgs/affine-widget-viewport-overlay/view.js';
 import { isBlockEnabled, isCapabilityEnabled, } from '../flags.js';
 import { CommandTelemetryViewExtension } from './command-telemetry.js';
+import { CommandUsageViewExtension } from './command-usage.js';
 /**
  * View extensions.
  *
@@ -74,9 +75,20 @@ export function getInternalViewExtensions(flags) {
         // The single command-telemetry emitter. Unconditional: a disabled
         // framework simply never invokes a command (docs/adr/0008).
         CommandTelemetryViewExtension,
+        // The default (browser-local) recency/frequency measure. Unconditional for
+        // the same reason, and independent of telemetry: it feeds an in-editor
+        // ranking, not a dashboard (docs/adr/0008).
+        CommandUsageViewExtension,
         // Gfx — each framework contributes an always-on `…Render…` extension
         // (element view + renderer + interaction + contextual toolbar) and a
         // flag-gated tooling extension (senior button + creation shortcuts).
+        //
+        // The eight business frameworks are registered as PAIRS, in the order their
+        // senior buttons must read left to right: no framework declares a
+        // `SeniorTool.order`, so they all share the default group and the row is
+        // sorted stably — i.e. left in registration order. The single source of that
+        // order is `FRAMEWORK_DESCRIPTORS`, and `senior-row-order.unit.spec.ts` pins
+        // the two lists together.
         PointerViewExtension,
         GfxNoteViewExtension,
         BrushRenderViewExtension,

package/dist/frameworks.js

@@ -2,6 +2,7 @@ export const FRAMEWORK_DESCRIPTORS = [
     {
         id: 'wardley',
         labelKey: 'com.labre.framework.wardley',
+        labelFallback: 'Wardley map',
         iconKey: 'wardley.toolbar',
         // The only allocated chord prefix: `w` was free against
         // RESERVED_EDGELESS_KEYS. The other six frameworks ship no chord, so they
@@ -26,6 +27,7 @@ export const FRAMEWORK_DESCRIPTORS = [
     {
         id: 'edgy',
         labelKey: 'com.labre.framework.edgy',
+        labelFallback: 'EDGY',
         iconKey: 'edgy.toolbar',
         telemetryKey: 'edgy',
         telemetrySegment: 'edgy toolbox',
@@ -43,6 +45,7 @@ export const FRAMEWORK_DESCRIPTORS = [
     {
         id: 'cynefin-estuarine',
         labelKey: 'com.labre.framework.cynefin-estuarine',
+        labelFallback: 'Cynefin / Estuarine',
         iconKey: 'cynefin.toolbar',
         // Historical PostHog value; the flag and the owner say
         // `cynefin-estuarine`, the wire says `cynefin`.
@@ -66,6 +69,7 @@ export const FRAMEWORK_DESCRIPTORS = [
     {
         id: 'bpmn',
         labelKey: 'com.labre.framework.bpmn',
+        labelFallback: 'BPMN',
         iconKey: 'bpmn.toolbar',
         telemetryKey: 'bpmn',
         telemetrySegment: 'bpmn toolbox',
@@ -83,6 +87,7 @@ export const FRAMEWORK_DESCRIPTORS = [
     {
         id: 'ddd-event-storming',
         labelKey: 'com.labre.framework.ddd-event-storming',
+        labelFallback: 'Event Storming',
         iconKey: 'ddd-event-storming.toolbar',
         telemetryKey: 'event-storming',
         telemetrySegment: 'ddd toolbox',
@@ -91,6 +96,9 @@ export const FRAMEWORK_DESCRIPTORS = [
         pkg: '@labre/affine-gfx-ddd-event-storming',
         dir: 'affine/gfx/ddd-event-storming',
         extensions: [
+            // always-on: placed Event Storming boards must paint even with the button
+            // off, and their role vocabulary must stay readable
+            { viewExtension: 'DddEventStormingRenderViewExtension' },
             {
                 flag: 'ddd-event-storming',
                 viewExtension: 'DddEventStormingViewExtension',
@@ -98,9 +106,29 @@ export const FRAMEWORK_DESCRIPTORS = [
         ],
         shortcuts: true,
     },
+    {
+        id: 'c4',
+        labelKey: 'com.labre.framework.c4',
+        labelFallback: 'C4 model',
+        iconKey: 'c4.toolbar',
+        telemetryKey: 'c4',
+        telemetrySegment: 'c4 toolbox',
+        bundle: 'framework-c4',
+        info: 'c4Framework',
+        pkg: '@labre/affine-gfx-c4',
+        dir: 'affine/gfx/c4',
+        extensions: [
+            // always-on: placed C4 boards, boundaries and elements must paint even
+            // with the button off
+            { viewExtension: 'C4RenderViewExtension' },
+            { flag: 'c4', viewExtension: 'C4ViewExtension' },
+        ],
+        shortcuts: true,
+    },
     {
         id: 'ddd-core-domain',
         labelKey: 'com.labre.framework.ddd-core-domain',
+        labelFallback: 'Core Domain Chart',
         iconKey: 'ddd-core-domain.toolbar',
         telemetryKey: 'core-domain',
         telemetrySegment: 'ddd toolbox',
@@ -118,6 +146,7 @@ export const FRAMEWORK_DESCRIPTORS = [
     {
         id: 'ddd-context-map',
         labelKey: 'com.labre.framework.ddd-context-map',
+        labelFallback: 'Context Map',
         iconKey: 'ddd-context-map.toolbar',
         telemetryKey: 'context-map',
         telemetrySegment: 'ddd toolbox',
@@ -126,6 +155,9 @@ export const FRAMEWORK_DESCRIPTORS = [
         pkg: '@labre/affine-gfx-ddd-context-map',
         dir: 'affine/gfx/ddd-context-map',
         extensions: [
+            // always-on: placed Context Map boards must paint even with the button
+            // off, and their role vocabulary must stay readable
+            { viewExtension: 'DddContextMapRenderViewExtension' },
             { flag: 'ddd-context-map', viewExtension: 'DddContextMapViewExtension' },
         ],
         shortcuts: true,