@formicoidea/labre-framework-c4 0.36.0 → 0.38.1

package/dist/index.d.ts

@@ -14,3 +14,4 @@ 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

@@ -54,3 +54,4 @@ export { c4TranslationEntries } from './translations.js';
 // 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/reading.d.ts

@@ -0,0 +1,8 @@
+import type { ReadingProfile } from '@formicoidea/labre-core/blocks/surface';
+export declare const C4_PERSON_READING: ReadingProfile;
+export declare const C4_SYSTEM_READING: ReadingProfile;
+/** Covers `c4:database`, the one specialisation in the pack. */
+export declare const C4_CONTAINER_READING: ReadingProfile;
+export declare const C4_COMPONENT_READING: ReadingProfile;
+/** Every C4 profile, in the order the view extension registers them. */
+export declare const C4_READINGS: readonly ReadingProfile[];

package/dist/reading.js

@@ -0,0 +1,85 @@
+import { C4_ROLE, C4_ROLES } from './roles.js';
+/**
+ * What a C4 diagram lets the tool read of an element (MF3, the reversed
+ * reading).
+ *
+ * DATA, like the rules and the profiles beside it: the engine
+ * (`@labre/affine-block-surface`) knows how to read a role and a typed edge — it
+ * knows nothing about C4. Everything below is already stated in `roles.ts` and
+ * is merely POINTED AT here.
+ *
+ * Registered from the FLAG-GATED view extension: reading a diagram is tooling,
+ * so a board whose C4 flag is off keeps every element it has and simply stops
+ * being read (ADR 0009).
+ *
+ * ## FOUR profiles, because the four levels are deliberately FLAT
+ *
+ * `roles.ts` argues it at length: the relation between the levels is
+ * COMPOSITION ("a container is part of a system"), not specialisation, and
+ * `roleIsA` means the second. Filing them in a chain to get one `appliesTo`
+ * would make "every rule about a system also falls on every container" true —
+ * the opposite of what C4 says — and minting a `c4:element` parent would be
+ * inventing an id the notation does not have (ADR 0007: an id is forever).
+ *
+ * So there is one profile per level, each with an id of its own (the DI keys on
+ * it and throws on a duplicate). `c4:database` needs none: it is the one real
+ * specialisation in the pack, a kind of container, and is read through the
+ * container's profile for free.
+ *
+ * The BOARD and the BOUNDARY (and its two children) are frames and are not read.
+ *
+ * ## The name lives on a separate element
+ *
+ * A C4 element is a composite — a shape, and three tiers of canvas text grouped
+ * with it — so every profile points `labelRole` at `c4:title`. Without it the
+ * panel would print an id at a human, and the relation lines would name the
+ * other end by id too.
+ *
+ * ## No nature, no phase
+ *
+ * C4 ships no type-3 tag pack: the levels ARE the roles, and the middle tier of
+ * the label (`c4:type-line`) already says the technology in the author's own
+ * words. And a board declares which of the three diagrams it draws, not a set of
+ * zones a position could be read against.
+ */
+/**
+ * The two words a relationship is read with, from the subject's end.
+ *
+ * ADR 0010 tier 1 and this role's own `direction`: the verb is "uses", so the
+ * SOURCE is the user. An edge leaving the subject names what it uses; one
+ * arriving names what uses it.
+ */
+const RELATIONSHIP = {
+    edgeRole: C4_ROLE.relationship,
+    sides: {
+        consumer: {
+            labelKey: 'com.labre.c4.reading.relations.consumer',
+            labelFallback: 'Used by',
+        },
+        supplier: {
+            labelKey: 'com.labre.c4.reading.relations.supplier',
+            labelFallback: 'Uses',
+        },
+    },
+};
+/** One level, as a profile. The four below differ by `id` and `appliesTo` only. */
+const level = (id, appliesTo) => ({
+    id,
+    framework: 'c4',
+    roles: C4_ROLES,
+    appliesTo,
+    labelRole: C4_ROLE.title,
+    relation: RELATIONSHIP,
+});
+export const C4_PERSON_READING = level('c4-person', C4_ROLE.person);
+export const C4_SYSTEM_READING = level('c4-system', C4_ROLE.system);
+/** Covers `c4:database`, the one specialisation in the pack. */
+export const C4_CONTAINER_READING = level('c4-container', C4_ROLE.container);
+export const C4_COMPONENT_READING = level('c4-component', C4_ROLE.component);
+/** Every C4 profile, in the order the view extension registers them. */
+export const C4_READINGS = [
+    C4_PERSON_READING,
+    C4_SYSTEM_READING,
+    C4_CONTAINER_READING,
+    C4_COMPONENT_READING,
+];

package/dist/templates.d.ts

@@ -0,0 +1,2 @@
+import { type TemplateCategory } from '@formicoidea/labre-core/gfx/template';
+export declare const c4TemplateCategory: TemplateCategory;

package/dist/templates.js

@@ -0,0 +1,68 @@
+import { templateFromCommand, } from '@formicoidea/labre-core/gfx/template';
+import { c4Commands } from './commands.js';
+import { BOARD_BAND_FILL, BOARD_CARD_BORDER, BOARD_CARD_FILL, BOUNDARY_STROKE, NODE_PALETTE, } from './consts.js';
+/**
+ * The C4 palette — DERIVED from the toolbox, one template per command.
+ *
+ * C4 was the ONE framework the Templates panel had no category for: the pack
+ * landed on 28/08/2026 with thirteen commands and nobody wrote the palette
+ * (audit of 09/09/2026, § 4.3). Writing it by hand was never an option — a C4
+ * component is five elements (a bodyless shape, three text tiers and the group
+ * that makes them one thing), created in painting order, and a hand-written
+ * restatement of that would have drifted from `actions.ts` the way every other
+ * framework's palette already had.
+ *
+ * So every entry below IS its command, run once against a recording surface, and
+ * `__tests__/templates-parity.unit.spec.ts` re-runs each one and compares. There
+ * is nothing hand-authored here to fall out of date: the day `createC4Node`
+ * changes, the palette changes with it.
+ *
+ * `relationshipTool` has no template on purpose — it ARMS the connector tool and
+ * draws nothing, so there is no artefact to record; `exportMermaid` is not an
+ * artefact command at all.
+ */
+/** The command a derived template is the picture of. Throws rather than skips. */
+function byId(id) {
+    const command = c4Commands.find(entry => entry.id === id);
+    if (!command)
+        throw new Error(`[c4] templates: no command "${id}"`);
+    return command;
+}
+const ATTRS = 'width="100%" height="100%" viewBox="0 0 135 80" xmlns="http://www.w3.org/2000/svg"';
+/** The two written lines every element carries, drawn as the words they are. */
+const words = (color, y) => `<g fill="${color}" opacity="0.85"><rect x="44" y="${y}" width="47" height="4" rx="2"/><rect x="52" y="${y + 8}" width="31" height="3" rx="1.5"/></g>`;
+/** A kind's body, in its own stencil colours — the plain box the levels share. */
+const boxPreview = (kind, extra = '') => {
+    const p = NODE_PALETTE[kind];
+    return `<svg ${ATTRS} fill="none"><rect x="30" y="20" width="75" height="40" fill="${p.fill}" stroke="${p.border}" stroke-width="2"/>${words(p.text, 32)}${extra}</svg>`;
+};
+/** The silhouette: a head standing clear of the same body. */
+const personPreview = (kind) => {
+    const p = NODE_PALETTE[kind];
+    return `<svg ${ATTRS} fill="none"><circle cx="67" cy="18" r="10" fill="${p.fill}" stroke="${p.border}" stroke-width="2"/><rect x="34" y="32" width="67" height="32" rx="14" fill="${p.fill}" stroke="${p.border}" stroke-width="2"/>${words(p.text, 42)}</svg>`;
+};
+/** A dashed frame, and — one level in — a second frame inside it. */
+const boundaryPreview = (inner = '') => `<svg ${ATTRS} fill="none"><rect x="14" y="12" width="107" height="56" stroke="${BOUNDARY_STROKE}" stroke-width="2" stroke-dasharray="7 4.5"/>${inner}</svg>`;
+const CONTAINER = NODE_PALETTE.container;
+export const c4TemplateCategory = {
+    name: '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="#262626" 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="#444444" stroke-width="1.6" stroke-dasharray="4 3"/></svg>`),
+        templateFromCommand(byId('c4.addPerson'), personPreview('person')),
+        templateFromCommand(byId('c4.addPersonExt'), personPreview('person-ext')),
+        templateFromCommand(byId('c4.addSystem'), boxPreview('system')),
+        templateFromCommand(byId('c4.addSystemExt'), boxPreview('system-ext')),
+        templateFromCommand(byId('c4.addContainer'), boxPreview('container')),
+        // The UML component: the same box, with two tabs down its leading edge.
+        templateFromCommand(byId('c4.addComponent'), boxPreview('component', `<g fill="${NODE_PALETTE.component.fill}" stroke="${NODE_PALETTE.component.border}" stroke-width="2"><rect x="22" y="28" width="16" height="8"/><rect x="22" y="44" width="16" height="8"/></g>`)),
+        // A cylinder, and the stencil's own container blue: a database is a
+        // container drawn as a data store, never a fourth level.
+        templateFromCommand(byId('c4.addDatabase'), `<svg ${ATTRS} fill="none"><path d="M36 22 V58 C36 62 50 65 67 65 C84 65 99 62 99 58 V22 Z" fill="${CONTAINER.fill}" stroke="${CONTAINER.border}" stroke-width="2"/><ellipse cx="67.5" cy="22" rx="31.5" ry="7" fill="${CONTAINER.fill}" stroke="${CONTAINER.border}" stroke-width="2"/>${words(CONTAINER.text, 38)}</svg>`),
+        // The two decorated containers paint their BEZEL in the border colour and
+        // their SCREEN in the fill, which is the stencil's own pair (`consts.ts`).
+        templateFromCommand(byId('c4.addMobile'), `<svg ${ATTRS} fill="none"><rect x="49" y="6" width="37" height="68" rx="7" fill="${CONTAINER.border}"/><rect x="54" y="15" width="27" height="50" fill="${CONTAINER.fill}"/><rect x="61" y="10" width="13" height="2.5" rx="1.25" fill="${CONTAINER.fill}"/></svg>`),
+        templateFromCommand(byId('c4.addBrowser'), `<svg ${ATTRS} fill="none"><rect x="20" y="14" width="95" height="52" rx="4" fill="${CONTAINER.border}"/><rect x="24" y="28" width="87" height="34" fill="${CONTAINER.fill}"/><g fill="${CONTAINER.fill}"><circle cx="29" cy="21" r="2.4"/><circle cx="37" cy="21" r="2.4"/><circle cx="45" cy="21" r="2.4"/></g></svg>`),
+        templateFromCommand(byId('c4.addSystemBoundary'), boundaryPreview()),
+        templateFromCommand(byId('c4.addContainerBoundary'), boundaryPreview(`<rect x="34" y="26" width="67" height="30" stroke="${BOUNDARY_STROKE}" stroke-width="1.6" stroke-dasharray="5 3.5"/>`)),
+    ],
+};

package/dist/translations.js

@@ -3,6 +3,7 @@ import { C4_BOARD_BACKGROUND, C4_BOUNDARY_BACKGROUND } from './background.js';
 import { c4Commands } from './commands.js';
 import { C4_BOARD_LEVEL_MENU } from './levels.js';
 import { C4_PROFILES } from './profiles.js';
+import { C4_READINGS } from './reading.js';
 import { C4_ROLES } from './roles.js';
 import { C4_RULES } from './rules.js';
 /**
@@ -45,4 +46,8 @@ commandCategoryTranslationEntries(c4Commands), collectTranslationKeys('role', C4
 // declaration, so walking the rules reaches keys those two lists already
 // named. `mergeTranslationEntries` keeps the FIRST occurrence, which is what
 // makes each key report the source it actually comes from.
-collectTranslationKeys('rule', C4_RULES), collectTranslationKeys('profile', C4_PROFILES));
+collectTranslationKeys('rule', C4_RULES), collectTranslationKeys('profile', C4_PROFILES), 
+// LAST, for the reason the rules are placed after the roles: a reading
+// profile carries the framework's own `roles` too, so walking it reaches
+// keys the lists above already named, and the first occurrence wins.
+collectTranslationKeys('reading', C4_READINGS));

package/dist/view.d.ts

@@ -16,8 +16,9 @@ export declare class C4RenderViewExtension extends ViewExtensionProvider {
 }
 /**
  * C4 creation tooling — flag-gated (`c4`): the senior toolbar button, its
- * sub-menu, the thirteen commands behind them, the board's legend button, the
- * component's "Change type" dropdown, and the validation rules and profiles.
+ * sub-menu, the thirteen commands behind them, its templates category, the
+ * board's legend button, the component's "Change type" dropdown, and the
+ * validation rules and profiles.
  *
  * All of it is tooling in the sense `docs/adr/0009` means: a diagram drawn while
  * the flag was on keeps painting, stays selectable and keeps its contextual

package/dist/view.js

@@ -1,5 +1,6 @@
-import { FrameworkBackgroundInteractionExtension, InterchangeExtension, morphToolbarConfig, ValidationProfileExtension, ValidationRuleExtension, } from '@formicoidea/labre-core/blocks/surface';
+import { FrameworkBackgroundInteractionExtension, InterchangeExtension, morphToolbarConfig, ReadingProfileExtension, ValidationProfileExtension, ValidationRuleExtension, } from '@formicoidea/labre-core/blocks/surface';
 import { ViewExtensionProvider, } from '@formicoidea/labre-core/ext-loader';
+import { extendTemplateCategory } from '@formicoidea/labre-core/gfx/template';
 import { ToolbarModuleExtension, toolbarModuleKey, } from '@formicoidea/labre-core/shared/services';
 import { BlockFlavourIdentifier, CommandExtension } from '@formicoidea/labre-core/std';
 import { RoleVocabularyExtension } from '@formicoidea/labre-core/std/gfx';
@@ -14,8 +15,10 @@ import { C4NodeRendererExtension } from './node/node-renderer.js';
 import { C4NodeView } from './node/node-view.js';
 import { C4TypeLineWatcher } from './node/type-line-watcher.js';
 import { C4_PROFILES } from './profiles.js';
+import { C4_READINGS } from './reading.js';
 import { C4_ROLES } from './roles.js';
 import { C4_RULES } from './rules.js';
+import { c4TemplateCategory } from './templates.js';
 import { c4BoardToolbarExtension, c4BoardToolingToolbarExtension, } from './toolbar/config.js';
 import { c4SeniorTool } from './toolbar/senior-tool.js';
 /**
@@ -70,8 +73,9 @@ export class C4RenderViewExtension extends ViewExtensionProvider {
 }
 /**
  * C4 creation tooling — flag-gated (`c4`): the senior toolbar button, its
- * sub-menu, the thirteen commands behind them, the board's legend button, the
- * component's "Change type" dropdown, and the validation rules and profiles.
+ * sub-menu, the thirteen commands behind them, its templates category, the
+ * board's legend button, the component's "Change type" dropdown, and the
+ * validation rules and profiles.
  *
  * All of it is tooling in the sense `docs/adr/0009` means: a diagram drawn while
  * the flag was on keeps painting, stays selectable and keeps its contextual
@@ -89,6 +93,7 @@ export class C4ViewExtension extends ViewExtensionProvider {
         super.effect();
         // Defines the senior button and its menu — tooling-only custom elements.
         effects();
+        extendTemplateCategory(c4TemplateCategory);
     }
     setup(context) {
         super.setup(context);
@@ -99,6 +104,14 @@ export class C4ViewExtension extends ViewExtensionProvider {
             // Tooling like the rest of this class: with the flag off there is nothing
             // to export WITH, while a stored diagram keeps painting (`docs/adr/0009`).
             context.register(InterchangeExtension(C4_INTERCHANGE));
+            // The reversed reading (MF3): what the diagram says about an element, on
+            // demand. Four profiles because the four levels are deliberately FLAT —
+            // composition is not specialisation, and `reading.ts` says why a common
+            // parent would be a lie. The CLICK that triggers it is registered once by
+            // the surface and gated by the presence of a profile.
+            for (const reading of C4_READINGS) {
+                context.register(ReadingProfileExtension(reading));
+            }
             context.register(c4SeniorTool);
             context.register(CommandExtension(c4Commands, c4CommandIcons));
             // The flag-gated half of the selected BOARD's row, through the `custom:`

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@formicoidea/labre-framework-c4",
   "description": "Labre c4 framework for @formicoidea/labre-core.",
-  "version": "0.36.0",
+  "version": "0.38.1",
   "type": "module",
   "sideEffects": false,
   "author": "lajola",
@@ -31,8 +31,8 @@
     "dist"
   ],
   "dependencies": {
-    "@formicoidea/labre-core": "0.36.0",
-    "@formicoidea/labre-ddd-shared": "0.36.0",
+    "@formicoidea/labre-core": "0.38.1",
+    "@formicoidea/labre-ddd-shared": "0.38.1",
     "lit": "^3.2.0"
   }
 }