@formicoidea/labre-framework-c4 0.33.0

package/dist/background.js

@@ -0,0 +1,223 @@
+import { BOARD_BORDER_WIDTH, BOARD_CARD_BORDER, BOARD_CARD_FILL, BOARD_CORNER_RADIUS, BOARD_MARGIN, BOARD_REF_HEIGHT, BOARD_REF_WIDTH, BOARD_TITLE_COLOR, BOARD_TITLE_FONT_SIZE, BOARD_TITLE_MARGIN, BOUNDARY_CORNER_RADIUS, BOUNDARY_DASH, BOUNDARY_MARGIN, BOUNDARY_NAME_COLOR, BOUNDARY_NAME_FONT_SIZE, BOUNDARY_NAME_INSET, BOUNDARY_REF_HEIGHT, BOUNDARY_REF_WIDTH, BOUNDARY_STROKE, BOUNDARY_TYPE_FONT_SIZE, BOUNDARY_TYPE_STEP, BOUNDARY_WIDTH, FONT_FAMILY, } from './consts.js';
+import { C4_ROLE } from './roles.js';
+/**
+ * The two C4 frames, DECLARED (the `FrameworkBackgroundDef` primitive).
+ *
+ * There is no C4 drawing code for either of them: the primitive paints these
+ * declarations, and would paint any other framework's the same way
+ * (`docs/adr/0009` on why a framework declares rather than draws).
+ */
+/* ── The board ─────────────────────────────────────────────────────────── */
+/**
+ * The C4 board: a titled white card, and nothing else.
+ *
+ * **No axes and no zones**, exactly like the Context Map board this is modelled
+ * on, and for the same reason: a C4 diagram is a GRAPH, not a chart. A system
+ * drawn top left says nothing more than one drawn bottom right, and graduating
+ * the card would invent a frame of reference C4 does not have — and then judge
+ * people against it.
+ *
+ * What the declaration is for here is the ROLE, the geometry and the TITLE:
+ * `c4:board` is what a rule frames its subjects against, and the title is what
+ * says which of the four levels this particular sheet is drawing.
+ *
+ * ## Why the title is declared as a zone label
+ *
+ * The primitive knows three places words can come from: a side band's label, a
+ * zone's label and an axis' title (`backgroundTexts`). A board has no band and
+ * no axis, so a single full-plot zone — no fill, no tint, nothing painted but
+ * its name — is what carries the title. That keeps it on the ONE walk both the
+ * renderer and the hit tester use, which is what makes the words the user
+ * double-clicks the same words they see (`C4BoardView`).
+ */
+export const C4_BOARD_BACKGROUND = {
+    type: 'c4Board',
+    role: C4_ROLE.board,
+    geometry: {
+        // Wide and free, the Context Map board's own call: a C4 diagram grows
+        // sideways as the system is discovered, so neither dimension is locked to
+        // the other and the handles are offered from the start.
+        width: BOARD_REF_WIDTH,
+        height: BOARD_REF_HEIGHT,
+        lockAspectRatio: false,
+        resizable: true,
+        // Only the top margin is deep: that is where the title is written.
+        margin: {
+            top: BOARD_TITLE_MARGIN,
+            right: BOARD_MARGIN,
+            bottom: BOARD_MARGIN,
+            left: BOARD_MARGIN,
+        },
+    },
+    zones: [
+        {
+            id: 'title',
+            // The whole plot, and nothing painted over it: this zone exists to carry
+            // a label, not to tint a region. Reported by the audit as one zone
+            // covering the board, which is the honest answer — a C4 board has exactly
+            // one region and it is the board.
+            rect: { x: 0, y: 0, w: 1, h: 1 },
+            label: {
+                id: 'name',
+                // The user's own words, and only those: a diagram is titled by whoever
+                // draws it, so there is no vocabulary to fall back to and no `labelKey`
+                // to declare. Same call the BPMN pool's participant name makes.
+                prop: 'name',
+                // `y: 0` is the top of the plot; a negative `dy` walks back UP into the
+                // title margin, where the words are written.
+                anchor: { x: 0, y: 0, dy: -BOARD_TITLE_MARGIN / 3 },
+                style: {
+                    size: BOARD_TITLE_FONT_SIZE,
+                    weight: 600,
+                    color: '@title',
+                },
+            },
+        },
+    ],
+    chrome: {
+        fontFamily: FONT_FAMILY,
+        palette: {
+            card: BOARD_CARD_FILL,
+            cardBorder: BOARD_CARD_BORDER,
+            title: BOARD_TITLE_COLOR,
+        },
+        surface: {
+            fill: '@card',
+            border: {
+                color: '@cardBorder',
+                width: BOARD_BORDER_WIDTH,
+                radius: BOARD_CORNER_RADIUS,
+            },
+        },
+    },
+};
+/* ── The boundary ──────────────────────────────────────────────────────── */
+/**
+ * The C4 boundary: a dashed rectangle with its name in the bottom-left corner.
+ *
+ * The one background in the library that is deliberately TRANSPARENT. Every
+ * other one is a card you put things on — a Wardley map, a pool, a board — and
+ * the PO's recette of 26/08/2026 settled that they all paint white. A boundary
+ * is the opposite object: it is drawn OVER a diagram, round elements that are
+ * already there, and an opaque card would hide the very thing it is pointing at.
+ * So it declares a border and no fill, which the primitive paints as an unfilled
+ * frame.
+ *
+ * The consequence is worth stating because it is the reverse of the usual one: a
+ * boundary dropped over existing elements does NOT cover them, and it is not
+ * hit anywhere but on its own frame area — it is a lasso, in the same sense
+ * BPMN's group is.
+ *
+ * ## The dash
+ *
+ * Declared, not drawn: `surface.border.dash` was added to the primitive for this
+ * (see `BackgroundSurfaceDef`). It is the whole distinction between a boundary
+ * and a board at a glance, so it belongs where the rest of the frame is
+ * declared, in data a reviewer can read.
+ *
+ * ## The variant, and the bracket line it decides
+ *
+ * The stencil writes TWO lines in that corner: the author's name, and under it
+ * the level — `[Software System]` or `[Container]`. The second is derived from
+ * the variant and is therefore VOCABULARY, declared with a `labelKey` and no
+ * `prop`: it is translatable through the host's catalogue, and it is not offered
+ * to the in-place editor, because what kind of boundary this is was said by
+ * picking the tool rather than by typing.
+ *
+ * `variantProp` names {@link C4BoundaryElementModel.variantOrDefault} rather
+ * than `variant` itself, and that is the whole trick. `variant` is OPTIONAL: an
+ * unstated one stringifies to `"undefined"`, matches no declared variant and
+ * would paint NOTHING — which is exactly why this declaration used to declare no
+ * `variantProp` at all and let the creation site's default NAME carry the
+ * distinction. The derived getter applies the documented default (`'system'`)
+ * before the gate sees it, so every boundary — including every one already on
+ * disk, which stored nothing — reads as a real variant and gets its line.
+ *
+ * The default NAME still lives at the creation site (`BOUNDARY_LABEL` in
+ * `consts.ts`) and is still the author's from that moment on: renaming a
+ * boundary never contradicts its variant, and never silences its bracket line.
+ */
+export const C4_BOUNDARY_BACKGROUND = {
+    type: 'c4Boundary',
+    role: C4_ROLE.boundary,
+    geometry: {
+        width: BOUNDARY_REF_WIDTH,
+        height: BOUNDARY_REF_HEIGHT,
+        // A boundary is stretched to fit whatever it has been drawn round, which is
+        // never the same shape twice.
+        lockAspectRatio: false,
+        resizable: true,
+        margin: {
+            top: BOUNDARY_MARGIN,
+            right: BOUNDARY_MARGIN,
+            bottom: BOUNDARY_MARGIN,
+            left: BOUNDARY_MARGIN,
+        },
+    },
+    // The level this instance encloses, with the optional field's documented
+    // default already applied — see the note above on why it is the DERIVED
+    // getter and not `variant` itself.
+    variantProp: 'variantOrDefault',
+    zones: [
+        {
+            id: 'name',
+            rect: { x: 0, y: 0, w: 1, h: 1 },
+            label: {
+                id: 'name',
+                prop: 'name',
+                // Bottom-left INSIDE the plot — the corner C4 writes a boundary's name
+                // in, and the one corner of a frame that is least likely to have an
+                // element sitting in it. It sits one bracket-line step up, because the
+                // line below it is the level.
+                anchor: {
+                    x: 0,
+                    y: 1,
+                    dy: -(BOUNDARY_NAME_INSET + BOUNDARY_TYPE_STEP),
+                },
+                style: {
+                    size: BOUNDARY_NAME_FONT_SIZE,
+                    weight: 600,
+                    color: '@name',
+                },
+            },
+        },
+        // …and the bracket line under it, one zone per variant. Two zones rather
+        // than one label with two wordings because a zone carries exactly one
+        // label, and the gate that picks between them is the zone's own `variants`
+        // — which `backgroundTexts` propagates onto the label it carries.
+        ...['system', 'container'].map(variant => ({
+            id: `type-${variant}`,
+            variants: [variant],
+            rect: { x: 0, y: 0, w: 1, h: 1 },
+            label: {
+                id: `type-${variant}`,
+                // NO `prop`: this is vocabulary, so it is translatable and it is not
+                // offered to the in-place editor. The fallback is the stencil's own
+                // wording, brackets included.
+                labelKey: `com.labre.c4.boundary.type.${variant}`,
+                fallback: variant === 'system' ? '[Software System]' : '[Container]',
+                anchor: { x: 0, y: 1, dy: -BOUNDARY_NAME_INSET },
+                style: {
+                    size: BOUNDARY_TYPE_FONT_SIZE,
+                    color: '@name',
+                },
+            },
+        })),
+    ],
+    chrome: {
+        fontFamily: FONT_FAMILY,
+        palette: {
+            frame: BOUNDARY_STROKE,
+            name: BOUNDARY_NAME_COLOR,
+        },
+        surface: {
+            // NO fill — see the note above. This is the transparent one.
+            border: {
+                color: '@frame',
+                width: BOUNDARY_WIDTH,
+                radius: BOUNDARY_CORNER_RADIUS,
+                dash: BOUNDARY_DASH,
+            },
+        },
+    },
+};

package/dist/commands.d.ts

@@ -0,0 +1,4 @@
+import type { CommandDescriptor } from '@formicoidea/labre-core/std';
+import type { TemplateResult } from 'lit';
+export declare const c4Commands: CommandDescriptor[];
+export declare const c4CommandIcons: Record<string, TemplateResult>;

package/dist/commands.js

@@ -0,0 +1,221 @@
+import { activateC4Relationship, c4BoardsForExport, createC4Board, createC4Boundary, createC4Node, exportC4MermaidFile, } from './actions.js';
+import { c4ExportMermaidIcon, C4_TOOLBOX_ICONS } from './toolbar/icons.js';
+const SPECS = [
+    /* ── Boards first: the sheet everything else is drawn on ────────────── */
+    {
+        id: 'addBoard',
+        label: 'C4 board',
+        iconKey: 'c4.board',
+        kind: 'artefact',
+        category: 'diagrams',
+        element: 'board',
+        run: createC4Board,
+    },
+    /* ── The base components: the four levels, each plain form immediately
+         followed by its external variant ─────────────────────────────────── */
+    {
+        id: 'addPerson',
+        label: 'Person',
+        iconKey: 'c4.person',
+        kind: 'artefact',
+        category: 'elements',
+        element: 'node:person',
+        run: std => createC4Node(std, 'person'),
+    },
+    {
+        id: 'addPersonExt',
+        label: 'Person (external)',
+        iconKey: 'c4.person.external',
+        kind: 'artefact',
+        category: 'elements',
+        element: 'node:person-ext',
+        run: std => createC4Node(std, 'person-ext'),
+    },
+    {
+        id: 'addSystem',
+        label: 'Software system',
+        iconKey: 'c4.system',
+        kind: 'artefact',
+        category: 'elements',
+        element: 'node:system',
+        run: std => createC4Node(std, 'system'),
+    },
+    {
+        id: 'addSystemExt',
+        label: 'Software system (external)',
+        iconKey: 'c4.system.external',
+        kind: 'artefact',
+        category: 'elements',
+        element: 'node:system-ext',
+        run: std => createC4Node(std, 'system-ext'),
+    },
+    {
+        id: 'addContainer',
+        label: 'Container',
+        iconKey: 'c4.container',
+        kind: 'artefact',
+        category: 'elements',
+        element: 'node:container',
+        run: std => createC4Node(std, 'container'),
+    },
+    {
+        id: 'addComponent',
+        label: 'Component',
+        iconKey: 'c4.component',
+        kind: 'artefact',
+        category: 'elements',
+        element: 'node:component',
+        run: std => createC4Node(std, 'component'),
+    },
+    /* ── The niche components: a container with a picture on it ─────────── */
+    {
+        // The container flavour every real system has one of, and the only one with
+        // a role of its own — so it leads the three.
+        id: 'addDatabase',
+        label: 'Database',
+        iconKey: 'c4.database',
+        kind: 'artefact',
+        category: 'elements',
+        element: 'node:database',
+        run: std => createC4Node(std, 'database'),
+    },
+    {
+        id: 'addMobile',
+        label: 'Mobile app',
+        iconKey: 'c4.mobile',
+        kind: 'artefact',
+        category: 'elements',
+        element: 'node:mobile',
+        run: std => createC4Node(std, 'mobile'),
+    },
+    {
+        id: 'addBrowser',
+        label: 'Web browser',
+        iconKey: 'c4.browser',
+        kind: 'artefact',
+        category: 'elements',
+        element: 'node:browser',
+        run: std => createC4Node(std, 'browser'),
+    },
+    /* ── What joins the components, then the frames drawn round them ────── */
+    {
+        // C4 asks every relationship to be READ as a sentence, and the tool is where
+        // the author says which way it runs.
+        id: 'relationshipTool',
+        label: 'Relationship',
+        iconKey: 'c4.relationship',
+        kind: 'tool',
+        category: 'relations',
+        element: 'connector:relationship',
+        run: activateC4Relationship,
+    },
+    {
+        id: 'addSystemBoundary',
+        label: 'System boundary',
+        iconKey: 'c4.boundary.system',
+        kind: 'artefact',
+        category: 'boundaries',
+        element: 'boundary:system',
+        run: std => createC4Boundary(std, 'system'),
+    },
+    {
+        id: 'addContainerBoundary',
+        label: 'Container boundary',
+        iconKey: 'c4.boundary.container',
+        kind: 'artefact',
+        category: 'boundaries',
+        element: 'boundary:container',
+        run: std => createC4Boundary(std, 'container'),
+    },
+];
+const toolboxCommands = SPECS.map((spec, order) => ({
+    id: `c4.${spec.id}`,
+    owner: 'c4',
+    kind: spec.kind,
+    labelKey: `com.labre.commands.c4.${spec.id}`,
+    labelFallback: spec.label,
+    category: spec.category,
+    iconKey: spec.iconKey,
+    // All thirteen, on every surface: the catalogue is the total surface and the
+    // sub-menu holds fourteen, so nothing has to be left out of either.
+    surfaces: ['senior-menu', 'catalogue', 'palette', 'agent'],
+    order,
+    scope: 'edgeless',
+    // Keyless by intent — still bindable from Settings › Shortcuts, which is what
+    // `toShortcutDescriptor` being total buys.
+    defaultKeys: { mac: [], other: [] },
+    availability: 'always',
+    run: spec.run,
+    telemetry: { framework: 'c4', element: spec.element },
+}));
+/**
+ * The EXPORT — the first C4 command whose subject is a whole BOARD.
+ *
+ * ## Why it hangs off the board's toolbar, and why the board is also the scope
+ *
+ * BPMN's export makes the opposite call and the difference is the notation's,
+ * not a preference. A BPMN document is a process and half a process is not a
+ * smaller process, so `bpmn.exportXml` serializes the whole surface and the
+ * selected pool decides only the filename. A C4 board is one LEVEL of one model
+ * — a context diagram, a container diagram, a component diagram — and the whole
+ * point of drawing three of them side by side is that they are three separate
+ * diagrams. Merging them would produce the picture C4 exists to stop people
+ * drawing, and mermaid renders one diagram per document anyway. So the selection
+ * is the scope: one board, one document; several boards, several documents in
+ * one file.
+ *
+ * ## Surfaces
+ *
+ * It declines `'senior-menu'`: the sub-menu is what you reach for to DRAW
+ * something, and this draws nothing — and C4 has exactly one senior slot left,
+ * which an export would be a poor use of. It keeps `'catalogue'`, which is not a
+ * category claim but the registry's own invariant: the catalogue is the TOTAL
+ * surface, and a command missing from it is unreachable the moment its framework
+ * overflows the fourteen slots (pinned by `registry.unit.spec.ts`). It is also
+ * what makes the catalogue exactly fourteen — the cap, to the entry.
+ *
+ * On the row itself it sits in the "⋮" rather than as a button: it is the rarest
+ * thing anybody does to a board, and the row already carries the resize toggle
+ * and the legend.
+ *
+ * ## Where the "⋮" entry is registered
+ *
+ * In the ALWAYS-ON toolbar module (`c4BoardToolbarConfig`), not the flag-gated
+ * one, which is where BPMN puts its own export entry: `bpmnPoolToolbarExtension`
+ * carries `bpmn.exportXml` and is registered by `BpmnRenderViewExtension`. The
+ * entry hides itself when the command is absent from the registry — the `when`
+ * guard every `commandAction` carries — so with the C4 tooling flag off the row
+ * is the resize toggle alone, and nothing on it can be clicked into a no-op.
+ */
+const exportCommand = {
+    id: 'c4.exportMermaid',
+    owner: 'c4',
+    kind: 'action',
+    labelKey: 'com.labre.commands.c4.exportMermaid',
+    labelFallback: 'Export as mermaid',
+    descriptionKey: 'com.labre.commands.c4.exportMermaid.description',
+    descriptionFallback: 'Download the selected board as a mermaid C4 diagram, ready to paste into any mermaid renderer.',
+    // Filed with the board, which is the selection that offers it.
+    category: 'diagrams',
+    iconKey: 'c4.export-mermaid',
+    surfaces: ['catalogue', 'contextual-toolbar', 'palette', 'agent'],
+    order: SPECS.length,
+    scope: 'edgeless',
+    defaultKeys: { mac: [], other: [] },
+    availability: 'selection',
+    run: exportC4MermaidFile,
+    telemetry: { framework: 'c4', element: 'board:export-mermaid' },
+    // A board in the selection, and no more than that: an export READS, so unlike
+    // the legend button it is offered on a read-only document — which is precisely
+    // the board somebody wants to take away. That is what `c4BoardsForExport` is,
+    // and why it is not `c4BoardsSelected`.
+    when: std => c4BoardsForExport(std).length > 0,
+};
+export const c4Commands = [
+    ...toolboxCommands,
+    exportCommand,
+];
+export const c4CommandIcons = {
+    ...C4_TOOLBOX_ICONS,
+    'c4.export-mermaid': c4ExportMermaidIcon,
+};

package/dist/component.d.ts

@@ -0,0 +1,192 @@
+import type { C4NodeKind } from '@formicoidea/labre-core/model';
+/**
+ * A C4 component — the SHAPE and its own words, grouped.
+ *
+ * ## What the PO's recette of 28/08/2026 changed
+ *
+ * A C4 element used to be one shape carrying a title, plus two fields edited in
+ * a "Details" popover and painted underneath by the renderer. The verdict was
+ * that the popover is the wrong mechanism: an architect writes ON the picture.
+ * So a component is now a native `group` holding three elements —
+ *
+ *  1. the `c4Node` shape, whose native inner text is the TITLE;
+ *  2. a canvas `text` element carrying the type line, `[Container: Java]`;
+ *  3. a canvas `text` element carrying the description —
+ *
+ * and every one of the three is edited in place, on a double-click, exactly like
+ * any other words on the canvas. There is no form left.
+ *
+ * ## This module
+ *
+ * The two questions that arise from that arrangement, both PURE and both free of
+ * `std`, so the creation site, the exporter, the commit hook and a test all
+ * answer them the same way:
+ *
+ *  - **where do the tiers go**, given a node's box ({@link c4TierBoxes});
+ *  - **which text belongs to which node**, given a flat list of elements
+ *    ({@link c4ComponentTiers}) — resolved by GROUP MEMBERSHIP plus the role
+ *    stamped on each text, never by position in `children`.
+ *
+ * The role stays on the SHAPE alone; the group carries none (`roles.ts`).
+ */
+/** A box in the same units and origin as the node's own. */
+export interface C4TierBox {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+}
+export interface C4TierBoxes {
+    title: C4TierBox;
+    typeLine: C4TierBox;
+    description: C4TierBox;
+}
+/**
+ * The three text boxes of a component, laid out against the node's own box.
+ *
+ * ## The rhythm
+ *
+ * A margin, the name over two lines, a small gap, the type line, a wider gap,
+ * the description over two, and the same margin again — which is exactly what
+ * {@link NODE_BOX} is tall enough for, because the box is derived from this
+ * stack rather than the stack fitted into the box. So the default element is
+ * neither cramped nor half empty, and the two gaps say what they mean: the name
+ * and its type line are one heading, the sentence under them is a second
+ * statement.
+ *
+ * The tiers are stacked by walking DOWN — each one placed under the last plus
+ * its gap — rather than by six independent offsets. Six offsets is six chances
+ * for two tiers to overlap; a walk cannot produce one.
+ *
+ * ## The person
+ *
+ * `bodyTop` is the one asymmetry and it is the stencil's: a person's head stands
+ * clear ABOVE a body of the standard height, and its words are laid out in the
+ * BODY (`v:textRect` is the body box exactly), so the whole stack starts below
+ * the head rather than across it.
+ *
+ * ## What this is not
+ *
+ * A creation-time answer and nothing more. The tiers are real elements from the
+ * moment they are drawn: an author who moves one has moved it, and nothing here
+ * runs again to put it back. It is also proportional in the one direction that
+ * matters — a node dragged taller keeps its margins where they were, because
+ * they are absolutes; only the person's head, which is a picture, scales.
+ */
+export declare function c4TierBoxes(kind: C4NodeKind, x: number, y: number, w: number, h: number): C4TierBoxes;
+/**
+ * The little a resolution needs to know about a text element — an id, a role,
+ * and whatever it says.
+ *
+ * `text` is `unknown` because on a real element it is a `Y.Text` and in a test
+ * it is a string, and this module has no business knowing which: it is read
+ * through {@link c4TierText}, which stringifies whatever it is given. That is
+ * also what keeps this file free of a Yjs import.
+ */
+export interface C4TierElement {
+    id: string;
+    role?: string;
+    text?: unknown;
+}
+/** The little a resolution needs to know about a group. */
+export interface C4ComponentGroup {
+    id: string;
+    childIds: readonly string[];
+}
+/** The three tiers of one node's component — any of them may be absent. */
+export interface C4ComponentTiers {
+    title?: C4TierElement;
+    typeLine?: C4TierElement;
+    description?: C4TierElement;
+}
+/**
+ * The tiers of the component a node belongs to — `{}` when it belongs to none.
+ *
+ * ## Group membership, then roles
+ *
+ * The group answers "which words are THIS node's" — two containers side by side
+ * both have a `[Container: …]` under them, and only the grouping says which is
+ * which. The role then answers "which of these words is the type line", which
+ * position in `children` cannot: a group's child order is an implementation
+ * detail that a reorder, a copy or a regroup rewrites, while a role is written
+ * on the element and travels with it.
+ *
+ * ## What a bare node resolves to, and why that is the right answer
+ *
+ * `{}` — no name, no technology, no description. Which is exactly what happens
+ * to a node whose group was released (native "ungroup"), to one whose texts were
+ * deleted, and to one drawn before this change. None of those is an error and
+ * none of them is guessed at: an element with no words on it states nothing, and
+ * the export says so by writing nothing. The picture is still a C4 element — the
+ * role is on the shape and survives everything.
+ *
+ * The NAME is the one tier with somewhere else to look, and only for the last of
+ * those three: an element drawn before the title became a child keeps its name
+ * in the shape's own inner text. See {@link c4StatedName}.
+ *
+ * The FIRST group holding the node wins, and the first text of each role in it.
+ * Groups nest, so a component grouped again inside a bigger group has two
+ * ancestors; document order picks the one written first, which is the innermost
+ * the creation site made.
+ */
+export declare function c4ComponentTiers(nodeId: string, groups: readonly C4ComponentGroup[], texts: readonly C4TierElement[]): C4ComponentTiers;
+/**
+ * Everything grouped with this element — `[]` when it is grouped with nothing.
+ *
+ * The other direction of the same question {@link c4ComponentTiers} asks, and
+ * the one the commit hook needs: given a type line somebody has just finished
+ * typing into, which shape does it belong to, so its kind can supply the word?
+ *
+ * The element itself is among the siblings, which is what the id list actually
+ * says and what saves the caller from reasoning about whether it was excluded.
+ */
+export declare function c4ComponentSiblings(elementId: string, groups: readonly C4ComponentGroup[]): readonly string[];
+/** Whatever a tier says, as a plain trimmed string. */
+export declare function c4TierText(tier: C4TierElement | undefined): string;
+/**
+ * The NAME a component states — its `c4:title` tier if it has one, and the
+ * shape's own inner text if it has not.
+ *
+ * ## No placeholder suppression, unlike the other two
+ *
+ * A fresh element's title reads `Container`, and that goes into the export
+ * verbatim. It is not a prompt standing in for a value the way
+ * `[Container: technology]` is: an unnamed container IS a container, and
+ * `Container(x, "Container")` is a true statement about a box somebody drew and
+ * has not named yet. Blanking it would hand the reader `?` instead — less
+ * information, not more honesty. The other two tiers suppress their prompts
+ * because "built with a technology called technology" is not true of anything.
+ *
+ * ## The fallback, and who needs it
+ *
+ * An element drawn before 28/08/2026 keeps its name in the SHAPE's native inner
+ * text, which is where that iteration put it, and it has no title child at all.
+ * That is the whole of the compatibility story and it costs one `??`: nothing is
+ * migrated, nothing is rewritten, and such an element exports exactly as it
+ * always did. The test is EXISTENCE of the tier, not whether it is empty — a
+ * component whose title the author deliberately cleared has been cleared, and
+ * reaching past it to a shape text that is not there either would say nothing
+ * different anyway.
+ */
+export declare function c4StatedName(tiers: C4ComponentTiers, shapeText: unknown): string;
+/**
+ * The technology a component STATES — `''` when it states none.
+ *
+ * The one place the creation placeholder is read as "nothing yet". Every tier
+ * exists from the moment a component is drawn, so an element nobody has typed on
+ * carries a literal `[Container: technology]`; exporting that as a technology
+ * would put the word "technology" in the technology slot of a file somebody is
+ * about to paste into a renderer.
+ *
+ * Deliberately NOT done in `technologyOfTypeLine`, which the commit hook also
+ * calls: normalising the placeholder to "nothing" would let a focus-and-blur
+ * silently rewrite `[Container: technology]` to `[Container]` and eat the
+ * stencil's own prompt. Reading and rewriting are different questions, and only
+ * the reader gets to be opinionated.
+ *
+ * The comparison is on the WORD rather than on the whole line, so it holds for
+ * every kind and for a placeholder an author moved brackets around.
+ */
+export declare function c4StatedTechnology(tier: C4TierElement | undefined): string;
+/** The description a component STATES — `''` for the untouched placeholder. */
+export declare function c4StatedDescription(tier: C4TierElement | undefined): string;