@formicoidea/labre-framework-c4 0.40.0 → 0.42.0

package/dist/commands.js

@@ -1,5 +1,131 @@
 import { activateC4Relationship, c4BoardsForExport, createC4Board, createC4Boundary, createC4Node, exportC4MermaidFile, } from './actions.js';
-import { c4ExportMermaidIcon, C4_TOOLBOX_ICONS } from './toolbar/icons.js';
+import { BOUNDARY_STROKE, NODE_PALETTE, RELATIONSHIP_STROKE } from './consts.js';
+import { C4_ROLE } from './roles.js';
+import { c4ExportMermaidIcon, c4ToolbarIcon, C4_TOOLBOX_ICONS, } from './toolbar/icons.js';
+/**
+ * The C4 toolbox as commands — the single source every surface reads: the
+ * senior sub-menu, the artefact catalogue, the palette, Settings › Shortcuts
+ * and the agent (`docs/adr/0008`).
+ *
+ * ## Thirteen drawn, fourteen declared — exactly the cap
+ *
+ * The pack draws nine elements, two boundaries, one board and one connecting
+ * object: thirteen entries, all thirteen on a sub-menu that holds fourteen. The
+ * mermaid EXPORT is the fourteenth catalogue entry and declines the sub-menu, so
+ * the catalogue lands on fourteen against a cap of fourteen — which
+ * `selectSeniorMenuCommands` measures on the CATALOGUE, not on the menu. C4 is
+ * therefore still the framework that FITS, to the entry: nothing is arbitrated,
+ * the ranking never runs, and the sub-menu is exactly this list in exactly this
+ * order.
+ *
+ * The board's automatic LEGEND is deliberately not among them, and is not a
+ * command at all: it is reached from the selected board's contextual toolbar and
+ * from nowhere else (PO arbitration, 27/08/2026 — the same call the Context Map
+ * board makes). See `toolbar/config.ts` for what that costs and why it is the
+ * arbitrated exception to the command bottleneck.
+ *
+ * What the legend IS made of, though, is declared right here: each entry below
+ * subscribes the row its artefact puts in the box (`CommandDescriptor.legend`,
+ * `docs/adr/0026`), so the row and the gesture cannot drift apart the way a
+ * second hand-written table did.
+ *
+ * That does not make the ORDER free — it makes it a fifteenth entry away from
+ * mattering. Add one more of anything, an artefact or a second export, and the
+ * catalogue outgrows the cap, the ranking kicks in, and the first
+ * `SENIOR_MENU_RANKED_SLOTS` of this list become the COLD START every new user
+ * meets. BPMN learned that the hard way in a live recette (#144): its
+ * declarations were grouped by family, so the head a first-time user met was six
+ * events and a task, with nothing to connect them. The fix was the order, and
+ * the lesson is cheaper to apply before the overflow than after it.
+ *
+ * The head is THIRTEEN slots since #167 (seven recent + six frequent), not the
+ * seven it was when BPMN met the problem — which makes the cold start nearly the
+ * whole toolbox and the author's order nearly the whole answer. Named through
+ * the constant rather than restated as a number, so the next widening does not
+ * leave a lie here.
+ *
+ * ## The house order for a framework that FITS (PO, 28/08/2026)
+ *
+ * A general convention, decided on this pack and applying to every framework of
+ * fourteen commands or fewer — i.e. every one whose sub-menu is never
+ * arbitrated, so the author's order is the only order anybody ever sees:
+ *
+ *   1. the BOARDS first — the sheet has to exist before anything can be put on
+ *      it, and a first-time user who reaches for a person before a board draws
+ *      a person on the void;
+ *   2. then the BASE components, the ones a diagram of this kind is mostly made
+ *      of;
+ *   3. then the NICHE ones last;
+ *   4. and components of the SAME TYPE stay adjacent — the external variant sits
+ *      against the plain one it varies, not in a ghetto of externals at the end.
+ *
+ * This SUPERSEDES the previous C4 order, which led with the four levels and put
+ * the board sixth: it was built to make the would-be cold start drawable, and
+ * the PO's answer is that a cold start which opens with the sheet is drawable
+ * sooner. Applied here, it reads: the board, then person / person-ext, system /
+ * system-ext (each variant next to its plain form), container, component,
+ * database, then the two container flavours that are a container with a picture,
+ * then the relationship, then the two boundaries, then the export.
+ */
+/* ── The legend, SUBSCRIBED rather than tabulated (`docs/adr/0026`) ────── */
+/**
+ * The legend's own three section titles — this framework's word about this
+ * framework's vocabulary, which is why they are keyed per framework and never
+ * shared with UML's identical three (`translation-service/README.md`).
+ *
+ * They are DECLARED rather than derived from the commands' `category` because
+ * the catalogue files a boundary under `boundaries` and the legend calls the
+ * same thing a "Frame": one is where a gesture sits in a toolbox, the other is
+ * what the drawing is. The keys are the ones already shipped to the host
+ * catalogue, unchanged.
+ */
+const SECTION_ELEMENTS = [
+    'com.labre.c4.legend.section.elements',
+    'Elements',
+];
+const SECTION_FRAMES = [
+    'com.labre.c4.legend.section.frames',
+    'Frames',
+];
+const SECTION_RELATIONS = [
+    'com.labre.c4.legend.section.relations',
+    'Relations',
+];
+/** Every section wording above, for `translations.ts`'s manifest. */
+export const C4_LEGEND_SECTION_WORDINGS = [
+    SECTION_ELEMENTS,
+    SECTION_FRAMES,
+    SECTION_RELATIONS,
+];
+/**
+ * One element row, in the very fill {@link NODE_PALETTE} paints that kind with
+ * — never a second literal, so restyling the pack restyles its swatches. The
+ * WORDING is nowhere here either: the engine reads the role's own label, so
+ * renaming a role renames its row.
+ *
+ * `exact` is asked for on the container and nowhere else. `c4:database`
+ * specialises `c4:container`, so an inclusive row on the parent would put a
+ * blue square on a board carrying nothing but cylinders — a row naming a shape
+ * that is nowhere on the diagram. The other four element roles are childless,
+ * so the flag would change nothing for them and marks only the place where the
+ * distinction is real.
+ */
+function elementEntry(role, fill, exact = false) {
+    return {
+        role,
+        row: { swatch: 'square', color: fill },
+        ...(exact ? { exact } : {}),
+        section: SECTION_ELEMENTS,
+    };
+}
+/**
+ * A line row: a boundary and a relationship are both drawn, never filled, and
+ * both are dashed on the canvas — a filled chip would picture the one thing
+ * this board deliberately does not paint.
+ */
+function lineEntry(role, color, section) {
+    return { role, row: { swatch: 'line', color, dashed: true }, section };
+}
 const SPECS = [
     /* ── Boards first: the sheet everything else is drawn on ────────────── */
     {
@@ -10,6 +136,8 @@ const SPECS = [
         category: 'diagrams',
         element: 'board',
         board: true,
+        // Wider than the shared 260: the longest C4 row reads "Software system".
+        legendBox: { width: 290 },
         run: createC4Board,
     },
     /* ── The base components: the four levels, each plain form immediately
@@ -21,6 +149,7 @@ const SPECS = [
         kind: 'artefact',
         category: 'elements',
         element: 'node:person',
+        legend: elementEntry(C4_ROLE.person, NODE_PALETTE.person.fill),
         run: std => createC4Node(std, 'person'),
     },
     {
@@ -39,6 +168,7 @@ const SPECS = [
         kind: 'artefact',
         category: 'elements',
         element: 'node:system',
+        legend: elementEntry(C4_ROLE.system, NODE_PALETTE.system.fill),
         run: std => createC4Node(std, 'system'),
     },
     {
@@ -57,6 +187,7 @@ const SPECS = [
         kind: 'artefact',
         category: 'elements',
         element: 'node:container',
+        legend: elementEntry(C4_ROLE.container, NODE_PALETTE.container.fill, true),
         run: std => createC4Node(std, 'container'),
     },
     {
@@ -66,6 +197,7 @@ const SPECS = [
         kind: 'artefact',
         category: 'elements',
         element: 'node:component',
+        legend: elementEntry(C4_ROLE.component, NODE_PALETTE.component.fill),
         run: std => createC4Node(std, 'component'),
     },
     /* ── The niche components: a container with a picture on it ─────────── */
@@ -78,6 +210,7 @@ const SPECS = [
         kind: 'artefact',
         category: 'elements',
         element: 'node:database',
+        legend: elementEntry(C4_ROLE.database, NODE_PALETTE.database.fill),
         run: std => createC4Node(std, 'database'),
     },
     {
@@ -108,6 +241,7 @@ const SPECS = [
         kind: 'tool',
         category: 'relations',
         element: 'connector:relationship',
+        legend: lineEntry(C4_ROLE.relationship, RELATIONSHIP_STROKE, SECTION_RELATIONS),
         run: activateC4Relationship,
     },
     {
@@ -117,6 +251,9 @@ const SPECS = [
         kind: 'artefact',
         category: 'boundaries',
         element: 'boundary:system',
+        // ONE row for both boundaries, written on the PARENT role: a container
+        // boundary IS a boundary, and two rows would name one frame twice.
+        legend: lineEntry(C4_ROLE.boundary, BOUNDARY_STROKE, SECTION_FRAMES),
         run: std => createC4Boundary(std, 'system'),
     },
     {
@@ -148,6 +285,8 @@ const toolboxCommands = SPECS.map((spec, order) => ({
     availability: 'always',
     run: spec.run,
     telemetry: { framework: 'c4', element: spec.element, board: spec.board },
+    ...(spec.legend ? { legend: spec.legend } : {}),
+    ...(spec.legendBox ? { legendBox: spec.legendBox } : {}),
 }));
 /**
  * The EXPORT — the first C4 command whose subject is a whole BOARD.
@@ -219,4 +358,7 @@ export const c4Commands = [
 export const c4CommandIcons = {
     ...C4_TOOLBOX_ICONS,
     'c4.export-mermaid': c4ExportMermaidIcon,
+    // The senior button's 56×56 glyph, so `FrameworkDescriptor.iconKey` resolves
+    // through `getCommandIcon`.
+    'c4.toolbar': c4ToolbarIcon,
 };

package/dist/consts.d.ts

@@ -246,6 +246,22 @@ export declare const NODE_SIZE: Record<C4NodeKind, {
  * nothing at all: the words are the artefact.
  */
 export declare const NODE_LABEL: Record<C4NodeKind, string>;
+/**
+ * The i18n key {@link NODE_LABEL} is the English default of — mirrors BPMN's
+ * {@link nodeLabelKey} exactly, one package over: resolved at placement
+ * (`createC4Node`, the NAME tier) and never afterwards, since the title is
+ * content from the moment it lands and an author is free to retype it.
+ *
+ * Safe to translate where the type line is not: the exporter reads a
+ * component's NAME verbatim (`c4StatedName`) with no placeholder suppression,
+ * so nothing downstream compares this text against the English literal.
+ */
+export declare const nodeLabelKey: (kind: C4NodeKind) => string;
+/**
+ * The prompt a fresh description tier carries, resolved at placement exactly
+ * like {@link DESCRIPTION_PLACEHOLDER} below is the English default of.
+ */
+export declare const DESCRIPTION_PLACEHOLDER_KEY = "com.labre.c4.seed.description-placeholder";
 export declare const FONT_FAMILY = "Inter, sans-serif";
 /**
  * The card — the same white every framework background paints, framed and
@@ -336,6 +352,14 @@ export declare const BOUNDARY_MARGIN = 12;
  * on the canvas keeps its words whatever its variant.
  */
 export declare const BOUNDARY_LABEL: Record<C4BoundaryVariant, string>;
+/**
+ * The i18n key {@link BOUNDARY_LABEL} is the English default of — resolved at
+ * placement (`createC4Boundary`) exactly like {@link nodeLabelKey}: the name
+ * is exported verbatim (`export.ts`, `boundary.name`) with no comparison
+ * against the English literal, so translating it is as safe as a component's
+ * title.
+ */
+export declare const boundaryLabelKey: (variant: C4BoundaryVariant) => string;
 /**
  * Relationship connector preset — the dashed arrow C4 draws between elements.
  *

package/dist/consts.js

@@ -291,6 +291,22 @@ export const NODE_LABEL = {
     browser: 'Web app',
     component: 'Component',
 };
+/**
+ * The i18n key {@link NODE_LABEL} is the English default of — mirrors BPMN's
+ * {@link nodeLabelKey} exactly, one package over: resolved at placement
+ * (`createC4Node`, the NAME tier) and never afterwards, since the title is
+ * content from the moment it lands and an author is free to retype it.
+ *
+ * Safe to translate where the type line is not: the exporter reads a
+ * component's NAME verbatim (`c4StatedName`) with no placeholder suppression,
+ * so nothing downstream compares this text against the English literal.
+ */
+export const nodeLabelKey = (kind) => `com.labre.c4.seed.${kind}`;
+/**
+ * The prompt a fresh description tier carries, resolved at placement exactly
+ * like {@link DESCRIPTION_PLACEHOLDER} below is the English default of.
+ */
+export const DESCRIPTION_PLACEHOLDER_KEY = 'com.labre.c4.seed.description-placeholder';
 /* ── The board ─────────────────────────────────────────────────────────── */
 export const FONT_FAMILY = 'Inter, sans-serif';
 /**
@@ -389,6 +405,14 @@ export const BOUNDARY_LABEL = {
     system: 'System boundary',
     container: 'Container boundary',
 };
+/**
+ * The i18n key {@link BOUNDARY_LABEL} is the English default of — resolved at
+ * placement (`createC4Boundary`) exactly like {@link nodeLabelKey}: the name
+ * is exported verbatim (`export.ts`, `boundary.name`) with no comparison
+ * against the English literal, so translating it is as safe as a component's
+ * title.
+ */
+export const boundaryLabelKey = (variant) => `com.labre.c4.seed.boundary-${variant}`;
 /* ── The relationship ──────────────────────────────────────────────────── */
 /**
  * Relationship connector preset — the dashed arrow C4 draws between elements.

package/dist/index.d.ts

@@ -13,5 +13,4 @@ export { C4_INTERCHANGE, C4_MERMAID_EXPORT, C4_MERMAID_EXTENSION, C4_MERMAID_FOR
 export { C4_ELEMENT_MATRIX, C4_RELATIONSHIP_MATRIX, C4_RULES, } from './rules.js';
 export { c4CommandIcons, c4Commands } from './commands.js';
 export { c4TranslationEntries } from './translations.js';
-export { C4_AUTO_LEGEND } from './legend.js';
 export { C4_COMPONENT_READING, C4_CONTAINER_READING, C4_PERSON_READING, C4_READINGS, C4_SYSTEM_READING, } from './reading.js';

package/dist/index.js

@@ -48,10 +48,10 @@ export { C4_ELEMENT_MATRIX, C4_RELATIONSHIP_MATRIX, C4_RULES, } from './rules.js
 // The toolbox, for the host that composes the command registry and the
 // translation-key manifest out of the frameworks it installed (see
 // `packages/affine/all/src/{commands,translations}.ts`).
+// What the board's automatic legend can say is no longer a table of its own:
+// every row is subscribed by the command that draws the artefact
+// (`CommandDescriptor.legend`, `docs/adr/0026`), so `c4Commands` already
+// answers "what does this framework document about itself" without a canvas.
 export { c4CommandIcons, c4Commands } from './commands.js';
 export { c4TranslationEntries } from './translations.js';
-// The legend TABLE — what the board's automatic legend can say. Exported for
-// the same reason the two background declarations are: it answers "what does
-// this framework document about itself" without a canvas.
-export { C4_AUTO_LEGEND } from './legend.js';
 export { C4_COMPONENT_READING, C4_CONTAINER_READING, C4_PERSON_READING, C4_READINGS, C4_SYSTEM_READING, } from './reading.js';

package/dist/morph.js

@@ -167,8 +167,8 @@ function rewriteTier(model, role, decide) {
  *   "Customer database" keeps that name whatever it becomes, which is the PO's
  *   "the label is intact" for every title that is real content.
  */
-function rewriteTiers(model, from, to) {
-    rewriteTier(model, C4_ROLE['type-line'], text => c4MorphedTypeLine(from, to, text));
+function rewriteTiers(model, from, to, std) {
+    rewriteTier(model, C4_ROLE['type-line'], text => c4MorphedTypeLine(from, to, text, std));
     rewriteTier(model, C4_ROLE.title, text => c4MorphedTitle(from, to, text));
 }
 /**

package/dist/node/type-line-watcher.js

@@ -103,7 +103,12 @@ export class C4TypeLineWatcher extends InteractivityExtension {
         if (!kind)
             return;
         const raw = element.text.toString();
-        const canonical = normalizeC4TypeLine(kind, raw);
+        // `this.std` resolves the canonical line through the host's catalogue —
+        // both halves of the prompt, and the technology round-trip
+        // (`technologyOfTypeLine`) recognising the host's own resolved word —
+        // so a translated document's type line stays in that language across a
+        // commit instead of being silently reverted to English (`type-line.ts`).
+        const canonical = normalizeC4TypeLine(kind, raw, this.std);
         if (canonical === raw)
             return;
         this.std.store.captureSync();

package/dist/templates.js

@@ -46,6 +46,8 @@ const boundaryPreview = (inner = '') => `<svg ${ATTRS} fill="none"><rect x="14"
 const CONTAINER = NODE_PALETTE.container;
 export const c4TemplateCategory = {
     name: 'C4',
+    // Reuses the senior button's own key — see `TemplateCategory.nameKey`.
+    nameKey: 'com.labre.framework.c4',
     templates: [
         templateFromCommand(byId('c4.addBoard'), `<svg ${ATTRS} fill="none"><rect x="10" y="10" width="115" height="60" rx="6" fill="${BOARD_CARD_FILL}" stroke="${BOARD_CARD_BORDER}" stroke-width="1.5"/><path d="M10 26 H125" stroke="${BOARD_CARD_BORDER}" stroke-width="1.5"/><rect x="11" y="11" width="113" height="15" fill="${BOARD_BAND_FILL}"/><rect x="20" y="15" width="40" height="6" rx="3" fill="${BOARD_TITLE_COLOR}" opacity="0.55"/><rect x="22" y="36" width="34" height="20" rx="2" fill="${NODE_PALETTE.system.fill}"/><rect x="79" y="36" width="34" height="20" rx="2" fill="${CONTAINER.fill}"/><path d="M58 46 H75" stroke="${RELATIONSHIP_STROKE}" stroke-width="1.6" stroke-dasharray="4 3"/></svg>`),
         templateFromCommand(byId('c4.addPerson'), personPreview('person')),

package/dist/toolbar/c4-senior-button.d.ts

@@ -16,4 +16,5 @@ export declare class EdgelessC4SeniorButton extends DddSeniorButtonBase {
     protected label: string;
     protected labelKey: string;
     protected icon: import("lit-html").TemplateResult<2>;
+    protected owner: "c4";
 }

package/dist/toolbar/c4-senior-button.js

@@ -19,5 +19,6 @@ export class EdgelessC4SeniorButton extends DddSeniorButtonBase {
         this.label = 'C4 model';
         this.labelKey = 'com.labre.framework.c4';
         this.icon = c4ToolbarIcon;
+        this.owner = 'c4';
     }
 }

package/dist/toolbar/config.d.ts

@@ -1,5 +1,4 @@
-import { ActionPlacement, type ToolbarContext, type ToolbarModuleConfig } from '@formicoidea/labre-core/shared/services';
-import { type TemplateResult } from 'lit';
+import { type ToolbarContext, type ToolbarModuleConfig } from '@formicoidea/labre-core/shared/services';
 /**
  * The selected C4 board's contextual toolbar: the resize toggle, and the
  * automatic legend of what is actually drawn on the board.
@@ -13,15 +12,14 @@ import { type TemplateResult } from 'lit';
  * The PO's call is that generating one belongs to a board you have SELECTED and
  * to nothing else: it is not an artefact to pick off a palette, and an entry in
  * a catalogue of things C4 draws would offer it to a user with no board in front
- * of them. So there is no `c4.legend` command, this button is the only way to
- * reach it, and the telemetry it owes is emitted by hand below.
+ * of them. So there is no `c4.legend` command, and this button is the only way
+ * to reach it.
  *
- * That is the same shape — and the same exception — the Context Map board makes
- * (`ddd-context-map/src/toolbar/board-config.ts`), down to the payload, so the
- * two frameworks' legends stay comparable on one dashboard. The cost is the one
- * the bottleneck exists to avoid and is accepted knowingly: this `track()` call
- * is a second emitter, and it is on whoever edits it to keep the wire values
- * matching what `reportCommandTelemetry` would have sent.
+ * That is the same shape — and the same exception — every other framework with a
+ * legend makes. The cost is the one the bottleneck exists to avoid: the
+ * telemetry it owes is emitted outside `runCommand`. It is emitted ONCE, by the
+ * shared factory (`legend-toolbar.ts`), so the seven copies of those wire values
+ * that used to sit in seven files can no longer drift apart.
  *
  * ## Two modules on one element, and why
  *
@@ -66,35 +64,26 @@ export declare const c4BoardToolbarConfig: {
     readonly actions: [{
         readonly id: "a.toggle-resize";
         readonly tooltipWording: import("@formicoidea/labre-core/shared/services").ChromeWording;
-        readonly icon: TemplateResult<1>;
+        readonly icon: import("lit-html").TemplateResult<1>;
         readonly active: (ctx: ToolbarContext) => boolean;
         readonly run: (ctx: ToolbarContext) => void;
-    }, {
-        id: string;
-        placement: ActionPlacement;
-        when: (ctx: ToolbarContext) => boolean;
-        generate: (ctx: ToolbarContext) => {
-            icon: TemplateResult;
-            label: string;
-            run: (runCtx: ToolbarContext) => void;
-        };
-    }];
+    }, import("@formicoidea/labre-core/shared/services").ToolbarActionGenerator];
     readonly when: (ctx: ToolbarContext) => boolean;
 };
 export declare const c4BoardToolbarExtension: import("@formicoidea/labre-core/store").ExtensionType;
 /**
  * The legend button — the flag-gated half of the row (see the note above).
  *
- * `b.` sorts it after the resize toggle, so the two modules render as the one
- * row a user sees rather than in registration order.
+ * The SHARED factory, not a C4 copy of it: the button, the placement, the box
+ * and the one `FrameworkLegendCreated` emission all live in the surface block
+ * (`legend-toolbar.ts`, `docs/adr/0026`), and C4 hands it the board model to
+ * look for, whose commands to read the rows off, and the historical wire value.
+ *
+ * `b.` — the factory's default — sorts it after the resize toggle, so the two
+ * modules render as the one row a user sees rather than in registration order.
  */
 export declare const c4LegendToolbarConfig: {
-    readonly actions: [{
-        readonly id: "b.legend";
-        readonly tooltipWording: import("@formicoidea/labre-core/shared/services").ChromeWording;
-        readonly icon: TemplateResult<1>;
-        readonly run: (ctx: ToolbarContext) => void;
-    }];
+    readonly actions: [import("@formicoidea/labre-core/shared/services").ToolbarAction];
     readonly when: (ctx: ToolbarContext) => boolean;
 };
 /**

package/dist/toolbar/config.js

@@ -1,10 +1,8 @@
-import { EdgelessCRUDIdentifier, validationToolbarConfig, } from '@formicoidea/labre-core/blocks/surface';
-import { dddLegendIcon } from '@formicoidea/labre-ddd-shared';
+import { EdgelessCRUDIdentifier, legendToolbarAction, validationToolbarConfig, } from '@formicoidea/labre-core/blocks/surface';
 import { C4BoardElementModel } from '@formicoidea/labre-core/model';
-import { ActionPlacement, BOARD_LEGEND_NOTATION, BOARD_RESIZE_TOGGLE, TelemetryProvider, ToolbarModuleExtension, translateKey, } from '@formicoidea/labre-core/shared/services';
-import { BlockFlavourIdentifier, getRegisteredCommands, runCommand, } from '@formicoidea/labre-core/std';
+import { BOARD_RESIZE_TOGGLE, commandMoreAction, TelemetryProvider, ToolbarModuleExtension, translateKey, } from '@formicoidea/labre-core/shared/services';
+import { BlockFlavourIdentifier } from '@formicoidea/labre-core/std';
 import { html, nothing } from 'lit';
-import { createC4Legend } from '../actions.js';
 import { C4_BOARD_LEVEL_MENU } from '../levels.js';
 import { c4ExportMermaidIcon } from './icons.js';
 const ResizeIcon = html `<svg
@@ -56,55 +54,6 @@ const CheckIcon = html `<svg
 >
   <path d="M5 12.5l4.5 4.5L19 7.5" />
 </svg>`;
-const findCommand = (ctx, id) => getRegisteredCommands(ctx.std).find(candidate => candidate.id === id);
-/**
- * A "⋮" entry that INVOKES a registered command instead of restating what it
- * does — the shape `docs/adr/0010` M3 introduced, and the reason the export has
- * one behaviour, one availability rule and one telemetry emission whether it is
- * reached from here, from the catalogue, from the palette, from
- * Settings › Shortcuts or from the agent.
- *
- * Two things the widget imposes: a menu line is drawn from `label` (a tooltip on
- * a line that is already words would be a second copy of them), and
- * `placement: ActionPlacement.More` is what partitions it out of the row in the
- * first place — `renderToolbar` splits on exactly that flag, and the entries it
- * collects come from every module contributing to the element, so a framework
- * can add to the "⋮" without owning it.
- *
- * `generate` rather than a static entry because the i18n seam needs `std`:
- * `translateKey` is what reaches the host's catalogue, and a hard-coded English
- * label would be the one wording a host could not override.
- *
- * Lifted from the BPMN pool's row, where `bpmn.exportXml` sits in exactly this
- * position.
- */
-function commandMoreAction(id, commandId, labelKey, labelFallback, icon) {
-    return {
-        id,
-        placement: ActionPlacement.More,
-        when: (ctx) => {
-            const command = findCommand(ctx, commandId);
-            return command !== undefined && (command.when?.(ctx.std) ?? true);
-        },
-        generate: (ctx) => ({
-            icon,
-            label: translateKey(ctx.std, labelKey, labelFallback),
-            run: (runCtx) => {
-                const command = findCommand(runCtx, commandId);
-                if (!command)
-                    return;
-                // The same `source` the row's own entries report: the "⋮" is a
-                // degradation of the row, not a surface of its own, and the
-                // `ElementCreationSource` union deliberately names places rather than
-                // widths (`docs/adr/0008`).
-                runCommand(runCtx.std, command, {
-                    surface: 'contextual-toolbar',
-                    source: 'toolbar:general',
-                });
-            },
-        }),
-    };
-}
 /**
  * The selected C4 board's contextual toolbar: the resize toggle, and the
  * automatic legend of what is actually drawn on the board.
@@ -118,15 +67,14 @@ function commandMoreAction(id, commandId, labelKey, labelFallback, icon) {
  * The PO's call is that generating one belongs to a board you have SELECTED and
  * to nothing else: it is not an artefact to pick off a palette, and an entry in
  * a catalogue of things C4 draws would offer it to a user with no board in front
- * of them. So there is no `c4.legend` command, this button is the only way to
- * reach it, and the telemetry it owes is emitted by hand below.
+ * of them. So there is no `c4.legend` command, and this button is the only way
+ * to reach it.
  *
- * That is the same shape — and the same exception — the Context Map board makes
- * (`ddd-context-map/src/toolbar/board-config.ts`), down to the payload, so the
- * two frameworks' legends stay comparable on one dashboard. The cost is the one
- * the bottleneck exists to avoid and is accepted knowingly: this `track()` call
- * is a second emitter, and it is on whoever edits it to keep the wire values
- * matching what `reportCommandTelemetry` would have sent.
+ * That is the same shape — and the same exception — every other framework with a
+ * legend makes. The cost is the one the bottleneck exists to avoid: the
+ * telemetry it owes is emitted outside `runCommand`. It is emitted ONCE, by the
+ * shared factory (`legend-toolbar.ts`), so the seven copies of those wire values
+ * that used to sit in seven files can no longer drift apart.
  *
  * ## Two modules on one element, and why
  *
@@ -345,32 +293,21 @@ const levelPickerAction = {
 /**
  * The legend button — the flag-gated half of the row (see the note above).
  *
- * `b.` sorts it after the resize toggle, so the two modules render as the one
- * row a user sees rather than in registration order.
+ * The SHARED factory, not a C4 copy of it: the button, the placement, the box
+ * and the one `FrameworkLegendCreated` emission all live in the surface block
+ * (`legend-toolbar.ts`, `docs/adr/0026`), and C4 hands it the board model to
+ * look for, whose commands to read the rows off, and the historical wire value.
+ *
+ * `b.` — the factory's default — sorts it after the resize toggle, so the two
+ * modules render as the one row a user sees rather than in registration order.
  */
 export const c4LegendToolbarConfig = {
     actions: [
-        {
-            id: 'b.legend',
-            tooltipWording: BOARD_LEGEND_NOTATION,
-            icon: dddLegendIcon,
-            run(ctx) {
-                createC4Legend(ctx.std);
-                ctx.std
-                    .getOptional(TelemetryProvider)
-                    ?.track('FrameworkLegendCreated', {
-                    // The WIRE values, and they are the ones `reportCommandTelemetry`
-                    // would have sent for a `kind: 'legend'` command — `framework` from
-                    // the descriptor's `telemetryKey`, `element: 'legend'` as Wardley
-                    // and the Context Map both emit, so the three are one metric.
-                    framework: 'c4',
-                    element: 'legend',
-                    page: 'whiteboard editor',
-                    segment: 'element toolbar',
-                    module: 'c4 toolbar',
-                });
-            },
-        },
+        legendToolbarAction({
+            Model: C4BoardElementModel,
+            owner: 'c4',
+            framework: 'c4',
+        }),
     ],
     when: (ctx) => ctx.getSurfaceModelsByType(C4BoardElementModel).length > 0,
 };

package/dist/toolbar/icons.d.ts

@@ -67,11 +67,14 @@ export declare const c4ExportMermaidIcon: import("lit-html").TemplateResult<2>;
  *
  * {@link c4ExportMermaidIcon} is deliberately NOT here and is added to
  * `c4CommandIcons` in `commands.ts` instead: this record is the TOOLBOX — the
- * thirteen glyphs of things C4 DRAWS — and an export draws nothing.
+ * thirteen glyphs of things C4 DRAWS — and an export draws nothing. The same
+ * goes for {@link c4ToolbarIcon}, registered there under `c4.toolbar` for
+ * `FrameworkDescriptor.iconKey`; it is the one key that test exempts from the
+ * glyph ⇄ command bijection.
  *
  * The legend's glyph is in neither, because the legend is no longer a command at
- * all: it is `dddLegendIcon`, referenced straight from `config.ts` by the button
- * that is now the only way to reach it (PO arbitration, 27/08/2026).
+ * all: it is the surface block's own `legendIcon`, drawn by the shared button
+ * factory that is now the only way to reach it (PO arbitration, 27/08/2026).
  */
 export declare const C4_TOOLBOX_ICONS: {
     readonly 'c4.person': import("lit-html").TemplateResult<2>;

package/dist/toolbar/icons.js

@@ -134,11 +134,14 @@ export const c4ExportMermaidIcon = svg `<svg width="24" height="24" viewBox="0 0
  *
  * {@link c4ExportMermaidIcon} is deliberately NOT here and is added to
  * `c4CommandIcons` in `commands.ts` instead: this record is the TOOLBOX — the
- * thirteen glyphs of things C4 DRAWS — and an export draws nothing.
+ * thirteen glyphs of things C4 DRAWS — and an export draws nothing. The same
+ * goes for {@link c4ToolbarIcon}, registered there under `c4.toolbar` for
+ * `FrameworkDescriptor.iconKey`; it is the one key that test exempts from the
+ * glyph ⇄ command bijection.
  *
  * The legend's glyph is in neither, because the legend is no longer a command at
- * all: it is `dddLegendIcon`, referenced straight from `config.ts` by the button
- * that is now the only way to reach it (PO arbitration, 27/08/2026).
+ * all: it is the surface block's own `legendIcon`, drawn by the shared button
+ * factory that is now the only way to reach it (PO arbitration, 27/08/2026).
  */
 export const C4_TOOLBOX_ICONS = {
     'c4.person': c4PersonIcon,