@formicoidea/labre-core 0.32.0 → 0.33.0

package/dist/_pkgs/affine-block-surface/extensions/violation-detail-widget.d.ts

@@ -1,7 +1,7 @@
 import type { RootBlockModel } from '../../affine-model/index.js';
 import { WidgetComponent } from '../../std/index.js';
 import { nothing } from 'lit';
-import { type ExemptionScope, type ViolationSeverity } from './validation.js';
+import { type ExemptionScope, type ProvenanceSource, type ViolationSeverity } from './validation.js';
 export declare const VIOLATION_DETAIL_WIDGET = "affine-violation-detail-widget";
 /**
  * Chrome wording, and only chrome: an English default so a catalogue-less
@@ -17,6 +17,25 @@ export declare const VIOLATION_DETAIL_WIDGET = "affine-violation-detail-widget";
 export declare const SEVERITY_FALLBACK: Record<ViolationSeverity, string>;
 /** What the badge says of an excused violation, per scope of the exception. */
 export declare const EXEMPTION_FALLBACK: Record<ExemptionScope, string>;
+/**
+ * What the bubble calls each kind of authority a rule can claim
+ * ({@link RuleProvenance}).
+ *
+ * The one wording in this file that changes what a finding MEANS rather than
+ * how it looks: "Standard" tells an architect the diagram breaks a published
+ * specification, "Labre convention" tells them it does not. An external review
+ * of the BPMN pack asked for exactly this line, because a house style shown
+ * without it reads as a norm violation — and a tool that cannot be trusted on
+ * that distinction is a tool an architect stops believing.
+ *
+ * The word only; the CITATION beside it is the rule's own `reference`, rendered
+ * verbatim and never translated (a page number is the same in every language).
+ *
+ * Exported for the same reason {@link SEVERITY_FALLBACK} is: the manifest walks
+ * this table under `com.labre.validation.provenance.` instead of restating four
+ * wordings a source scan could not check behind a template key.
+ */
+export declare const PROVENANCE_FALLBACK: Record<ProvenanceSource, string>;
 /**
  * The PERSISTENT half of the PF7 affordance, and the restitution behind it.
  *
@@ -79,11 +98,20 @@ export declare const EXEMPTION_FALLBACK: Record<ExemptionScope, string>;
  *
  * ## What it knows
  *
- * Nothing about rules. It consumes normalised {@link Violation} objects off
- * `ValidationManager.violations$` and resolves their `messageKey` through the
- * host's catalogue ({@link translateKey}), falling back to the raw key. No rule
- * logic, no hard-coded rule wording — the library must not put words in a
- * framework's mouth.
+ * No rule LOGIC, and no hard-coded rule wording — the library must not put
+ * words in a framework's mouth. It consumes normalised {@link Violation}
+ * objects off `ValidationManager.violations$` and resolves their `messageKey`
+ * through the host's catalogue ({@link translateKey}), falling back to the raw
+ * key.
+ *
+ * The one thing it reads off the RULE rather than off the finding is
+ * {@link ValidationRule.provenance} — whether the sentence above it restates a
+ * published standard, a linter's recommendation, or a Labre house style. It is
+ * looked up by `ruleId` through {@link ValidationManager.ruleOf}, the same path
+ * this widget already walks to name a finding's framework when it reports an
+ * exception, and it is still declared data rather than logic: the widget
+ * chooses the LABEL for a source it is handed, and prints the citation
+ * verbatim.
  */
 export declare class ViolationDetailWidget extends WidgetComponent<RootBlockModel> {
     static styles: import("lit").CSSResult;
@@ -220,6 +248,22 @@ export declare class ViolationDetailWidget extends WidgetComponent<RootBlockMode
      */
     private _estimateBubbleHeight;
     private _severityLabel;
+    /**
+     * The one line saying where the rule behind a finding gets its authority.
+     *
+     * Resolved through {@link ValidationManager.ruleOf}, which is the path this
+     * widget already uses to name a finding's framework when it reports an
+     * exception — the bubble consumes normalised {@link Violation}s and knows
+     * nothing about rules, so the manager is the only place a rule can come from.
+     *
+     * Rendered ONLY when the rule declares one. A rule that says nothing about
+     * its provenance gets no line and no invented one: the library must not put
+     * an authority in a framework's mouth any more than it puts words there
+     * (see {@link translateKey}). That is also why the fallback is chrome-only —
+     * the LABEL is ours, the citation is the framework's, and the citation is
+     * printed exactly as declared rather than translated.
+     */
+    private _renderProvenance;
     /**
      * Grant or revoke, then report it.
      *

package/dist/_pkgs/affine-block-surface/extensions/violation-detail-widget.js

@@ -93,6 +93,30 @@ export const EXEMPTION_FALLBACK = {
     element: 'Exception',
     map: 'Exception (whole map)',
 };
+/**
+ * What the bubble calls each kind of authority a rule can claim
+ * ({@link RuleProvenance}).
+ *
+ * The one wording in this file that changes what a finding MEANS rather than
+ * how it looks: "Standard" tells an architect the diagram breaks a published
+ * specification, "Labre convention" tells them it does not. An external review
+ * of the BPMN pack asked for exactly this line, because a house style shown
+ * without it reads as a norm violation — and a tool that cannot be trusted on
+ * that distinction is a tool an architect stops believing.
+ *
+ * The word only; the CITATION beside it is the rule's own `reference`, rendered
+ * verbatim and never translated (a page number is the same in every language).
+ *
+ * Exported for the same reason {@link SEVERITY_FALLBACK} is: the manifest walks
+ * this table under `com.labre.validation.provenance.` instead of restating four
+ * wordings a source scan could not check behind a template key.
+ */
+export const PROVENANCE_FALLBACK = {
+    standard: 'Standard',
+    recommendation: 'Recommendation',
+    'labre-convention': 'Labre convention',
+    organization: 'Organisation rule',
+};
 /**
  * The PERSISTENT half of the PF7 affordance, and the restitution behind it.
  *
@@ -155,11 +179,20 @@ export const EXEMPTION_FALLBACK = {
  *
  * ## What it knows
  *
- * Nothing about rules. It consumes normalised {@link Violation} objects off
- * `ValidationManager.violations$` and resolves their `messageKey` through the
- * host's catalogue ({@link translateKey}), falling back to the raw key. No rule
- * logic, no hard-coded rule wording — the library must not put words in a
- * framework's mouth.
+ * No rule LOGIC, and no hard-coded rule wording — the library must not put
+ * words in a framework's mouth. It consumes normalised {@link Violation}
+ * objects off `ValidationManager.violations$` and resolves their `messageKey`
+ * through the host's catalogue ({@link translateKey}), falling back to the raw
+ * key.
+ *
+ * The one thing it reads off the RULE rather than off the finding is
+ * {@link ValidationRule.provenance} — whether the sentence above it restates a
+ * published standard, a linter's recommendation, or a Labre house style. It is
+ * looked up by `ruleId` through {@link ValidationManager.ruleOf}, the same path
+ * this widget already walks to name a finding's framework when it reports an
+ * exception, and it is still declared data rather than logic: the widget
+ * chooses the LABEL for a source it is handed, and prints the citation
+ * verbatim.
  */
 let ViolationDetailWidget = (() => {
     let _classSuper = WidgetComponent;
@@ -403,6 +436,22 @@ let ViolationDetailWidget = (() => {
       overflow-wrap: anywhere;
     }
 
+    /* Where the rule's authority comes from. Discreet on purpose: it is
+       context for the sentence above it, not a second finding — one line,
+       secondary colour, below the suggestion and above the way out. */
+    .violation-provenance {
+      margin-top: 6px;
+      color: var(--affine-text-secondary-color);
+      font-size: 12px;
+      overflow-wrap: anywhere;
+    }
+
+    /* The LABEL carries the weight, because it is the word that decides how
+       much an architect has to care. The citation beside it stays plain. */
+    .violation-provenance-source {
+      font-weight: 600;
+    }
+
     /* "No rule is a wall": the way out is on the message, one click away, and
        never behind a settings panel (PF8.1). */
     .violation-actions {
@@ -627,11 +676,50 @@ let ViolationDetailWidget = (() => {
             const padding = 24;
             // Message, optional hint, severity chip and the action row underneath it.
             const perEntry = 100;
-            return Math.min(BUBBLE_MAX_HEIGHT, padding + Math.max(1, entries.length) * perEntry);
+            // ...plus one line for each entry that will actually SHOW a provenance,
+            // asked the same way the render asks it. A framework whose rules declare
+            // none must not have the bubble reserve room for a line it never draws.
+            const provenanceLine = 18;
+            const validation = this.std.getOptional(ValidationManager);
+            const cited = entries.filter(entry => validation?.ruleOf(entry.ruleId)?.provenance !== undefined).length;
+            return Math.min(BUBBLE_MAX_HEIGHT, padding + Math.max(1, entries.length) * perEntry + cited * provenanceLine);
         }
         _severityLabel(severity) {
             return translateKey(this.std, `com.labre.validation.severity.${severity}`, SEVERITY_FALLBACK[severity]);
         }
+        /**
+         * The one line saying where the rule behind a finding gets its authority.
+         *
+         * Resolved through {@link ValidationManager.ruleOf}, which is the path this
+         * widget already uses to name a finding's framework when it reports an
+         * exception — the bubble consumes normalised {@link Violation}s and knows
+         * nothing about rules, so the manager is the only place a rule can come from.
+         *
+         * Rendered ONLY when the rule declares one. A rule that says nothing about
+         * its provenance gets no line and no invented one: the library must not put
+         * an authority in a framework's mouth any more than it puts words there
+         * (see {@link translateKey}). That is also why the fallback is chrome-only —
+         * the LABEL is ours, the citation is the framework's, and the citation is
+         * printed exactly as declared rather than translated.
+         */
+        _renderProvenance(ruleId) {
+            const provenance = this.std
+                .getOptional(ValidationManager)
+                ?.ruleOf(ruleId)?.provenance;
+            if (provenance === undefined)
+                return nothing;
+            const { source, reference } = provenance;
+            const label = translateKey(this.std, `com.labre.validation.provenance.${source}`, PROVENANCE_FALLBACK[source]);
+            return html `<div
+      class="violation-provenance"
+      data-testid="violation-provenance"
+      data-provenance=${source}
+    >
+      <span class="violation-provenance-source">${label}</span>${reference
+                ? html ` — ${reference}`
+                : nothing}
+    </div>`;
+        }
         /**
          * Grant or revoke, then report it.
          *
@@ -696,15 +784,15 @@ let ViolationDetailWidget = (() => {
         _renderEntry(entry, violations) {
             const { exemption } = entry;
             const action = (key, fallback, testid, scope, granted) => html `<button
-      class="violation-action"
-      type="button"
-      data-testid=${testid}
-      @pointerdown=${this._swallow}
-      @pointerup=${this._swallow}
-      @click=${this._exception(violations, scope, granted)}
-    >
-      ${translateKey(this.std, key, fallback)}
-    </button>`;
+        class="violation-action"
+        type="button"
+        data-testid=${testid}
+        @pointerdown=${this._swallow}
+        @pointerup=${this._swallow}
+        @click=${this._exception(violations, scope, granted)}
+      >
+        ${translateKey(this.std, key, fallback)}
+      </button>`;
             return html `<div class="violation-entry" data-exemption=${exemption ?? ''}>
       <div class="violation-severity" data-severity=${entry.severity}>
         ${this._severityLabel(entry.severity)}
@@ -726,6 +814,7 @@ let ViolationDetailWidget = (() => {
             ${translateKey(this.std, entry.suggestion, entry.suggestionFallback)}
           </div>`
                 : nothing}
+      ${this._renderProvenance(entry.ruleId)}
       <div class="violation-actions">
         ${exemption
                 ? action('com.labre.validation.action.revoke', 'Revoke', 'violation-revoke', exemption, false)
@@ -734,8 +823,7 @@ let ViolationDetailWidget = (() => {
                 // A family that measures against no background records no
                 // `backgroundId`, so there is no map to write the wider
                 // arbitration on and the action simply does not exist.
-                violations.some(violation => violation.backgroundId !== undefined) &&
-                    this._isRepeated(violations)
+                violations.some(violation => violation.backgroundId !== undefined) && this._isRepeated(violations)
                     ? action('com.labre.validation.action.ignore-map', 'Ignore this rule on the whole map', 'violation-ignore-map', 'map', true)
                     : nothing}`}
       </div>
@@ -763,7 +851,9 @@ let ViolationDetailWidget = (() => {
       data-flip-y=${flipY}
       aria-label=${translateKey(this.std, 'com.labre.validation.bubble.label', 'Validation details')}
       style=${styleMap({
-                left: flipX ? `${x - BUBBLE_GAP - BUBBLE_WIDTH}px` : `${x + BUBBLE_GAP}px`,
+                left: flipX
+                    ? `${x - BUBBLE_GAP - BUBBLE_WIDTH}px`
+                    : `${x + BUBBLE_GAP}px`,
                 top: flipY ? `${y - BUBBLE_GAP}px` : `${y + BUBBLE_GAP}px`,
                 ...(flipY ? { transform: 'translateY(-100%)' } : {}),
             })}
@@ -838,29 +928,34 @@ let ViolationDetailWidget = (() => {
             const width = right - left;
             const height = bottom - top;
             const strips = [
-                { left: left - band, top: top - band, width: width + band * 2, height: band },
+                {
+                    left: left - band,
+                    top: top - band,
+                    width: width + band * 2,
+                    height: band,
+                },
                 { left: left - band, top: bottom, width: width + band * 2, height: band },
                 { left: left - band, top, width: band, height },
                 { left: right, top, width: band, height },
             ];
             return strips.map(strip => html `<button
-        class="violation-bracket-hit"
-        type="button"
-        tabindex="-1"
-        aria-hidden="true"
-        data-anchor-id=${anchor.id}
-        data-testid="violation-bracket-hit"
-        title=${label}
-        style=${styleMap({
+          class="violation-bracket-hit"
+          type="button"
+          tabindex="-1"
+          aria-hidden="true"
+          data-anchor-id=${anchor.id}
+          data-testid="violation-bracket-hit"
+          title=${label}
+          style=${styleMap({
                 left: `${strip.left}px`,
                 top: `${strip.top}px`,
                 width: `${Math.max(0, strip.width)}px`,
                 height: `${Math.max(0, strip.height)}px`,
             })}
-        @pointerdown=${this._swallow}
-        @pointerup=${this._swallow}
-        @click=${this._open(anchor.id)}
-      ></button>`);
+          @pointerdown=${this._swallow}
+          @pointerup=${this._swallow}
+          @click=${this._open(anchor.id)}
+        ></button>`);
         }
         render() {
             if (this._violations.length === 0)
@@ -891,7 +986,9 @@ let ViolationDetailWidget = (() => {
                 }
                 // Strictly one marker at a time: while the bracket is still drawn the
                 // badge does not exist, and the bracket's own band takes the clicks.
-                const fresh = timeline ? anchorEmphasis(anchor, timeline, now) > 0 : false;
+                const fresh = timeline
+                    ? anchorEmphasis(anchor, timeline, now) > 0
+                    : false;
                 const [badgeX, badgeY] = this._badgeAt(anchor);
                 return html `${fresh
                     ? this._renderBracketHit(anchor, label)

package/dist/_pkgs/affine-block-surface/framework-background/def.d.ts

@@ -59,6 +59,18 @@ export interface BackgroundTextStyle {
     weight?: number;
     /** Named consumer: Estuarine's `e` / `t` letters are `italic 700`. */
     italic?: boolean;
+    /**
+     * Where the anchor sits on the glyphs. `alphabetic` — the default, and what
+     * every text meant before this existed — puts it on the BASELINE, so the
+     * words hang above the anchor; `middle` centres them on it.
+     *
+     * Named consumer: the BPMN pool, whose participant name is centred ACROSS the
+     * band it is written in. A baseline anchor there would push the name against
+     * the frame instead of down the middle of the band — the one case where the
+     * two conventions are visibly different, because the room the text is given
+     * is the width of the glyphs and nothing more.
+     */
+    baseline?: 'alphabetic' | 'middle';
 }
 /** Where a piece of text sits: a plot ratio plus a fixed model-unit offset. */
 export interface BackgroundAnchor {
@@ -92,6 +104,18 @@ export interface BackgroundTextDef extends BackgroundLabelSource {
     id: string;
     anchor: BackgroundAnchor;
     style: BackgroundTextStyle;
+    /**
+     * Only drawn when {@link FrameworkBackgroundDef.variantProp} reads one of
+     * these — the same semantics a wash already has
+     * ({@link BackgroundWashDef.variants}), and the reason a variant is a
+     * DECLARATION and not a second background.
+     *
+     * Absent means every variant, which is what every text meant before this
+     * existed. Distinct from {@link visibleProp}, and the two compose: a variant
+     * says which chart this text belongs to, a visible prop says whether the user
+     * has switched it off in the chart it does belong to.
+     */
+    variants?: readonly string[];
     /** Defaults to `left` for horizontal text and `center` for vertical. */
     align?: 'left' | 'center' | 'right';
     /** Drawn rotated -90°, reading bottom-to-top. */
@@ -167,6 +191,19 @@ export interface BackgroundZoneDef {
         w: Ratio;
         h: Ratio;
     };
+    /**
+     * The variants this zone exists in, same semantics as
+     * {@link BackgroundWashDef.variants}: only drawn when
+     * {@link FrameworkBackgroundDef.variantProp} reads one of them, and absent
+     * means all of them.
+     *
+     * Unlike {@link fillVisibleProp}, which gates the TINT alone, this gates the
+     * zone as a whole — its {@link label} included, unless that label names its
+     * own variants. A quadrant that is not part of this reading of the chart has
+     * no name to be written on the canvas either, and the same precedent already
+     * holds one layer up: an axis' title shares the axis' visibility.
+     */
+    variants?: readonly string[];
     /** Tint painted under everything but the card. */
     fill?: BackgroundColor;
     /** Model prop gating the tint (not the label). */
@@ -174,6 +211,135 @@ export interface BackgroundZoneDef {
     /** The zone name. Anchored in plot ratios like any other text. */
     label?: BackgroundTextDef;
 }
+/**
+ * One region of the plot an INSTANCE declares, read off a model prop.
+ *
+ * The counterpart of {@link BackgroundZoneDef}, which is part of the framework
+ * and identical on every element of it. This one is the user's own partition of
+ * their own frame: a BPMN pool's lanes (couloirs) are exactly this — how many
+ * there are, what they are called and how the height is shared between them is
+ * a property of THAT pool, not of BPMN.
+ */
+export interface BackgroundInstanceZoneItem {
+    /** Stable id inside the instance; what a reported zone id is built from. */
+    id: string;
+    /** The zone name, drawn in the band. Absent means an unnamed band. */
+    name?: string;
+    /**
+     * A relative WEIGHT, not a length: the zones share the plot in proportion to
+     * their sizes. See {@link BackgroundInstanceZonesDef} for why.
+     */
+    size: number;
+}
+/**
+ * A label STRIP at the leading edge of every instance zone.
+ *
+ * The placement BPMN 2.0 draws a lane title in, and the one bpmn.io, Camunda
+ * and Visio all render: a fixed-width band along the lane's leading edge,
+ * immediately inside the pool's own participant band, with the lane name turned
+ * on its side. The first placement this file offered wrote the name across the
+ * zone's top-left corner instead; the PO's visual recette (2026-08-26) settled
+ * it against the corner, on notation rather than on taste — a reader who knows
+ * BPMN reads the strip as a lane title and a floating corner word as a note.
+ *
+ * ## The strip is CHROME, not a smaller zone
+ *
+ * {@link backgroundInstanceZones} keeps reporting the FULL plot slice, and the
+ * strip is painted inside it. That is the BPMN reading and not an
+ * implementation shortcut: the title band belongs TO the lane, so an element
+ * dropped on it is in that lane, and a lane's share of the pool does not shrink
+ * because it was given a name. Membership, the audit and every rule therefore
+ * see exactly what they saw before this existed.
+ *
+ * ## Which way the words run
+ *
+ * From the stack, not from a field: a `'y'` stack makes the strip tall and
+ * narrow, so the name is rotated to read bottom-to-top, exactly as the
+ * participant name is one level up ({@link BackgroundSideBandDef}); an `'x'`
+ * stack makes it short and wide, so the name stays upright. A declaration that
+ * could disagree with its own geometry would only ever be a way to get it
+ * wrong.
+ */
+export interface BackgroundInstanceZoneBandDef {
+    /** Strip thickness in FIXED model units — across the stacking direction. */
+    width: number;
+    /** The line between the strip and the rest of the zone. Absent means none. */
+    divider?: BackgroundStroke;
+}
+/**
+ * A background whose plot its INSTANCES divide up.
+ *
+ * A framework declares here that its elements carry their own partition, which
+ * prop holds it and how the pieces stack; the primitive paints the dividers and
+ * the names, and the audit reports the pieces as zones like any other. Named
+ * consumer: the BPMN pool, whose lanes arrive in the tranche after this one.
+ *
+ * ## Why weights and not model units
+ *
+ * Every position in this file is a ratio of the plot precisely so that a
+ * background survives being stretched, and an instance partition has to survive
+ * it too. Sizes are therefore NORMALISED over their sum: a pool with lanes of
+ * `1, 2, 1` gives the middle one half the height at any size, and dragging the
+ * pool taller redistributes the extra space proportionally instead of leaving a
+ * gap under the last band or pushing it out of the frame. The numbers are also
+ * free of a unit the user would have to think in — `2` reads as "twice the
+ * other one", which is the only thing a lane's height ever means.
+ */
+export interface BackgroundInstanceZonesDef {
+    /** Model prop holding the {@link BackgroundInstanceZoneItem}[]. */
+    prop: string;
+    /**
+     * Which way the zones stack. `'y'` lays them out as horizontal bands, full
+     * width, top to bottom in array order — the BPMN pool. `'x'` is the
+     * symmetric case: full-height columns, left to right.
+     */
+    stack: 'x' | 'y';
+    /** The line between two adjacent zones. Absent means none is drawn. */
+    divider?: BackgroundStroke;
+    /**
+     * How a zone's {@link BackgroundInstanceZoneItem.name} is written.
+     *
+     * Not a {@link BackgroundTextDef}: there is one style for every zone of the
+     * instance, and the anchor is the zone's own geometry rather than a declared
+     * ratio — the whole point is that the declaration does not know how many
+     * zones there are or where they sit.
+     *
+     * ## Two placements, selected by the PRESENCE of {@link band}
+     *
+     * - **corner** (no `band`) — horizontal, anchored at the top-left of the
+     *   zone, inset by `dx` / `dy` in FIXED model units like every other offset
+     *   here. The original placement, and still the default;
+     * - **band** — a fixed-width label STRIP at the zone's leading edge, with the
+     *   name written along it: rotated for a `'y'` stack, upright for an `'x'`
+     *   one. See {@link BackgroundInstanceZoneBandDef}.
+     *
+     * Presence as the selector rather than a discriminated union, deliberately.
+     * A union would need a tag on every declaration that already exists, which
+     * makes an additive change a breaking one for no reader; and presence is
+     * already how this file says "this feature is off" everywhere else — an
+     * absent `instanceZones` is no partition, an absent `divider` is no line, an
+     * absent `label` is no names at all. `dx` / `dy` belong to the corner
+     * placement and are ignored under a band, which has no corner to inset from.
+     */
+    label?: {
+        style: BackgroundTextStyle;
+        /** Corner placement only. */
+        dx?: number;
+        /** Corner placement only. */
+        dy?: number;
+        /** Present = band placement. */
+        band?: BackgroundInstanceZoneBandDef;
+    };
+    /**
+     * Prefix of the reported zone ids: `'lane'` reports `lane:sales`.
+     *
+     * A namespace, not decoration. The instance zones are concatenated with the
+     * declared ones ({@link FrameworkBackgroundDef.zones}) wherever zones are
+     * consumed, and a user free to name a lane `early` must not be able to shadow
+     * a framework zone by doing so.
+     */
+    idPrefix: string;
+}
 /**
  * A flat colour wash over the plot, given as gradient stops.
  *
@@ -196,12 +362,56 @@ export interface BackgroundWashDef {
 }
 export interface BackgroundSurfaceDef {
     fill?: BackgroundColor;
+    /**
+     * The frame round the card. `dash` is a pattern in model units, exactly as
+     * {@link BackgroundStroke.dash} is; absent — which is what every declaration
+     * written before it existed says — draws the solid line it always drew.
+     *
+     * Named consumer: the C4 boundary, which the notation draws as a DASHED
+     * rectangle round a group of elements. A dash is what tells a boundary from a
+     * board on that canvas, so it belongs where the rest of the frame is declared
+     * rather than in a renderer wrapper only one framework would ever have.
+     */
     border?: {
         color: BackgroundColor;
         width: number;
         radius?: number;
+        dash?: readonly number[];
     };
 }
+/**
+ * A filled strip of FIXED width, painted over one margin of the card.
+ *
+ * The width of a band IS the margin it covers
+ * ({@link BackgroundGeometry.margin}), never a second number: the margin is
+ * already the room the plot gives up to the furniture, and letting a
+ * declaration state a different width would be two numbers that must agree and
+ * one day will not. An element narrower than its own margin clamps the band to
+ * the element, which is the only case where the two can disagree.
+ *
+ * A band is part of the CARD, not a layer over it: it is painted over the
+ * card's fill and under its border, so the frame keeps outlining the whole
+ * element. Its {@link label} is a text like any other, drawn with the rest of
+ * them, and anchored in plot ratios — the plot edge is the band's inner edge,
+ * so `x: 0` with a negative `dx` walks back INTO the band.
+ *
+ * Named consumer: the BPMN pool, a lane whose participant name is written up a
+ * filled band along its left edge, with a {@link divider} between that band and
+ * the flow area.
+ *
+ * Only `'left'` for now — same philosophy as the wash direction
+ * ({@link BackgroundWashDef.stops}): the union grows the day a framework asks
+ * for a top or a right band, not in anticipation of one.
+ */
+export interface BackgroundSideBandDef {
+    side: 'left';
+    /** Tint over the whole strip. Absent means the card shows through. */
+    fill?: BackgroundColor;
+    /** The line between the band and the plot. Absent means none. */
+    divider?: BackgroundStroke;
+    /** The words written in the band — the band's own label. */
+    label?: BackgroundTextDef;
+}
 /** Everything that dresses the frame: the card, the fills, the colour code. */
 export interface BackgroundChromeDef {
     /** Font family every text inherits unless it names its own. */
@@ -211,6 +421,11 @@ export interface BackgroundChromeDef {
      * a plain white rectangle with no border.
      */
     surface?: BackgroundSurfaceDef;
+    /**
+     * Filled strips over the margins, painted WITH the card — over its fill, under
+     * its border — in declaration order.
+     */
+    sideBands?: readonly BackgroundSideBandDef[];
     /** Washes over the plot, painted in declaration order, under the zones. */
     washes?: readonly BackgroundWashDef[];
     /** The colour code: names a palette entry `@name` can resolve to. */
@@ -253,6 +468,12 @@ export interface FrameworkBackgroundDef {
     variantProp?: string;
     axes?: readonly BackgroundAxisDef[];
     zones?: readonly BackgroundZoneDef[];
+    /**
+     * The plot partition each INSTANCE carries, if this framework lets its
+     * elements declare one. Absent — the case for every framework so far — means
+     * a background whose zones are the same on every element of it.
+     */
+    instanceZones?: BackgroundInstanceZonesDef;
     /**
      * Width of the TOLERANCE BAND around each zone transition, as a ratio of the
      * plot span the transition is measured across. Centred on the transition, so
@@ -299,6 +520,74 @@ export declare function warnBrokenBackgroundColor(reason: string): void;
  * request for transparency: it warns and returns {@link BROKEN_BACKGROUND_COLOR}.
  */
 export declare function backgroundColor(color: BackgroundColor | undefined, palette: Readonly<Record<string, BackgroundColor>> | undefined): string;
+/** One zone of one instance, resolved: a name and a rectangle in plot ratios. */
+export interface BackgroundInstanceZone {
+    /** `${idPrefix}:${item.id}` — never collides with a declared zone id. */
+    id: string;
+    name?: string;
+    rect: {
+        x: Ratio;
+        y: Ratio;
+        w: Ratio;
+        h: Ratio;
+    };
+}
+/**
+ * The plot partition ONE instance carries, as rectangles in plot ratios.
+ *
+ * The semantic accessor onto {@link BackgroundInstanceZonesDef}: everything
+ * that has to know where a user's own zones sit — the renderer that draws their
+ * dividers and their names, the audit that reports them, the rules a later
+ * tranche will judge inside them — reads them here, so a lane is one shape and
+ * not four that must agree. Named consumer: the BPMN pool's lanes (couloirs).
+ *
+ * Pure: declaration plus the instance's bag of props in, plain data out. Ratios
+ * and not model units, for the reason every position in this file is a ratio —
+ * an instance stretched to twice its height keeps the same partition.
+ *
+ * ## What a malformed partition does
+ *
+ * A partition is data the user edits, so it gets typos and half-written rows,
+ * and none of them may take the frame down or paint a picture that lies:
+ *
+ * - a missing, empty or non-array prop yields `[]` — a background that simply
+ *   has no partition yet, which is what every instance looks like the moment it
+ *   is created;
+ * - an entry that is not an object, or carries no string id, is dropped;
+ * - a size that is not a finite number, or is `0` or less, is dropped with a
+ *   warning: a zero-height band is a band nothing can be in, and a negative one
+ *   would eat into its neighbours. Dropped rather than clamped, for the reason
+ *   {@link FrameworkBackgroundDef.transitionBandWidth} drops its own degenerate
+ *   case — silently inventing a size is worse than showing one band fewer;
+ * - once for each distinct problem, like every other diagnostic on the paint
+ *   path (see {@link warnBrokenBackgroundColor}).
+ *
+ * The survivors keep their declaration ORDER, and their sizes are normalised
+ * over the sum of the survivors — so dropping a broken row redistributes its
+ * space rather than leaving a hole where it was.
+ */
+export declare function backgroundInstanceZones(def: FrameworkBackgroundDef, model: Readonly<Record<string, unknown>>): readonly BackgroundInstanceZone[];
+/** A rectangle in ELEMENT-LOCAL model units, i.e. what the renderer paints in. */
+export interface BackgroundRect {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+}
+/**
+ * The label STRIP of one instance zone, in element-local model units.
+ *
+ * `null` when the declaration asks for no band, or when there is no room for
+ * one. THE one place that knows where a lane title sits: the renderer paints
+ * from it and the framework's view hit-tests a double-click against it, so the
+ * words a user aims at and the words they get are the same rectangle by
+ * construction rather than by two constants that must agree.
+ *
+ * Clamped to the plot, the way a side band clamps to an element narrower than
+ * its own margin ({@link BackgroundSideBandDef}) — the same degenerate case,
+ * and the same answer.
+ */
+export declare function backgroundInstanceZoneBand(def: FrameworkBackgroundDef, zone: BackgroundInstanceZone, plot: ReturnType<typeof backgroundPlot>): BackgroundRect | null;
 /**
  * Whether the resize handles are offered for this element.
  *