@formicoidea/labre-core 0.32.0 → 0.33.0

package/dist/_pkgs/affine-model/elements/bpmn/node.d.ts

@@ -1,17 +1,50 @@
 import { ShapeElementModel } from '../shape/index.js';
 /**
- * The BPMN flow-object nodes shipped in v1. Each maps onto a native shape:
- *  - `startEvent` / `endEvent` → an ellipse (thin green / thick red ring)
- *  - `task`                    → a rounded rectangle with editable inner text
- *  - `gatewayExclusive`        → a diamond decorated with an X glyph
+ * The BPMN artefacts the pack draws — the **descriptive conformance subclass**
+ * of BPMN 2.0. Each maps onto a native shape, decorated by a glyph where the
+ * notation asks for one:
+ *
+ *  - events (ellipse)   — `startEvent` / `endEvent` plain, plus the message and
+ *    timer starts and the message and terminate ends;
+ *  - activities (rect)  — `task` plain, plus the user and service tasks, the
+ *    collapsed sub-process and the call activity;
+ *  - gateways (diamond) — `gatewayExclusive` (X) and `gatewayParallel` (+);
+ *  - data & artifacts   — `dataObject`, `dataStore` and `textAnnotation`, whose
+ *    silhouettes (folded page, cylinder, open bracket) are drawn by the glyph
+ *    over a native rect with its own stroke and fill turned off;
+ *  - `group`            — a dashed rounded rectangle drawn AROUND things.
+ *
+ * `group` is the odd one and deliberately so. Every other kind is a node the
+ * process is made of; a group is a lasso somebody drew round part of it. The
+ * spec (BPMN 2.0.2 §10.4) exempts it from every connection and containment
+ * constraint there is — it cannot be attached to a sequence or message flow, it
+ * is not bounded by the pool or lane it overlaps, and it may straddle several
+ * pools at once. Nothing here has to enforce that, because a group is unfilled:
+ * it is hit near its border and on its label, so it never steals a click from
+ * what it encloses, and what it encloses never becomes its content.
+ *
+ * ## Compatibility
+ *
+ * This union is only ever WIDENED, and it is widened with new VALUES of the
+ * existing `kind` string field — no new field, no schema change, no migration
+ * and no backfill. The precedent is `wardley`'s (`gfx/wardley/src/roles.ts`):
+ * a process drawn before today carries one of the four original values, loads
+ * unchanged and paints exactly as it always did.
+ *
+ * The expanded (drilled-in) sub-process is deliberately NOT here: `subProcess`
+ * is the COLLAPSED representation only — a task-sized rectangle with the `+`
+ * marker. An expanded sub-process is a container with its own flow inside it,
+ * which is a containment model this pack does not have yet.
  */
-export type BpmnNodeKind = 'startEvent' | 'endEvent' | 'task' | 'gatewayExclusive';
+export type BpmnNodeKind = 'startEvent' | 'startEventMessage' | 'startEventTimer' | 'endEvent' | 'endEventMessage' | 'endEventTerminate' | 'task' | 'taskUser' | 'taskService' | 'subProcess' | 'callActivity' | 'gatewayExclusive' | 'gatewayParallel' | 'dataObject' | 'dataStore' | 'textAnnotation' | 'group';
 /**
  * A BPMN flow-object node. Extends {@link ShapeElementModel} (a native shape)
  * so it inherits ALL shape behaviour — editable stroke width / colors, inner
  * text, native resize, the shape context toolbar — for free. `kind`
- * discriminates the four basics; only `gatewayExclusive` is decorated with a
- * glyph (the X) by the renderer (the others are plain native shapes).
+ * discriminates the artefacts and drives the RENDERING alone; what a node
+ * MEANS is the `role` stamped on it at creation (`gfx/bpmn/src/roles.ts`).
+ * The plain start event, end event and task are undecorated native shapes;
+ * every other kind is decorated with a glyph by the renderer.
  *
  * Mirrors {@link EdgyNodeElementModel}.
  */

package/dist/_pkgs/affine-model/elements/bpmn/node.js

@@ -38,8 +38,10 @@ import { ShapeElementModel } from '../shape/index.js';
  * A BPMN flow-object node. Extends {@link ShapeElementModel} (a native shape)
  * so it inherits ALL shape behaviour — editable stroke width / colors, inner
  * text, native resize, the shape context toolbar — for free. `kind`
- * discriminates the four basics; only `gatewayExclusive` is decorated with a
- * glyph (the X) by the renderer (the others are plain native shapes).
+ * discriminates the artefacts and drives the RENDERING alone; what a node
+ * MEANS is the `role` stamped on it at creation (`gfx/bpmn/src/roles.ts`).
+ * The plain start event, end event and task are undecorated native shapes;
+ * every other kind is decorated with a glyph by the renderer.
  *
  * Mirrors {@link EdgyNodeElementModel}.
  */

package/dist/_pkgs/affine-model/elements/bpmn/pool.d.ts

@@ -1,30 +1,87 @@
-import type { IVec, SerializedXYWH } from '../../../global/gfx/index.js';
-import { Bound } from '../../../global/gfx/index.js';
-import type { BaseElementProps } from '../../../std/gfx/index.js';
-import { GfxPrimitiveElementModel } from '../../../std/gfx/index.js';
-export type BpmnPoolProps = BaseElementProps & {
+import type { SerializedXYWH } from '../../../global/gfx/index.js';
+import type { FrameworkBackgroundProps } from '../framework-background/index.js';
+import { FrameworkBackgroundElementModel } from '../framework-background/index.js';
+/**
+ * One LANE (couloir) of a pool: a horizontal band the participant's own work is
+ * divided into — "Sales", "Back office", "Automated".
+ *
+ * The shape of a {@link BackgroundInstanceZoneItem} in
+ * `@labre/affine-block-surface`, and deliberately the same three fields: the
+ * primitive paints an instance partition from that structure, the audit reports
+ * it from that structure, and a lane that had a shape of its own would be a
+ * fourth place the two have to agree.
+ *
+ * `size` is a relative WEIGHT, not a height in model units: lanes share the
+ * plot in proportion to their sizes, so a pool dragged taller redistributes the
+ * extra space instead of leaving a gap under the last band. `2` reads as "twice
+ * the other one", which is the only thing a lane's height ever means.
+ */
+export interface BpmnLane {
+    /** Stable id, generated at creation. Never the name: a lane can be renamed. */
+    id: string;
+    /** The lane name, written horizontally in its top-left corner. */
+    name?: string;
+    /** Relative weight — see above. Must be a finite number greater than zero. */
+    size: number;
+}
+export type BpmnPoolProps = FrameworkBackgroundProps & {
     /** The participant name shown in the left band — edited inline on dblclick. */
     name?: string;
-    /** When false the resize handles are hidden — toggled from the toolbar. */
-    resizeEnabled?: boolean;
+    /** The pool's own partition into lanes. Absent until the first one is added. */
+    lanes?: BpmnLane[];
 };
 /**
  * A BPMN "pool": a participant container drawn as a rounded-rect frame with a
- * vertical name band on the left. It is a background element (like the wardley
- * / cynefin backgrounds): the user drops flow-object nodes on top of it. Lanes
- * are deliberately out of scope for v1.
+ * vertical name band on the left. It is a framework background like every other
+ * one in the library — the user drops flow-object nodes on top of it, and a
+ * connector never snaps to it.
+ *
+ * The geometry of a passive canvas comes from
+ * {@link FrameworkBackgroundElementModel}: this class used to restate all five
+ * of those overrides verbatim, which is exactly the kind of copy that drifts.
+ * The persisted type is still `bpmnPool`, and the first four fields below are
+ * the four it has always written, in the same order, with the same defaults.
  *
- * Mirrors the other framework background elements.
+ * What it LOOKS like is declared, not coded: see `BPMN_POOL_BACKGROUND` in
+ * `@labre/affine-gfx-bpmn`.
  */
-export declare class BpmnPoolElementModel extends GfxPrimitiveElementModel<BpmnPoolProps> {
+export declare class BpmnPoolElementModel extends FrameworkBackgroundElementModel<BpmnPoolProps> {
     get type(): string;
-    get connectable(): boolean;
-    containsBound(bounds: Bound): boolean;
-    getLineIntersections(start: IVec, end: IVec): import("../../../global/gfx/index.js").PointLocation[] | null;
-    getNearestPoint(point: IVec): IVec;
-    includesPoint(x: number, y: number): boolean;
     accessor name: string;
     accessor resizeEnabled: boolean;
     accessor rotate: number;
     accessor xywh: SerializedXYWH;
+    /**
+     * The pool's own partition into lanes, in top-to-bottom order.
+     *
+     * The FIFTH field, and the only one that is optional. It mirrors
+     * `validationExceptions` on the base element model exactly, for the same three
+     * reasons:
+     *
+     * - **`undefined`, not `[]`.** `@field()`'s `init` writes nothing for an
+     *   `undefined` default, so a pool that has no lane stays byte-identical to
+     *   one created before this field existed: optional field, no schema version
+     *   bump, no migration, and every document already on disk opens and paints
+     *   exactly as it did (pinned by `pool-background.unit.spec.ts`, whose
+     *   fixture carries no `lanes` key). Removing the last lane goes back through
+     *   `clearField`, which deletes the KEY rather than leaving a phantom one.
+     * - **Flat JSON on purpose.** Element serialization is one level deep, and a
+     *   value a Yjs update can encode is the contract `_assignElementProp`
+     *   enforces. A nested `Y.Map` is what `tags` needs and this does not (see
+     *   `docs/adr/0007`): a lane list is one atomic choice about how a single
+     *   participant's own band is cut, authored by whoever is drawing the
+     *   process — not an accumulating multi-key set different people qualify
+     *   concurrently. The trade is stated so it is reviewed, not discovered:
+     *   two peers reordering the lanes at the same moment resolve
+     *   last-write-wins, one whole list winning over the other.
+     * - **Declared HERE and not on the base class.** A lane is a subdivision of a
+     *   pool and of nothing else, and the accessor is what carries the value
+     *   through a copy, a paste or a template insertion, so a duplicated pool
+     *   arrives with its lanes.
+     *
+     * What it MEANS is declared, not coded: `BPMN_POOL_BACKGROUND.instanceZones`
+     * in `@labre/affine-gfx-bpmn` names this prop, and the framework-background
+     * primitive paints the dividers and the names from it.
+     */
+    accessor lanes: BpmnLane[] | undefined;
 }

package/dist/_pkgs/affine-model/elements/bpmn/pool.js

@@ -32,18 +32,25 @@ var __runInitializers = (this && this.__runInitializers) || function (thisArg, i
     }
     return useValue ? value : void 0;
 };
-import { Bound, getPointsFromBoundWithRotation, linePolygonIntersects, pointInPolygon, polygonNearestPoint, } from '../../../global/gfx/index.js';
-import { field, GfxPrimitiveElementModel } from '../../../std/gfx/index.js';
+import { field } from '../../../std/gfx/index.js';
+import { FrameworkBackgroundElementModel } from '../framework-background/index.js';
 /**
  * A BPMN "pool": a participant container drawn as a rounded-rect frame with a
- * vertical name band on the left. It is a background element (like the wardley
- * / cynefin backgrounds): the user drops flow-object nodes on top of it. Lanes
- * are deliberately out of scope for v1.
+ * vertical name band on the left. It is a framework background like every other
+ * one in the library — the user drops flow-object nodes on top of it, and a
+ * connector never snaps to it.
  *
- * Mirrors the other framework background elements.
+ * The geometry of a passive canvas comes from
+ * {@link FrameworkBackgroundElementModel}: this class used to restate all five
+ * of those overrides verbatim, which is exactly the kind of copy that drifts.
+ * The persisted type is still `bpmnPool`, and the first four fields below are
+ * the four it has always written, in the same order, with the same defaults.
+ *
+ * What it LOOKS like is declared, not coded: see `BPMN_POOL_BACKGROUND` in
+ * `@labre/affine-gfx-bpmn`.
  */
 let BpmnPoolElementModel = (() => {
-    let _classSuper = GfxPrimitiveElementModel;
+    let _classSuper = FrameworkBackgroundElementModel;
     let _name_decorators;
     let _name_initializers = [];
     let _name_extraInitializers = [];
@@ -56,6 +63,9 @@ let BpmnPoolElementModel = (() => {
     let _xywh_decorators;
     let _xywh_initializers = [];
     let _xywh_extraInitializers = [];
+    let _lanes_decorators;
+    let _lanes_initializers = [];
+    let _lanes_extraInitializers = [];
     return class BpmnPoolElementModel extends _classSuper {
         static {
             const _metadata = typeof Symbol === "function" && Symbol.metadata ? Object.create(_classSuper[Symbol.metadata] ?? null) : void 0;
@@ -63,33 +73,17 @@ let BpmnPoolElementModel = (() => {
             _resizeEnabled_decorators = [field(true)];
             _rotate_decorators = [field(0)];
             _xywh_decorators = [field()];
+            _lanes_decorators = [field()];
             __esDecorate(this, null, _name_decorators, { kind: "accessor", name: "name", static: false, private: false, access: { has: obj => "name" in obj, get: obj => obj.name, set: (obj, value) => { obj.name = value; } }, metadata: _metadata }, _name_initializers, _name_extraInitializers);
             __esDecorate(this, null, _resizeEnabled_decorators, { kind: "accessor", name: "resizeEnabled", static: false, private: false, access: { has: obj => "resizeEnabled" in obj, get: obj => obj.resizeEnabled, set: (obj, value) => { obj.resizeEnabled = value; } }, metadata: _metadata }, _resizeEnabled_initializers, _resizeEnabled_extraInitializers);
             __esDecorate(this, null, _rotate_decorators, { kind: "accessor", name: "rotate", static: false, private: false, access: { has: obj => "rotate" in obj, get: obj => obj.rotate, set: (obj, value) => { obj.rotate = value; } }, metadata: _metadata }, _rotate_initializers, _rotate_extraInitializers);
             __esDecorate(this, null, _xywh_decorators, { kind: "accessor", name: "xywh", static: false, private: false, access: { has: obj => "xywh" in obj, get: obj => obj.xywh, set: (obj, value) => { obj.xywh = value; } }, metadata: _metadata }, _xywh_initializers, _xywh_extraInitializers);
+            __esDecorate(this, null, _lanes_decorators, { kind: "accessor", name: "lanes", static: false, private: false, access: { has: obj => "lanes" in obj, get: obj => obj.lanes, set: (obj, value) => { obj.lanes = value; } }, metadata: _metadata }, _lanes_initializers, _lanes_extraInitializers);
             if (_metadata) Object.defineProperty(this, Symbol.metadata, { enumerable: true, configurable: true, writable: true, value: _metadata });
         }
         get type() {
             return 'bpmnPool';
         }
-        get connectable() {
-            return false;
-        }
-        containsBound(bounds) {
-            const points = getPointsFromBoundWithRotation(this);
-            return points.some(point => bounds.containsPoint(point));
-        }
-        getLineIntersections(start, end) {
-            const points = getPointsFromBoundWithRotation(this);
-            return linePolygonIntersects(start, end, points);
-        }
-        getNearestPoint(point) {
-            return polygonNearestPoint(Bound.deserialize(this.xywh).points, point);
-        }
-        includesPoint(x, y) {
-            const points = getPointsFromBoundWithRotation(this);
-            return pointInPolygon([x, y], points);
-        }
         #name_accessor_storage = __runInitializers(this, _name_initializers, 'Pool');
         get name() { return this.#name_accessor_storage; }
         set name(value) { this.#name_accessor_storage = value; }
@@ -102,9 +96,44 @@ let BpmnPoolElementModel = (() => {
         #xywh_accessor_storage = (__runInitializers(this, _rotate_extraInitializers), __runInitializers(this, _xywh_initializers, '[0,0,560,200]'));
         get xywh() { return this.#xywh_accessor_storage; }
         set xywh(value) { this.#xywh_accessor_storage = value; }
+        #lanes_accessor_storage = (__runInitializers(this, _xywh_extraInitializers), __runInitializers(this, _lanes_initializers, undefined));
+        /**
+         * The pool's own partition into lanes, in top-to-bottom order.
+         *
+         * The FIFTH field, and the only one that is optional. It mirrors
+         * `validationExceptions` on the base element model exactly, for the same three
+         * reasons:
+         *
+         * - **`undefined`, not `[]`.** `@field()`'s `init` writes nothing for an
+         *   `undefined` default, so a pool that has no lane stays byte-identical to
+         *   one created before this field existed: optional field, no schema version
+         *   bump, no migration, and every document already on disk opens and paints
+         *   exactly as it did (pinned by `pool-background.unit.spec.ts`, whose
+         *   fixture carries no `lanes` key). Removing the last lane goes back through
+         *   `clearField`, which deletes the KEY rather than leaving a phantom one.
+         * - **Flat JSON on purpose.** Element serialization is one level deep, and a
+         *   value a Yjs update can encode is the contract `_assignElementProp`
+         *   enforces. A nested `Y.Map` is what `tags` needs and this does not (see
+         *   `docs/adr/0007`): a lane list is one atomic choice about how a single
+         *   participant's own band is cut, authored by whoever is drawing the
+         *   process — not an accumulating multi-key set different people qualify
+         *   concurrently. The trade is stated so it is reviewed, not discovered:
+         *   two peers reordering the lanes at the same moment resolve
+         *   last-write-wins, one whole list winning over the other.
+         * - **Declared HERE and not on the base class.** A lane is a subdivision of a
+         *   pool and of nothing else, and the accessor is what carries the value
+         *   through a copy, a paste or a template insertion, so a duplicated pool
+         *   arrives with its lanes.
+         *
+         * What it MEANS is declared, not coded: `BPMN_POOL_BACKGROUND.instanceZones`
+         * in `@labre/affine-gfx-bpmn` names this prop, and the framework-background
+         * primitive paints the dividers and the names from it.
+         */
+        get lanes() { return this.#lanes_accessor_storage; }
+        set lanes(value) { this.#lanes_accessor_storage = value; }
         constructor() {
             super(...arguments);
-            __runInitializers(this, _xywh_extraInitializers);
+            __runInitializers(this, _lanes_extraInitializers);
         }
     };
 })();

package/dist/_pkgs/affine-model/elements/c4/board.d.ts

@@ -0,0 +1,88 @@
+import type { SerializedXYWH } from '../../../global/gfx/index.js';
+import type { FrameworkBackgroundProps } from '../framework-background/index.js';
+import { FrameworkBackgroundElementModel } from '../framework-background/index.js';
+/**
+ * Which of C4's levels this board draws — the DECLARED fact, as opposed to the
+ * title, which is free text and says whatever its author wants it to.
+ *
+ * **Four values, for the four C's the notation is named after**: Context,
+ * Containers, Components, Code. The vocabulary is the model's, so it says all
+ * of it.
+ *
+ * ## Why `code` is here although nothing draws it
+ *
+ * Because the two questions are not the same one. What the EDITOR can draw is a
+ * fact about this tooling — there are no code-level artefacts in the pack today,
+ * and C4 itself says to skip that diagram unless it is generated from the source
+ * — while what a SHEET may declare is a fact about the author's intent. A board
+ * an architect keeps for the class diagram they paste in from elsewhere is a
+ * code-level board, and a vocabulary that refused to let them say so would be
+ * this editor's limitation dressed up as the notation's.
+ *
+ * So the declaration is the author's to make, and no rule judges it: nothing in
+ * the pack knows what a code diagram admits, and a rule with nothing to forbid
+ * is data that can never fire (`rules.ts` says this at length, about `component`
+ * and `code` together). The level is recorded, exported and readable; it is
+ * simply not yet checked.
+ *
+ * ## Widening this union is additive
+ *
+ * A value added here is a value older clients have never seen, and they read it
+ * back as the string it is — the same promise `C4NodeKind` and
+ * `C4BoundaryVariant` make. No document is rewritten, no migration is owed, and
+ * a rule that does not name a level evaluates nothing on a board carrying it.
+ *
+ * A board that states a level is a board a rule can judge — "a container has no
+ * place on a context diagram" — where a board that states nothing is a free
+ * sketch, which is what every C4 diagram ever drawn in this editor is.
+ */
+export type C4BoardLevel = 'context' | 'container' | 'component' | 'code';
+export type C4BoardProps = FrameworkBackgroundProps & {
+    /** The diagram title, written top-left — edited inline on dblclick. */
+    name?: string;
+    /** Which C4 level this sheet draws. Absent means a free sketch. */
+    level?: C4BoardLevel;
+};
+/**
+ * The C4 board: the sheet one diagram of the model is drawn on — a context
+ * diagram, a container diagram, a component diagram. A framework background like
+ * every other one in the library: the user drops nodes on top of it, and a
+ * connector never snaps to it.
+ *
+ * It carries a NAME, and optionally the LEVEL it draws. A C4 diagram has no
+ * frame of reference — a system drawn top left says nothing more than one drawn
+ * bottom right — so there are no axes, no zones and no partition to declare.
+ *
+ * What it LOOKS like is declared, not coded: see `C4_BOARD_BACKGROUND` in
+ * `@labre/affine-gfx-c4`.
+ */
+export declare class C4BoardElementModel extends FrameworkBackgroundElementModel<C4BoardProps> {
+    get type(): string;
+    accessor name: string;
+    accessor resizeEnabled: boolean;
+    accessor rotate: number;
+    accessor xywh: SerializedXYWH;
+    /**
+     * Which C4 level this sheet draws — the only OPTIONAL field of this element,
+     * and optional on purpose.
+     *
+     * `@field()`'s `init` writes nothing for an `undefined` default, so a board
+     * that never states its level stays byte-identical to one created before this
+     * value existed: no schema version bump, no migration, and every document
+     * already on disk opens and paints exactly as it did. The same call
+     * `C4BoundaryElementModel.variant` makes, for the same reason.
+     *
+     * ## Why there is no default to read, unlike the boundary's `variant`
+     *
+     * A boundary that says nothing still IS one of the two levels, and reading it
+     * as `'system'` is the only answer a reader could give. A board that says
+     * nothing is a different thing altogether: a free sketch, whose author has not
+     * told the tool which of the three sheets they are drawing. Guessing would
+     * hand every diagram already in existence a level nobody chose, and a rule
+     * reading it would start indicting drawings on the strength of that guess.
+     *
+     * So absent stays absent, and the rules that read it evaluate nothing at all
+     * on a board that declares none — no fact, no rule (PRD principle 8).
+     */
+    accessor level: C4BoardLevel | undefined;
+}

package/dist/_pkgs/affine-model/elements/c4/board.js

@@ -0,0 +1,128 @@
+var __esDecorate = (this && this.__esDecorate) || function (ctor, descriptorIn, decorators, contextIn, initializers, extraInitializers) {
+    function accept(f) { if (f !== void 0 && typeof f !== "function") throw new TypeError("Function expected"); return f; }
+    var kind = contextIn.kind, key = kind === "getter" ? "get" : kind === "setter" ? "set" : "value";
+    var target = !descriptorIn && ctor ? contextIn["static"] ? ctor : ctor.prototype : null;
+    var descriptor = descriptorIn || (target ? Object.getOwnPropertyDescriptor(target, contextIn.name) : {});
+    var _, done = false;
+    for (var i = decorators.length - 1; i >= 0; i--) {
+        var context = {};
+        for (var p in contextIn) context[p] = p === "access" ? {} : contextIn[p];
+        for (var p in contextIn.access) context.access[p] = contextIn.access[p];
+        context.addInitializer = function (f) { if (done) throw new TypeError("Cannot add initializers after decoration has completed"); extraInitializers.push(accept(f || null)); };
+        var result = (0, decorators[i])(kind === "accessor" ? { get: descriptor.get, set: descriptor.set } : descriptor[key], context);
+        if (kind === "accessor") {
+            if (result === void 0) continue;
+            if (result === null || typeof result !== "object") throw new TypeError("Object expected");
+            if (_ = accept(result.get)) descriptor.get = _;
+            if (_ = accept(result.set)) descriptor.set = _;
+            if (_ = accept(result.init)) initializers.unshift(_);
+        }
+        else if (_ = accept(result)) {
+            if (kind === "field") initializers.unshift(_);
+            else descriptor[key] = _;
+        }
+    }
+    if (target) Object.defineProperty(target, contextIn.name, descriptor);
+    done = true;
+};
+var __runInitializers = (this && this.__runInitializers) || function (thisArg, initializers, value) {
+    var useValue = arguments.length > 2;
+    for (var i = 0; i < initializers.length; i++) {
+        value = useValue ? initializers[i].call(thisArg, value) : initializers[i].call(thisArg);
+    }
+    return useValue ? value : void 0;
+};
+import { field } from '../../../std/gfx/index.js';
+import { FrameworkBackgroundElementModel } from '../framework-background/index.js';
+/**
+ * The C4 board: the sheet one diagram of the model is drawn on — a context
+ * diagram, a container diagram, a component diagram. A framework background like
+ * every other one in the library: the user drops nodes on top of it, and a
+ * connector never snaps to it.
+ *
+ * It carries a NAME, and optionally the LEVEL it draws. A C4 diagram has no
+ * frame of reference — a system drawn top left says nothing more than one drawn
+ * bottom right — so there are no axes, no zones and no partition to declare.
+ *
+ * What it LOOKS like is declared, not coded: see `C4_BOARD_BACKGROUND` in
+ * `@labre/affine-gfx-c4`.
+ */
+let C4BoardElementModel = (() => {
+    let _classSuper = FrameworkBackgroundElementModel;
+    let _name_decorators;
+    let _name_initializers = [];
+    let _name_extraInitializers = [];
+    let _resizeEnabled_decorators;
+    let _resizeEnabled_initializers = [];
+    let _resizeEnabled_extraInitializers = [];
+    let _rotate_decorators;
+    let _rotate_initializers = [];
+    let _rotate_extraInitializers = [];
+    let _xywh_decorators;
+    let _xywh_initializers = [];
+    let _xywh_extraInitializers = [];
+    let _level_decorators;
+    let _level_initializers = [];
+    let _level_extraInitializers = [];
+    return class C4BoardElementModel extends _classSuper {
+        static {
+            const _metadata = typeof Symbol === "function" && Symbol.metadata ? Object.create(_classSuper[Symbol.metadata] ?? null) : void 0;
+            _name_decorators = [field('C4 diagram')];
+            _resizeEnabled_decorators = [field(true)];
+            _rotate_decorators = [field(0)];
+            _xywh_decorators = [field()];
+            _level_decorators = [field()];
+            __esDecorate(this, null, _name_decorators, { kind: "accessor", name: "name", static: false, private: false, access: { has: obj => "name" in obj, get: obj => obj.name, set: (obj, value) => { obj.name = value; } }, metadata: _metadata }, _name_initializers, _name_extraInitializers);
+            __esDecorate(this, null, _resizeEnabled_decorators, { kind: "accessor", name: "resizeEnabled", static: false, private: false, access: { has: obj => "resizeEnabled" in obj, get: obj => obj.resizeEnabled, set: (obj, value) => { obj.resizeEnabled = value; } }, metadata: _metadata }, _resizeEnabled_initializers, _resizeEnabled_extraInitializers);
+            __esDecorate(this, null, _rotate_decorators, { kind: "accessor", name: "rotate", static: false, private: false, access: { has: obj => "rotate" in obj, get: obj => obj.rotate, set: (obj, value) => { obj.rotate = value; } }, metadata: _metadata }, _rotate_initializers, _rotate_extraInitializers);
+            __esDecorate(this, null, _xywh_decorators, { kind: "accessor", name: "xywh", static: false, private: false, access: { has: obj => "xywh" in obj, get: obj => obj.xywh, set: (obj, value) => { obj.xywh = value; } }, metadata: _metadata }, _xywh_initializers, _xywh_extraInitializers);
+            __esDecorate(this, null, _level_decorators, { kind: "accessor", name: "level", static: false, private: false, access: { has: obj => "level" in obj, get: obj => obj.level, set: (obj, value) => { obj.level = value; } }, metadata: _metadata }, _level_initializers, _level_extraInitializers);
+            if (_metadata) Object.defineProperty(this, Symbol.metadata, { enumerable: true, configurable: true, writable: true, value: _metadata });
+        }
+        get type() {
+            return 'c4Board';
+        }
+        #name_accessor_storage = __runInitializers(this, _name_initializers, 'C4 diagram');
+        get name() { return this.#name_accessor_storage; }
+        set name(value) { this.#name_accessor_storage = value; }
+        #resizeEnabled_accessor_storage = (__runInitializers(this, _name_extraInitializers), __runInitializers(this, _resizeEnabled_initializers, true));
+        get resizeEnabled() { return this.#resizeEnabled_accessor_storage; }
+        set resizeEnabled(value) { this.#resizeEnabled_accessor_storage = value; }
+        #rotate_accessor_storage = (__runInitializers(this, _resizeEnabled_extraInitializers), __runInitializers(this, _rotate_initializers, 0));
+        get rotate() { return this.#rotate_accessor_storage; }
+        set rotate(value) { this.#rotate_accessor_storage = value; }
+        #xywh_accessor_storage = (__runInitializers(this, _rotate_extraInitializers), __runInitializers(this, _xywh_initializers, '[0,0,1400,900]'));
+        get xywh() { return this.#xywh_accessor_storage; }
+        set xywh(value) { this.#xywh_accessor_storage = value; }
+        #level_accessor_storage = (__runInitializers(this, _xywh_extraInitializers), __runInitializers(this, _level_initializers, undefined));
+        /**
+         * Which C4 level this sheet draws — the only OPTIONAL field of this element,
+         * and optional on purpose.
+         *
+         * `@field()`'s `init` writes nothing for an `undefined` default, so a board
+         * that never states its level stays byte-identical to one created before this
+         * value existed: no schema version bump, no migration, and every document
+         * already on disk opens and paints exactly as it did. The same call
+         * `C4BoundaryElementModel.variant` makes, for the same reason.
+         *
+         * ## Why there is no default to read, unlike the boundary's `variant`
+         *
+         * A boundary that says nothing still IS one of the two levels, and reading it
+         * as `'system'` is the only answer a reader could give. A board that says
+         * nothing is a different thing altogether: a free sketch, whose author has not
+         * told the tool which of the three sheets they are drawing. Guessing would
+         * hand every diagram already in existence a level nobody chose, and a rule
+         * reading it would start indicting drawings on the strength of that guess.
+         *
+         * So absent stays absent, and the rules that read it evaluate nothing at all
+         * on a board that declares none — no fact, no rule (PRD principle 8).
+         */
+        get level() { return this.#level_accessor_storage; }
+        set level(value) { this.#level_accessor_storage = value; }
+        constructor() {
+            super(...arguments);
+            __runInitializers(this, _level_extraInitializers);
+        }
+    };
+})();
+export { C4BoardElementModel };

package/dist/_pkgs/affine-model/elements/c4/boundary.d.ts

@@ -0,0 +1,63 @@
+import type { SerializedXYWH } from '../../../global/gfx/index.js';
+import type { FrameworkBackgroundProps } from '../framework-background/index.js';
+import { FrameworkBackgroundElementModel } from '../framework-background/index.js';
+/**
+ * Which level a boundary encloses. C4 draws the two identically — a dashed
+ * rectangle round a group of elements — and the difference is entirely in what
+ * the label says, which is why this is one element type with a variant rather
+ * than two.
+ */
+export type C4BoundaryVariant = 'system' | 'container';
+export type C4BoundaryProps = FrameworkBackgroundProps & {
+    /** The boundary name, written bottom-left — edited inline on dblclick. */
+    name?: string;
+    /** Which level this boundary encloses. Absent behaves as `'system'`. */
+    variant?: C4BoundaryVariant;
+};
+/**
+ * A C4 boundary: the dashed rectangle drawn AROUND a group of elements to say
+ * "all of this is one system" (or one container). A framework background, so
+ * nodes are dropped on it and connectors never snap to it — but a transparent
+ * one, unlike every other background in the library: a boundary is drawn over
+ * the board it sits on, and an opaque card would hide the diagram it encloses.
+ *
+ * What it LOOKS like is declared, not coded: see `C4_BOUNDARY_BACKGROUND` in
+ * `@labre/affine-gfx-c4`.
+ */
+export declare class C4BoundaryElementModel extends FrameworkBackgroundElementModel<C4BoundaryProps> {
+    get type(): string;
+    accessor name: string;
+    accessor resizeEnabled: boolean;
+    accessor rotate: number;
+    accessor xywh: SerializedXYWH;
+    /**
+     * The level enclosed — the only OPTIONAL field of this element, and optional
+     * on purpose.
+     *
+     * `@field()`'s `init` writes nothing for an `undefined` default, so a boundary
+     * that never states its level stays byte-identical to one created before this
+     * value existed: no schema version bump, no migration, and every document
+     * already on disk opens and paints exactly as it did. The same call
+     * `BpmnPoolElementModel.lanes` makes, for the same reason.
+     *
+     * Absent reads as `'system'` everywhere — the outermost boundary, which is the
+     * one a reader draws first and the one the default wording names.
+     */
+    accessor variant: C4BoundaryVariant | undefined;
+    /**
+     * The variant every reader of this element should use — `variant` with its
+     * documented default already applied.
+     *
+     * Derived, not stored: nothing here reaches the document, and an element that
+     * never stated a level is untouched by the existence of this getter.
+     *
+     * It is what lets the declaration gate a piece of itself on the level
+     * (`variantProp`), which a raw optional field cannot do: an unstated `variant`
+     * stringifies to `"undefined"`, matches no declared variant, and would paint
+     * NOTHING — the trap the boundary declaration used to avoid by declaring no
+     * `variantProp` at all. Reading the default here removes the trap instead of
+     * routing round it, so the frame can finally write the bracket line the
+     * stencil puts under a boundary's name.
+     */
+    get variantOrDefault(): C4BoundaryVariant;
+}