@formicoidea/labre-framework-c4 0.33.0

package/dist/index.js

@@ -0,0 +1,52 @@
+// The declarations ARE the two frames: what they look like, where their plot is
+// and which words they carry are all read off these two values (`docs/adr/0009`
+// on why a framework declares rather than draws). Exported so a host — and the
+// audit's own consumers — can answer those questions without a canvas.
+export { C4_BOARD_BACKGROUND, C4_BOUNDARY_BACKGROUND } from './background.js';
+export { BOUNDARY_LABEL, DESCRIPTION_PLACEHOLDER, NODE_LABEL, NODE_PALETTE, NODE_RADIUS, NODE_SIZE, NODE_STROKE_WIDTH, RELATIONSHIP_STROKE, RELATIONSHIP_WIDTH, } from './consts.js';
+// The middle tier of an element's label, SEMI-DERIVED: the word from the kind,
+// the technology from the author. Pure and total over the nine kinds and over
+// every string an author can type, so a host, a rule or a reading can name an
+// element exactly as the canvas does — and read the technology back out of it.
+export { C4_TYPE_PLACEHOLDER, C4_TYPE_TAKES_TECHNOLOGY, C4_TYPE_WORD, c4MorphedTypeLine, c4TypeLine, normalizeC4TypeLine, technologyOfTypeLine, TYPE_TECHNOLOGY_PLACEHOLDER, } from './type-line.js';
+// What a C4 shape is BORN as, shared by the palette and — since the morph — by
+// the toolbar that says one artefact differently, so the two can never disagree
+// about what a database looks like.
+export { c4MorphClears, c4MorphProps, c4NodeProps, GLYPH_BODY_KINDS, } from './presets.js';
+// What an artefact may BECOME: the declared families, the spec the generic
+// morph module is registered with, and the resolution from a selected group to
+// the shape inside it. Data a host can read without an editor.
+export { C4_MORPH_FAMILIES, C4_MORPH_SPEC, c4MorphedTitle, c4NodeOfComponent, } from './morph.js';
+// A C4 component — the shape and its own words, grouped. Where the two written
+// tiers are placed at creation, and which of them belongs to which node. Pure,
+// so the creation site, the exporter and a host all resolve a component the
+// same way.
+export { c4ComponentSiblings, c4ComponentTiers, c4StatedDescription, c4StatedName, c4StatedTechnology, c4TierBoxes, c4TierText, } from './component.js';
+// Which of the three C4 diagrams a board declares it draws, and the words the
+// picker offers them under — DATA, like the rules that read the fact.
+export { C4_BOARD_LEVEL_MENU } from './levels.js';
+// The levels of requirement, and the rules they arbitrate: DATA a host can
+// read, ship and reason about without an editor.
+export { C4_PROFILES } from './profiles.js';
+export { C4_ROLE, C4_ROLE_OF_KIND, C4_ROLES, } from './roles.js';
+// The half of the export that needs an editor, kept apart from the half that
+// does not — same split BPMN's index makes for the same reason.
+export { c4BoardsForExport, c4ExportBoardOf } from './actions.js';
+// The export itself: a PURE function over element models — models in, mermaid
+// out — so a host can export a board it never rendered, and a rule or a test can
+// call it with plain stubs.
+export { C4_MERMAID_OF_KIND, exportC4Mermaid, toMermaidAlias, toMermaidText, } from './export.js';
+// C4's entries in the interchange registry (`docs/adr/0012`) — one today,
+// mermaid OUT. Exported whole so a host can ask what C4 can read and write
+// without mounting an editor, and call it without one either.
+export { C4_INTERCHANGE, C4_MERMAID_EXPORT, C4_MERMAID_EXTENSION, C4_MERMAID_FORMAT, C4_MERMAID_MIME, c4BoardFrom, c4SafeFilename, } from './interchange.js';
+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`).
+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';

package/dist/interchange.d.ts

@@ -0,0 +1,74 @@
+import type { InterchangeCapability, InterchangeExportCapability, InterchangeFormat } from '@formicoidea/labre-core/blocks/surface';
+import type { GfxPrimitiveElementModel } from '@formicoidea/labre-core/std/gfx';
+import { type C4ExportBoard } from './export.js';
+/**
+ * C4's entries in the interchange registry (`docs/adr/0012`, P1).
+ *
+ * One entry today — mermaid OUT — declared exactly as BPMN declares its `.bpmn`
+ * export: C4 can write a mermaid C4 diagram and cannot yet read one, and the
+ * registry says so instead of leaving a reader to infer a symmetry nobody
+ * implemented.
+ *
+ * Everything here is pure. The serializer was already a pure function with no
+ * `std` in sight, and this file adds no editor to it: it only picks the
+ * artefacts the serializer speaks about out of the elements it is handed.
+ *
+ * One C4-specific reading of the contract: the SELECTION is expressed by the
+ * caller through which boards it includes in the element list. A C4 board is
+ * one level of one model, so `exportC4Mermaid` scopes to the boards it is
+ * given — every `c4Board` in the list becomes a document, and the caller that
+ * wants only the selected ones simply leaves the others out. A headless host
+ * that hands over the whole surface gets every board, one document each, which
+ * is the honest whole-surface answer for this framework.
+ */
+/**
+ * mermaid C4 source. **Semantic** — the file carries a model, not a picture, so
+ * it takes the whole preservation contract the day an importer is written.
+ *
+ * `.mmd` is the extension the mermaid CLI and every editor plugin watch for.
+ * The format carries no `mime`, where `BPMN_XML_FORMAT` carries
+ * `application/xml`, and the difference is the truth rather than an oversight:
+ * mermaid has no registered media type, so there is none to declare. What a
+ * DOWNLOAD is served as is a different question with an answer — `text/plain`,
+ * because an invented type is a file some browsers refuse to save — and that
+ * answer is stated on the export result, where it belongs.
+ *
+ * The charset rides along with it because the text is the whole payload: unlike
+ * XML, a mermaid file has no prolog to declare its own encoding in.
+ */
+export declare const C4_MERMAID_EXTENSION = ".mmd";
+export declare const C4_MERMAID_MIME = "text/plain;charset=utf-8";
+export declare const C4_MERMAID_FORMAT: InterchangeFormat;
+/**
+ * The artefacts the exporter speaks about, picked out of a list of elements and
+ * kept in the order they were given.
+ *
+ * Six lists and not four: since the PO's recette of 28/08/2026 a C4 component
+ * is a shape, its three written tiers as canvas TEXT elements, and the GROUP
+ * that makes the four one thing — so the technology and the description the
+ * exporter writes are read off the canvas rather than off two model fields.
+ * Both lists are collected whole and unfiltered, because a tier belongs to its
+ * node through the group and not through the geometry (`component.ts`).
+ *
+ * Document order matters for the reason it does everywhere in this framework:
+ * it is the tie-break attribution breaks on — a centre inside two overlapping
+ * boundaries goes to the first — and the audit's `attribute()` breaks it the
+ * same way. Sorting here would make the export disagree with the badge the
+ * user can see.
+ */
+export declare function c4BoardFrom(elements: readonly GfxPrimitiveElementModel[]): C4ExportBoard;
+/**
+ * A name a file system will accept, minus the extension.
+ *
+ * The same transformations `bpmnSafeFilename` applies and for the same reasons
+ * — reserved characters become `-`, whitespace runs collapse, the result is
+ * capped, and the Windows tail of dots and spaces is trimmed AFTER the cap so
+ * the extension is not the thing that gets eaten. Duplicated rather than
+ * imported: a filename rule is not API, and coupling two frameworks to share
+ * eight lines would be the worse trade.
+ */
+export declare function c4SafeFilename(raw: string | undefined): string;
+/** `c4:mermaid:export` — C4's first capability. */
+export declare const C4_MERMAID_EXPORT: InterchangeExportCapability;
+/** Everything C4 registers, in one list the view extension can hand over. */
+export declare const C4_INTERCHANGE: readonly InterchangeCapability[];

package/dist/interchange.js

@@ -0,0 +1,143 @@
+import { interchangeCapabilityId } from '@formicoidea/labre-core/blocks/surface';
+import { C4BoardElementModel, C4BoundaryElementModel, C4NodeElementModel, ConnectorElementModel, GroupElementModel, TextElementModel, } from '@formicoidea/labre-core/model';
+import { exportC4Mermaid } from './export.js';
+/**
+ * C4's entries in the interchange registry (`docs/adr/0012`, P1).
+ *
+ * One entry today — mermaid OUT — declared exactly as BPMN declares its `.bpmn`
+ * export: C4 can write a mermaid C4 diagram and cannot yet read one, and the
+ * registry says so instead of leaving a reader to infer a symmetry nobody
+ * implemented.
+ *
+ * Everything here is pure. The serializer was already a pure function with no
+ * `std` in sight, and this file adds no editor to it: it only picks the
+ * artefacts the serializer speaks about out of the elements it is handed.
+ *
+ * One C4-specific reading of the contract: the SELECTION is expressed by the
+ * caller through which boards it includes in the element list. A C4 board is
+ * one level of one model, so `exportC4Mermaid` scopes to the boards it is
+ * given — every `c4Board` in the list becomes a document, and the caller that
+ * wants only the selected ones simply leaves the others out. A headless host
+ * that hands over the whole surface gets every board, one document each, which
+ * is the honest whole-surface answer for this framework.
+ */
+/* ── The format ───────────────────────────────────────────────────────── */
+/**
+ * mermaid C4 source. **Semantic** — the file carries a model, not a picture, so
+ * it takes the whole preservation contract the day an importer is written.
+ *
+ * `.mmd` is the extension the mermaid CLI and every editor plugin watch for.
+ * The format carries no `mime`, where `BPMN_XML_FORMAT` carries
+ * `application/xml`, and the difference is the truth rather than an oversight:
+ * mermaid has no registered media type, so there is none to declare. What a
+ * DOWNLOAD is served as is a different question with an answer — `text/plain`,
+ * because an invented type is a file some browsers refuse to save — and that
+ * answer is stated on the export result, where it belongs.
+ *
+ * The charset rides along with it because the text is the whole payload: unlike
+ * XML, a mermaid file has no prolog to declare its own encoding in.
+ */
+export const C4_MERMAID_EXTENSION = '.mmd';
+export const C4_MERMAID_MIME = 'text/plain;charset=utf-8';
+export const C4_MERMAID_FORMAT = {
+    id: 'mermaid',
+    tier: 'semantic',
+    extensions: [C4_MERMAID_EXTENSION],
+};
+/* ── Pure board helpers ───────────────────────────────────────────────── */
+/**
+ * The artefacts the exporter speaks about, picked out of a list of elements and
+ * kept in the order they were given.
+ *
+ * Six lists and not four: since the PO's recette of 28/08/2026 a C4 component
+ * is a shape, its three written tiers as canvas TEXT elements, and the GROUP
+ * that makes the four one thing — so the technology and the description the
+ * exporter writes are read off the canvas rather than off two model fields.
+ * Both lists are collected whole and unfiltered, because a tier belongs to its
+ * node through the group and not through the geometry (`component.ts`).
+ *
+ * Document order matters for the reason it does everywhere in this framework:
+ * it is the tie-break attribution breaks on — a centre inside two overlapping
+ * boundaries goes to the first — and the audit's `attribute()` breaks it the
+ * same way. Sorting here would make the export disagree with the badge the
+ * user can see.
+ */
+export function c4BoardFrom(elements) {
+    const boards = [];
+    const nodes = [];
+    const boundaries = [];
+    const connectors = [];
+    const texts = [];
+    const groups = [];
+    for (const element of elements) {
+        if (element instanceof C4BoardElementModel)
+            boards.push(element);
+        else if (element instanceof C4NodeElementModel)
+            nodes.push(element);
+        else if (element instanceof C4BoundaryElementModel)
+            boundaries.push(element);
+        else if (element instanceof ConnectorElementModel)
+            connectors.push(element);
+        else if (element instanceof TextElementModel)
+            texts.push(element);
+        else if (element instanceof GroupElementModel)
+            groups.push(element);
+    }
+    return { boards, nodes, boundaries, connectors, texts, groups };
+}
+/**
+ * A name a file system will accept, minus the extension.
+ *
+ * The same transformations `bpmnSafeFilename` applies and for the same reasons
+ * — reserved characters become `-`, whitespace runs collapse, the result is
+ * capped, and the Windows tail of dots and spaces is trimmed AFTER the cap so
+ * the extension is not the thing that gets eaten. Duplicated rather than
+ * imported: a filename rule is not API, and coupling two frameworks to share
+ * eight lines would be the worse trade.
+ */
+export function c4SafeFilename(raw) {
+    const safe = (raw ?? '')
+        .trim()
+        .replaceAll(/[\\/:*?"<>|]/g, '-')
+        .replaceAll(/\s+/g, ' ')
+        .trim()
+        .slice(0, 120)
+        .replace(/[. ]+$/, '');
+    return safe || 'diagram';
+}
+/* ── The capability ───────────────────────────────────────────────────── */
+/**
+ * The board as a mermaid C4 document.
+ *
+ * A thin adapter and nothing else: it picks the C4 artefacts out of the
+ * elements it was handed, runs {@link exportC4Mermaid} — unchanged — and names
+ * the file. There is no second door: `c4.exportMermaid` calls THIS, so the
+ * command and the registry cannot produce different bytes, different filenames
+ * or different content types — there is nowhere for them to differ.
+ *
+ * No `warnings`, where the BPMN exporter has some: the C4 writer drops nothing
+ * it could have written down. What it leaves out — a neutral connector, a shape
+ * with no role, a relationship whose far end is on another board — is not a
+ * loss but a statement the author never made (`docs/adr/0010`), and a warning
+ * about it would be the export telling the user off for their own drawing.
+ */
+const runC4MermaidExport = (elements, context) => {
+    const name = c4SafeFilename(context.name);
+    return {
+        text: exportC4Mermaid(c4BoardFrom(elements)),
+        filename: `${name}${C4_MERMAID_EXTENSION}`,
+        mime: C4_MERMAID_MIME,
+    };
+};
+/** `c4:mermaid:export` — C4's first capability. */
+export const C4_MERMAID_EXPORT = {
+    id: interchangeCapabilityId('c4', C4_MERMAID_FORMAT.id, 'export'),
+    framework: 'c4',
+    format: C4_MERMAID_FORMAT,
+    direction: 'export',
+    run: runC4MermaidExport,
+};
+/** Everything C4 registers, in one list the view extension can hand over. */
+export const C4_INTERCHANGE = [
+    C4_MERMAID_EXPORT,
+];

package/dist/legend.d.ts

@@ -0,0 +1,37 @@
+import { type AutoLegendSpec } from '@formicoidea/labre-ddd-shared';
+/**
+ * What the C4 board's automatic legend can say — a TABLE, and nothing else: the
+ * scan, the placement and the box are `createAutoLegend`'s job, shared with the
+ * three DDD boards.
+ *
+ * Every row is DERIVED twice over: its WORDING from the role vocabulary's own
+ * `labelFallback` ({@link roleLabel}), and its COLOUR from the very palette the
+ * creation site paints with ({@link NODE_PALETTE}). Neither is restated here, so
+ * renaming a role renames its legend row and restyling the pack restyles its
+ * swatches — which is what keeps a legend a description of the board rather than
+ * a second opinion about it.
+ *
+ * ## Why `exact` on the container, and only there
+ *
+ * `c4:database` specialises `c4:container`, so an inclusive entry on the parent
+ * would put a "Container" row — with the container's blue square — on a board
+ * carrying nothing but cylinders. The row would name a shape that is nowhere on
+ * the diagram. EDGY's four base kinds hit this first and `AutoLegendEntry.exact`
+ * exists for it: base and specialisation become two separate statements, each
+ * listed when it is the thing the user actually drew.
+ *
+ * The other four element roles are childless, so `exact` would change nothing
+ * for them and is left off — the flag marks the places where the distinction is
+ * real.
+ *
+ * ## What is missing, and why
+ *
+ * `mobile` and `browser` get no row of their own: they carry `c4:container`,
+ * because a phone app and a single-page app are containers with a picture
+ * (`roles.ts`). Detection is by role and only by role, so a board of nothing but
+ * mobile apps lists "Container" — which is the honest answer about what the
+ * boxes MEAN. `person-ext` and `system-ext` collapse the same way onto person
+ * and system, for the same reason: the grey says "out of scope", not "a
+ * different sort of thing".
+ */
+export declare const C4_AUTO_LEGEND: AutoLegendSpec;

package/dist/legend.js

@@ -0,0 +1,123 @@
+import { roleLabel } from '@formicoidea/labre-ddd-shared';
+import { BOUNDARY_STROKE, NODE_PALETTE, RELATIONSHIP_STROKE } from './consts.js';
+import { C4_ROLE, C4_ROLES } from './roles.js';
+/**
+ * What the C4 board's automatic legend can say — a TABLE, and nothing else: the
+ * scan, the placement and the box are `createAutoLegend`'s job, shared with the
+ * three DDD boards.
+ *
+ * Every row is DERIVED twice over: its WORDING from the role vocabulary's own
+ * `labelFallback` ({@link roleLabel}), and its COLOUR from the very palette the
+ * creation site paints with ({@link NODE_PALETTE}). Neither is restated here, so
+ * renaming a role renames its legend row and restyling the pack restyles its
+ * swatches — which is what keeps a legend a description of the board rather than
+ * a second opinion about it.
+ *
+ * ## Why `exact` on the container, and only there
+ *
+ * `c4:database` specialises `c4:container`, so an inclusive entry on the parent
+ * would put a "Container" row — with the container's blue square — on a board
+ * carrying nothing but cylinders. The row would name a shape that is nowhere on
+ * the diagram. EDGY's four base kinds hit this first and `AutoLegendEntry.exact`
+ * exists for it: base and specialisation become two separate statements, each
+ * listed when it is the thing the user actually drew.
+ *
+ * The other four element roles are childless, so `exact` would change nothing
+ * for them and is left off — the flag marks the places where the distinction is
+ * real.
+ *
+ * ## What is missing, and why
+ *
+ * `mobile` and `browser` get no row of their own: they carry `c4:container`,
+ * because a phone app and a single-page app are containers with a picture
+ * (`roles.ts`). Detection is by role and only by role, so a board of nothing but
+ * mobile apps lists "Container" — which is the honest answer about what the
+ * boxes MEAN. `person-ext` and `system-ext` collapse the same way onto person
+ * and system, for the same reason: the grey says "out of scope", not "a
+ * different sort of thing".
+ */
+export const C4_AUTO_LEGEND = {
+    title: 'Legend',
+    width: 290,
+    roles: C4_ROLES,
+    sections: [
+        {
+            title: 'Elements',
+            entries: [
+                {
+                    role: C4_ROLE.person,
+                    row: {
+                        swatch: 'square',
+                        color: NODE_PALETTE.person.fill,
+                        label: roleLabel(C4_ROLES, C4_ROLE.person),
+                    },
+                },
+                {
+                    role: C4_ROLE.system,
+                    row: {
+                        swatch: 'square',
+                        color: NODE_PALETTE.system.fill,
+                        label: roleLabel(C4_ROLES, C4_ROLE.system),
+                    },
+                },
+                {
+                    role: C4_ROLE.container,
+                    // See the note above: a board of cylinders must not claim a container.
+                    exact: true,
+                    row: {
+                        swatch: 'square',
+                        color: NODE_PALETTE.container.fill,
+                        label: roleLabel(C4_ROLES, C4_ROLE.container),
+                    },
+                },
+                {
+                    role: C4_ROLE.database,
+                    row: {
+                        swatch: 'square',
+                        color: NODE_PALETTE.database.fill,
+                        label: roleLabel(C4_ROLES, C4_ROLE.database),
+                    },
+                },
+                {
+                    role: C4_ROLE.component,
+                    row: {
+                        swatch: 'square',
+                        color: NODE_PALETTE.component.fill,
+                        label: roleLabel(C4_ROLES, C4_ROLE.component),
+                    },
+                },
+            ],
+        },
+        {
+            title: 'Frames',
+            entries: [
+                {
+                    role: C4_ROLE.boundary,
+                    row: {
+                        // A line, not a square: a boundary has no body — it is the dashed
+                        // frame itself, and a filled swatch would draw the one thing this
+                        // background deliberately does not paint.
+                        swatch: 'line',
+                        color: BOUNDARY_STROKE,
+                        dashed: true,
+                        label: roleLabel(C4_ROLES, C4_ROLE.boundary),
+                    },
+                },
+            ],
+        },
+        {
+            title: 'Relations',
+            entries: [
+                {
+                    role: C4_ROLE.relationship,
+                    row: {
+                        swatch: 'line',
+                        color: RELATIONSHIP_STROKE,
+                        dashed: true,
+                        label: roleLabel(C4_ROLES, C4_ROLE.relationship),
+                    },
+                },
+            ],
+        },
+    ],
+};

package/dist/levels.d.ts

@@ -0,0 +1,70 @@
+import type { C4BoardLevel } from '@formicoidea/labre-core/model';
+/**
+ * The LEVEL a board declares, as the picker offers it — DATA, like everything
+ * else this framework contributes.
+ *
+ * A C4 diagram is drawn at one level: the context of a system, the containers
+ * inside it, the components inside one of those. Which one a sheet is showing
+ * used to live nowhere the tool could read — the title is free text, and a board
+ * called "Payments" says nothing about which of the three it is. So the board
+ * carries an optional `level` (`C4BoardElementModel`), this table is the words
+ * for it, and `rules.ts` is what judges the sheet against it.
+ *
+ * ## The title stays the author's
+ *
+ * Choosing a level RENAMES NOTHING. The level is a declared fact sitting beside
+ * the title, not a replacement for it: a context diagram of the payments
+ * platform is still called whatever its author called it, and the picker writes
+ * one prop and touches no other.
+ *
+ * ## Why "Free sketch" is an option and not the absence of one
+ *
+ * The default is no level at all, and it has to be REACHABLE: a user who set a
+ * level and then decided the sheet is a working surface after all must be able
+ * to say so, and the way back cannot be "delete the board and draw another".
+ * Picking it CLEARS the field rather than writing a fourth value — the same call
+ * the validation profile picker makes for its default level of requirement — so
+ * a board on Free sketch is byte-identical to every C4 board drawn before this
+ * existed.
+ *
+ * ## All four C's are offered, `code` included
+ *
+ * C4 is named after Context, Containers, Components and Code, and the picker
+ * says all four. The fourth is the one C4's own author tells you to skip unless
+ * the picture is generated from the source, and this editor draws no code-level
+ * artefact — but that is a fact about the TOOLING, not about what a sheet may
+ * declare. An architect keeping a board for the class diagram they paste in from
+ * elsewhere is entitled to say what it is, and a picker that refused would be
+ * presenting our limitation as the notation's.
+ *
+ * Two of the four are judged by no rule at all — `component` and `code` — and
+ * `rules.ts` says why: a component diagram legitimately shows everything C4
+ * names, and nothing in the pack knows what a code diagram admits. Both are
+ * declarations the tool records and does not check, which is a perfectly honest
+ * thing for a declaration to be.
+ */
+export interface C4BoardLevelOption {
+    /**
+     * What gets written on the board — or `undefined`, which CLEARS the field and
+     * puts the sheet back to a free sketch.
+     */
+    level: C4BoardLevel | undefined;
+    /** i18n key of the entry's words; resolved by the host. */
+    labelKey: string;
+    /** The framework's own wording, for a host that ships no catalogue. */
+    labelFallback: string;
+}
+/**
+ * The picker, whole: its own heading and its five entries, in the order a
+ * reader zooms — no level, then the four C's from out to in.
+ *
+ * One object rather than a loose array plus a stray heading constant, because
+ * the manifest walks DECLARATIONS: `c4TranslationEntries` hands this value to
+ * `collectTranslationKeys` and every key below reaches a host's catalogue with
+ * nothing restated anywhere.
+ */
+export declare const C4_BOARD_LEVEL_MENU: {
+    labelKey: string;
+    labelFallback: string;
+    options: readonly C4BoardLevelOption[];
+};

package/dist/levels.js

@@ -0,0 +1,46 @@
+/** i18n key stem: `context` → `com.labre.c4.level.context`. */
+const levelKey = (name) => `com.labre.c4.level.${name}`;
+/**
+ * The picker, whole: its own heading and its five entries, in the order a
+ * reader zooms — no level, then the four C's from out to in.
+ *
+ * One object rather than a loose array plus a stray heading constant, because
+ * the manifest walks DECLARATIONS: `c4TranslationEntries` hands this value to
+ * `collectTranslationKeys` and every key below reaches a host's catalogue with
+ * nothing restated anywhere.
+ */
+export const C4_BOARD_LEVEL_MENU = {
+    labelKey: levelKey('section'),
+    labelFallback: 'Level',
+    options: [
+        {
+            // The default, and the only entry that writes nothing.
+            level: undefined,
+            labelKey: levelKey('none'),
+            labelFallback: 'Free sketch',
+        },
+        {
+            level: 'context',
+            labelKey: levelKey('context'),
+            labelFallback: 'Context',
+        },
+        {
+            level: 'container',
+            labelKey: levelKey('container'),
+            labelFallback: 'Container',
+        },
+        {
+            level: 'component',
+            labelKey: levelKey('component'),
+            labelFallback: 'Component',
+        },
+        {
+            // The fourth C. Recorded, exported and readable; judged by no rule — see
+            // the header, and `rules.ts` on why an empty forbidden list is data that
+            // can never fire.
+            level: 'code',
+            labelKey: levelKey('code'),
+            labelFallback: 'Code',
+        },
+    ],
+};

package/dist/morph.d.ts

@@ -0,0 +1,89 @@
+import { type MorphSpec } from '@formicoidea/labre-core/blocks/surface';
+import { C4NodeElementModel, type C4NodeKind } from '@formicoidea/labre-core/model';
+import type { GfxPrimitiveElementModel } from '@formicoidea/labre-core/std/gfx';
+/**
+ * What a C4 artefact may BECOME — the declaration behind the "Change type"
+ * dropdown on a selected component's contextual toolbar.
+ *
+ * ## Families, and the one thing that makes them safe here
+ *
+ * A person and an external person are the same actor, said with a different
+ * ownership; a container, a database, a mobile app and a browser app are the
+ * same level of the model, drawn with different silhouettes. Realising halfway
+ * through a container diagram that the box should have been the cylinder is
+ * modelling, not a mistake — and the only way through it today is delete,
+ * re-draw, re-connect, and retype three tiers of words.
+ *
+ * The three families below are DATA. Nothing derives them, and the role tree
+ * would have been the wrong source in the same way it is for BPMN: `roleIsA`
+ * makes `c4:database` a `c4:container`, so a derivation would reach in one
+ * direction and not the other, and it says nothing at all about
+ * `person`/`person-ext`, which are ONE role and still two artefacts.
+ *
+ * What makes these three families cheap is a property they happen to have and
+ * a later one may not: **every member of a family lays its words out
+ * identically**. `c4TierBoxes` differs on exactly one thing — the person's head
+ * clearance, which both people share — and `NODE_SIZE` on exactly one, the
+ * person's taller silhouette, which both people also share. So a morph inside
+ * a family needs no re-layout at all: the three tiers stay where they are, the
+ * group's derived box stays what it was, and the geometry a morph promises not
+ * to touch is genuinely untouched. `component` is deliberately in NO family
+ * partly for that reason and mostly for a better one: a component is a part of
+ * a container, not another drawing of one, and offering the swap would invite
+ * a diagram that mixes two levels of the model — the one thing C4 exists to
+ * stop. The two boundaries are frames rather than artefacts and are excluded
+ * for the reason `roles.ts` gives.
+ */
+export declare const C4_MORPH_FAMILIES: readonly (readonly C4NodeKind[])[];
+/**
+ * The `c4Node` shape a selected GROUP is the component of — `undefined` when
+ * the group is not one.
+ *
+ * A C4 component is a native `group` holding the shape and its three lines of
+ * words (PO recette, 28/08/2026), so what a click selects is the group and what
+ * carries `kind` is the shape. This is the whole of the indirection, and it is
+ * also the gate: a plain group somebody lassoed round three rectangles, a
+ * Wardley component (a group of a circle and its label) and a group of two C4
+ * components all answer `undefined`, so none of them is ever offered the menu.
+ *
+ * TWO shapes is a refusal rather than a first-wins pick. A group holding two
+ * components is a group somebody made of two components — morphing "it" would
+ * mean picking one of them by document order, and the honest answer to an
+ * ambiguous selection is the same one the generic module gives to a mixed
+ * family: nothing.
+ */
+export declare function c4NodeOfComponent(model: GfxPrimitiveElementModel): C4NodeElementModel | undefined;
+/**
+ * The name a component should carry once its shape has morphed — or `null`
+ * when the name is the AUTHOR's and must not be touched.
+ *
+ * Exactly one case rewrites: the title is the source kind's own creation
+ * prompt, letter for letter, which is what a component nobody has named still
+ * says. Everything else — a name typed over it, a prompt with a word added, a
+ * cleared title, another kind's prompt — is content, and content survives a
+ * morph untouched.
+ *
+ * This is the tier the type line does NOT cover, and the only one where a user
+ * sees the contradiction: {@link NODE_LABEL} differs across the container
+ * family where `C4_TYPE_WORD` does not, so a fresh container morphed to a
+ * database would otherwise be a cylinder captioned "Container".
+ *
+ * Pure and total over every string, like its sibling in `type-line.ts`: the
+ * input is a canvas text element somebody may have typed anything into.
+ */
+export declare function c4MorphedTitle(from: C4NodeKind, to: C4NodeKind, rawText: string | null | undefined): string | null;
+/**
+ * C4's morph declaration, handed to the generic `morphToolbarConfig`.
+ *
+ * `modelType` is the native `GroupElementModel` and not `C4NodeElementModel`,
+ * because the group is what a click on a component selects. Everything that
+ * makes that safe is in {@link c4NodeOfComponent}: the toolbar's own
+ * homogeneity test only proves that every selected element is A group, and the
+ * resolution proves that every one of them is one of OURS.
+ *
+ * `propsOf` is the shipped creation builder minus `type` / `xywh` / `text`
+ * ({@link c4MorphProps}), so the palette and the morph cannot disagree about
+ * what a database looks like; `clearOf` is empty on today's table and derived
+ * rather than assumed so (`presets.ts`).
+ */
+export declare const C4_MORPH_SPEC: MorphSpec<C4NodeKind>;