@formicoidea/labre-core 0.32.0 → 0.33.0

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

@@ -28,12 +28,15 @@ export function backgroundPoint(anchor, plot) {
 export const BROKEN_BACKGROUND_COLOR = '#ff00ff';
 /** Warn once per distinct problem: a renderer runs on every frame. */
 const warned = new Set();
-export function warnBrokenBackgroundColor(reason) {
+function warnOnce(reason) {
     if (warned.has(reason))
         return;
     warned.add(reason);
     console.warn(`[framework-background] ${reason}`);
 }
+export function warnBrokenBackgroundColor(reason) {
+    warnOnce(reason);
+}
 /**
  * Resolve `@name` against the palette; anything else is a literal colour.
  *
@@ -51,6 +54,128 @@ export function backgroundColor(color, palette) {
     warnBrokenBackgroundColor(`no palette entry for "${color}"`);
     return BROKEN_BACKGROUND_COLOR;
 }
+/** Nothing to report, shared so the common case allocates no array. */
+const NO_INSTANCE_ZONES = Object.freeze([]);
+/**
+ * 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 function backgroundInstanceZones(def, model) {
+    const spec = def.instanceZones;
+    if (spec === undefined)
+        return NO_INSTANCE_ZONES;
+    const raw = model[spec.prop];
+    if (!Array.isArray(raw) || raw.length === 0)
+        return NO_INSTANCE_ZONES;
+    const items = [];
+    let total = 0;
+    for (const entry of raw) {
+        if (typeof entry !== 'object' || entry === null)
+            continue;
+        const item = entry;
+        if (typeof item.id !== 'string' || item.id === '')
+            continue;
+        const size = item.size;
+        if (typeof size !== 'number' || !Number.isFinite(size) || size <= 0) {
+            warnOnce(`"${def.type}" instance zone "${item.id}" declares a size of ${String(size)} — a zone with no extent is one nothing can be inside, so it is ` +
+                `dropped and its neighbours share the space.`);
+            continue;
+        }
+        items.push({
+            id: item.id,
+            ...(typeof item.name === 'string' ? { name: item.name } : {}),
+            size,
+        });
+        total += size;
+    }
+    if (items.length === 0 || !(total > 0))
+        return NO_INSTANCE_ZONES;
+    const zones = [];
+    let at = 0;
+    for (const item of items) {
+        const share = item.size / total;
+        zones.push({
+            id: `${spec.idPrefix}:${item.id}`,
+            ...(item.name !== undefined ? { name: item.name } : {}),
+            rect: spec.stack === 'y'
+                ? { x: 0, y: at, w: 1, h: share }
+                : { x: at, y: 0, w: share, h: 1 },
+        });
+        at += share;
+    }
+    return zones;
+}
+/**
+ * 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 function backgroundInstanceZoneBand(def, zone, plot) {
+    const spec = def.instanceZones;
+    const band = spec?.label?.band;
+    if (spec === undefined || band === undefined)
+        return null;
+    if (!(band.width > 0))
+        return null;
+    if (spec.stack === 'y') {
+        const width = Math.min(band.width, plot.width);
+        if (!(width > 0))
+            return null;
+        return {
+            x: plot.x0,
+            y: plot.y0 + zone.rect.y * plot.height,
+            w: width,
+            h: zone.rect.h * plot.height,
+        };
+    }
+    const height = Math.min(band.width, plot.height);
+    if (!(height > 0))
+        return null;
+    return {
+        x: plot.x0 + zone.rect.x * plot.width,
+        y: plot.y0,
+        w: zone.rect.w * plot.width,
+        h: height,
+    };
+}
 /**
  * Whether the resize handles are offered for this element.
  *

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

@@ -19,6 +19,22 @@ export type BackgroundModelLike = Record<string, unknown>;
 export declare function backgroundLabelText(source: BackgroundLabelSource, model: BackgroundModelLike, translation?: TranslationService | null): string;
 /** Whether a `visibleProp` gate is open. No gate means always drawn. */
 export declare function backgroundVisible(visibleProp: string | undefined, model: BackgroundModelLike): boolean;
+/**
+ * Whether a piece of the declaration belongs to the variant this INSTANCE is
+ * currently reading — the one gate washes, zones and texts all pass through.
+ *
+ * A variant is a second reading of the same frame (a Core Domain Chart read for
+ * migration rather than for investment), so it is declared once, on the piece
+ * that belongs to it, and selected by a single model prop. Declaring `variants`
+ * with no {@link FrameworkBackgroundDef.variantProp} is a broken declaration and
+ * paints nothing: there is no prop to be one of them. It also says so out loud,
+ * once — a piece that is invisible everywhere with no diagnostic is the kind of
+ * authoring mistake somebody spends an afternoon on.
+ *
+ * Absent means every variant, which is what everything meant before variants
+ * existed.
+ */
+export declare function backgroundInVariant(def: FrameworkBackgroundDef, variants: readonly string[] | undefined, model: BackgroundModelLike): boolean;
 /** A label's clickable box in element-local coordinates (axis-aligned, padded). */
 export interface BackgroundLabelHit {
     /** The declaration id of the text. */
@@ -39,11 +55,35 @@ export interface BackgroundLabelHit {
     maxY: number;
 }
 /**
- * Every text of a declaration, in PAINTING ORDER: zone labels, then each axis'
- * title followed by its end labels.
+ * Every text of a declaration, in PAINTING ORDER: the side-band labels, the
+ * zone labels, then each axis' title followed by its end labels.
  *
  * One walk, used by both the renderer and the hit tester, so a label can never
  * be drawn in one place and clicked in another.
+ *
+ * The bands lead because a band is part of the card, which is painted first.
+ * Two gates are INHERITED here rather than restated by every framework: a zone's
+ * variants reach its label, and an axis' visibility reaches its title. Both are
+ * overridden by a text that names its own.
+ *
+ * ## What this walk does NOT contain
+ *
+ * The names of the zones an INSTANCE declares
+ * ({@link FrameworkBackgroundDef.instanceZones} — a BPMN pool's lanes). This
+ * walk takes a declaration and nothing else, on purpose: it is what makes the
+ * hit boxes a pure function of the same data the renderer paints from, and
+ * every consumer of it — `backgroundLabelHits` above, the renderer's text
+ * stage — is built on that. Instance zone names come from the model, exist in a
+ * number the declaration does not know, and are anchored to a band whose
+ * position the declaration does not know either; widening the signature to take
+ * a model would push that question onto every caller to serve one of them.
+ *
+ * They are therefore drawn renderer-side and are NOT hit-testable: a zone name
+ * cannot be renamed by double-clicking it on the canvas. That is a deliberate
+ * limit and not an oversight — a zone is created and destroyed through its
+ * framework's own tooling, so that is where it is renamed too, and a label the
+ * hit tester never returns can never be drawn in one place and clicked in
+ * another either.
  */
 export declare function backgroundTexts(def: FrameworkBackgroundDef): BackgroundTextDef[];
 /**

package/dist/_pkgs/affine-block-surface/framework-background/labels.js

@@ -1,4 +1,19 @@
 import { backgroundPlot, backgroundPoint } from './def.js';
+/**
+ * Complain once per distinct problem.
+ *
+ * Same shape and same reason as the validation engine's own `warnOnce`: these
+ * primitives run on the PAINT path, once per piece of the declaration per
+ * frame, so a bare `console.warn` about a broken declaration would fill the
+ * console at the refresh rate while somebody drags the frame.
+ */
+const warned = new Set();
+function warnOnce(reason) {
+    if (warned.has(reason))
+        return;
+    warned.add(reason);
+    console.warn(`[framework-background] ${reason}`);
+}
 /**
  * The words a label actually says.
  *
@@ -31,22 +46,78 @@ export function backgroundLabelText(source, model, translation) {
 export function backgroundVisible(visibleProp, model) {
     return visibleProp === undefined ? true : Boolean(model[visibleProp]);
 }
+/**
+ * Whether a piece of the declaration belongs to the variant this INSTANCE is
+ * currently reading — the one gate washes, zones and texts all pass through.
+ *
+ * A variant is a second reading of the same frame (a Core Domain Chart read for
+ * migration rather than for investment), so it is declared once, on the piece
+ * that belongs to it, and selected by a single model prop. Declaring `variants`
+ * with no {@link FrameworkBackgroundDef.variantProp} is a broken declaration and
+ * paints nothing: there is no prop to be one of them. It also says so out loud,
+ * once — a piece that is invisible everywhere with no diagnostic is the kind of
+ * authoring mistake somebody spends an afternoon on.
+ *
+ * Absent means every variant, which is what everything meant before variants
+ * existed.
+ */
+export function backgroundInVariant(def, variants, model) {
+    if (variants === undefined)
+        return true;
+    if (def.variantProp === undefined) {
+        warnOnce(`background "${def.type}" declares variants (${variants.join(', ')}) ` +
+            `with no variantProp to select them — the piece is never painted.`);
+        return false;
+    }
+    return variants.includes(String(model[def.variantProp]));
+}
 /** Rough per-character advance — only used to size generous hit boxes. */
 const approxTextWidth = (text, fontSize) => Math.max(fontSize, text.length * fontSize * 0.6);
 /** Padding so double-clicking a label is forgiving. */
 const HIT_PAD = 6;
 /**
- * Every text of a declaration, in PAINTING ORDER: zone labels, then each axis'
- * title followed by its end labels.
+ * Every text of a declaration, in PAINTING ORDER: the side-band labels, the
+ * zone labels, then each axis' title followed by its end labels.
  *
  * One walk, used by both the renderer and the hit tester, so a label can never
  * be drawn in one place and clicked in another.
+ *
+ * The bands lead because a band is part of the card, which is painted first.
+ * Two gates are INHERITED here rather than restated by every framework: a zone's
+ * variants reach its label, and an axis' visibility reaches its title. Both are
+ * overridden by a text that names its own.
+ *
+ * ## What this walk does NOT contain
+ *
+ * The names of the zones an INSTANCE declares
+ * ({@link FrameworkBackgroundDef.instanceZones} — a BPMN pool's lanes). This
+ * walk takes a declaration and nothing else, on purpose: it is what makes the
+ * hit boxes a pure function of the same data the renderer paints from, and
+ * every consumer of it — `backgroundLabelHits` above, the renderer's text
+ * stage — is built on that. Instance zone names come from the model, exist in a
+ * number the declaration does not know, and are anchored to a band whose
+ * position the declaration does not know either; widening the signature to take
+ * a model would push that question onto every caller to serve one of them.
+ *
+ * They are therefore drawn renderer-side and are NOT hit-testable: a zone name
+ * cannot be renamed by double-clicking it on the canvas. That is a deliberate
+ * limit and not an oversight — a zone is created and destroyed through its
+ * framework's own tooling, so that is where it is renamed too, and a label the
+ * hit tester never returns can never be drawn in one place and clicked in
+ * another either.
  */
 export function backgroundTexts(def) {
     const texts = [];
+    for (const band of def.chrome?.sideBands ?? []) {
+        if (band.label)
+            texts.push(band.label);
+    }
     for (const zone of def.zones ?? []) {
-        if (zone.label)
-            texts.push(zone.label);
+        if (!zone.label)
+            continue;
+        texts.push(zone.variants === undefined || zone.label.variants !== undefined
+            ? zone.label
+            : { ...zone.label, variants: zone.variants });
     }
     for (const axis of def.axes ?? []) {
         // The title shares the axis' visibility; the end labels have their own.
@@ -73,6 +144,11 @@ export function backgroundLabelHits(def, model, w, h, translation) {
     for (const text of backgroundTexts(def)) {
         if (text.prop === undefined)
             continue;
+        // A label the instance's variant does not paint is not there to be
+        // double-clicked either: an editor opening on invisible words would offer
+        // to rename something the user cannot see.
+        if (!backgroundInVariant(def, text.variants, model))
+            continue;
         if (!backgroundVisible(text.visibleProp, model))
             continue;
         const words = backgroundLabelText(text, model, translation);

package/dist/_pkgs/affine-block-surface/framework-background/renderer.js

@@ -1,6 +1,6 @@
 import { TranslationProvider } from '../../affine-shared/services/index.js';
-import { backgroundColor, backgroundPlot, backgroundPoint, BROKEN_BACKGROUND_COLOR, DEFAULT_BACKGROUND_SURFACE, warnBrokenBackgroundColor, } from './def.js';
-import { backgroundLabelText, backgroundTexts, backgroundVisible, } from './labels.js';
+import { backgroundColor, backgroundInstanceZoneBand, backgroundInstanceZones, backgroundPlot, backgroundPoint, BROKEN_BACKGROUND_COLOR, DEFAULT_BACKGROUND_SURFACE, warnBrokenBackgroundColor, } from './def.js';
+import { backgroundInVariant, backgroundLabelText, backgroundTexts, backgroundVisible, } from './labels.js';
 /**
  * The framework-background PRIMITIVE (PF2.1): one renderer, driven entirely by
  * a {@link FrameworkBackgroundDef}. A framework gets its background by
@@ -12,12 +12,16 @@ import { backgroundLabelText, backgroundTexts, backgroundVisible, } from './labe
  * change, because order is what makes two backgrounds look like the same
  * product rather than two drawings:
  *
- * 1. the card — the element rectangle;
+ * 1. the card — the element rectangle, and the side bands that dress it: the
+ *    fill, then the bands over it, then the border over both, so the frame
+ *    keeps outlining the whole element;
  * 2. the washes, over the plot;
- * 3. the zone tints;
+ * 3. the zone tints, then the dividers between the zones THIS INSTANCE
+ *    declares;
  * 4. the graduations of every axis;
  * 5. the axis lines and their arrowheads;
- * 6. every text — zone names, then per axis its title and its end labels.
+ * 6. every text — the band labels, the zone names, then per axis its title and
+ *    its end labels, and last the names of the instance's own zones.
  *
  * A declaration that says nothing but its size therefore paints a plain white
  * rectangle: no axis, no zone, no decoration.
@@ -66,6 +70,19 @@ function fontOf(style, fallbackFamily) {
 }
 /** The family a declaration that names none falls back to. */
 const DEFAULT_FONT_FAMILY = 'Inter, sans-serif';
+/**
+ * Where an instance zone's name sits in its band when the declaration states no
+ * offset: 8 model units in from the leading edge, 18 down from the top of the
+ * band.
+ *
+ * The two are not the same number, and that is not an oversight. The anchor is
+ * a BASELINE by default ({@link BackgroundTextStyle.baseline}), so the words
+ * hang ABOVE it: `dy` has to clear a cap height before it is an inset at all,
+ * and 18 leaves a name of the usual 12–15 units sitting just inside the top of
+ * its band. A declaration whose style anchors `middle` wants its own.
+ */
+const DEFAULT_INSTANCE_ZONE_LABEL_DX = 8;
+const DEFAULT_INSTANCE_ZONE_LABEL_DY = 18;
 /**
  * Build the canvas renderer of one declaration. Pure: the same declaration
  * always paints the same picture for the same model and size.
@@ -76,9 +93,16 @@ export function createFrameworkBackgroundRenderer(def) {
     const surface = def.chrome?.surface ?? DEFAULT_BACKGROUND_SURFACE;
     const color = (c) => backgroundColor(c, palette);
     const texts = backgroundTexts(def);
+    // The DECLARATION of the instance partition — how it stacks, how it is drawn.
+    // What it contains is the model's business and is read on every paint.
+    const instanceZonesDef = def.instanceZones;
     return (model, ctx, matrix, renderer) => {
         const props = model;
         const visible = (prop) => backgroundVisible(prop, props);
+        // Which READING of the frame this instance is showing. Washes, zones and
+        // texts all name the variants they belong to, and a declaration that names
+        // none belongs to every one of them.
+        const inVariant = (variants) => backgroundInVariant(def, variants, props);
         // The host's catalogue, resolved once per paint. Absent in a bare unit
         // test (the renderer is called with three arguments) and absent in a host
         // that ships no locale pack — both fall back to the declared wording.
@@ -110,7 +134,7 @@ export function createFrameworkBackgroundRenderer(def) {
                 ctx.font = fontOf(style, family);
                 ctx.fillStyle = color(style.color);
                 ctx.textAlign = align ?? 'center';
-                ctx.textBaseline = 'alphabetic';
+                ctx.textBaseline = style.baseline ?? 'alphabetic';
                 ctx.fillText(words, 0, 0);
                 ctx.restore();
                 return;
@@ -118,28 +142,65 @@ export function createFrameworkBackgroundRenderer(def) {
             ctx.font = fontOf(style, family);
             ctx.fillStyle = color(style.color);
             ctx.textAlign = align ?? 'left';
-            ctx.textBaseline = 'alphabetic';
+            ctx.textBaseline = style.baseline ?? 'alphabetic';
             ctx.fillText(words, ax, ay);
         };
-        // ── 1. The card ─────────────────────────────────────────────────────
+        // ── 1. The card, and the bands that dress it ────────────────────────
         const border = surface.border;
         const inset = border ? border.width / 2 : 0;
-        roundRectPath(ctx, inset, inset, w - inset * 2, h - inset * 2, border?.radius ?? 0);
+        const cardPath = () => roundRectPath(ctx, inset, inset, w - inset * 2, h - inset * 2, border?.radius ?? 0);
+        cardPath();
         if (surface.fill) {
             ctx.fillStyle = color(surface.fill);
             ctx.fill();
         }
+        // The side bands sit BETWEEN the fill and the border: a band is part of the
+        // card, and one painted over the frame would erase the edge it runs along,
+        // which reads as a broken card rather than as a band. Drawing a divider
+        // resets the current path, hence the second trace before the stroke — a
+        // declaration with no band never reaches it, so its picture is unchanged
+        // down to the operation.
+        const bands = def.chrome?.sideBands;
+        if (bands?.length) {
+            // The band IS the margin strip, clamped to an element narrower than its
+            // own margin — the one case where the two can disagree.
+            const bandWidth = Math.min(x0, w);
+            for (const band of bands) {
+                if (bandWidth <= 0)
+                    continue;
+                if (band.fill) {
+                    ctx.fillStyle = color(band.fill);
+                    ctx.fillRect(0, 0, bandWidth, h);
+                }
+                const divider = band.divider;
+                if (divider) {
+                    ctx.strokeStyle = color(divider.color);
+                    ctx.lineWidth = divider.width;
+                    if (divider.dash?.length)
+                        ctx.setLineDash([...divider.dash]);
+                    // Full height: the strip a margin gives up runs the whole side.
+                    line(bandWidth, 0, bandWidth, h);
+                    if (divider.dash?.length)
+                        ctx.setLineDash([]);
+                }
+            }
+            if (border)
+                cardPath();
+        }
         if (border) {
             ctx.strokeStyle = color(border.color);
             ctx.lineWidth = border.width;
+            if (border.dash?.length)
+                ctx.setLineDash([...border.dash]);
             ctx.stroke();
+            if (border.dash?.length)
+                ctx.setLineDash([]);
         }
         // ── 2. Washes over the plot ─────────────────────────────────────────
         const washes = def.chrome?.washes;
         if (washes?.length) {
-            const variant = def.variantProp === undefined ? undefined : props[def.variantProp];
             for (const wash of washes) {
-                if (wash.variants && !wash.variants.includes(String(variant)))
+                if (!inVariant(wash.variants))
                     continue;
                 if (!visible(wash.visibleProp))
                     continue;
@@ -156,11 +217,50 @@ export function createFrameworkBackgroundRenderer(def) {
         for (const zone of def.zones ?? []) {
             if (!zone.fill)
                 continue;
+            if (!inVariant(zone.variants))
+                continue;
             if (!visible(zone.fillVisibleProp))
                 continue;
             ctx.fillStyle = color(zone.fill);
             ctx.fillRect(x0 + zone.rect.x * pw, y0 + zone.rect.y * ph, zone.rect.w * pw, zone.rect.h * ph);
         }
+        // The partition THIS element carries, resolved once per paint: alone on
+        // this pipeline it is a function of the model rather than of the
+        // declaration. A framework that declares none never reads the model and
+        // never allocates.
+        const instanceZones = instanceZonesDef
+            ? backgroundInstanceZones(def, props)
+            : [];
+        // Dividers between adjacent instance zones: N zones, N−1 lines, on the
+        // INTERNAL boundaries only — the outer edges belong to the plot, and a line
+        // there would double the frame that is already drawn round it.
+        //
+        // Painted here, at the end of stage 3, rather than with the axis lines: a
+        // divider is part of what the zones ARE, so it belongs with the zones, and
+        // it must lie UNDER the graduations and the axes, which describe the frame
+        // of reference the user cannot move. After the tints, for the ordinary
+        // reason a fill goes under a line.
+        const zoneDivider = instanceZonesDef?.divider;
+        if (zoneDivider && instanceZones.length > 1) {
+            ctx.strokeStyle = color(zoneDivider.color);
+            ctx.lineWidth = zoneDivider.width;
+            if (zoneDivider.dash?.length)
+                ctx.setLineDash([...zoneDivider.dash]);
+            // Every zone but the first opens on a boundary with the one before it.
+            for (let i = 1; i < instanceZones.length; i++) {
+                const { x, y } = instanceZones[i].rect;
+                if (instanceZonesDef?.stack === 'y') {
+                    const ty = y0 + y * ph;
+                    line(x0, ty, x1, ty);
+                }
+                else {
+                    const tx = x0 + x * pw;
+                    line(tx, y0, tx, y1);
+                }
+            }
+            if (zoneDivider.dash?.length)
+                ctx.setLineDash([]);
+        }
         // ── 4. Graduations ──────────────────────────────────────────────────
         for (const axis of def.axes ?? []) {
             const graduations = axis.ticks;
@@ -191,11 +291,72 @@ export function createFrameworkBackgroundRenderer(def) {
         }
         // ── 6. Every text, in declaration order ─────────────────────────────
         for (const text of texts) {
+            if (!inVariant(text.variants))
+                continue;
             if (!visible(text.visibleProp))
                 continue;
             const [tx, ty] = backgroundPoint(text.anchor, plot);
             drawText(backgroundLabelText(text, props, translation), tx, ty, text.style, text.align, text.vertical === true);
         }
+        // The instance's own zone names, after the declared texts — the same order
+        // the audit reports them in, and the same reason: what the framework says
+        // comes first, what this element adds comes after.
+        //
+        // Deliberately NOT routed through `backgroundTexts` (see `labels.ts`): that
+        // walk is a function of the DECLARATION alone, and these names are a
+        // function of the MODEL. A zone name is therefore not in the declaration's
+        // hit-test walk, and the two cannot disagree. Under the BAND placement the
+        // framework's own view hit-tests `backgroundInstanceZoneBand` instead —
+        // the very rectangle painted below — so the words a user aims at and the
+        // words they get are one shape rather than two constants that must agree.
+        const zoneLabel = instanceZonesDef?.label;
+        if (zoneLabel) {
+            const labelBand = zoneLabel.band;
+            const dx = zoneLabel.dx ?? DEFAULT_INSTANCE_ZONE_LABEL_DX;
+            const dy = zoneLabel.dy ?? DEFAULT_INSTANCE_ZONE_LABEL_DY;
+            const stackY = instanceZonesDef?.stack === 'y';
+            for (const zone of instanceZones) {
+                // The strip is drawn for EVERY zone, named or not: it is the lane's
+                // title band, and a lane whose name has been cleared still has one —
+                // an empty band that reads as a lane waiting to be named, rather than
+                // a lane that silently loses its structure. The NAME is what is
+                // conditional, exactly as under the corner placement.
+                const strip = labelBand
+                    ? backgroundInstanceZoneBand(def, zone, plot)
+                    : null;
+                if (strip && labelBand?.divider) {
+                    const divider = labelBand.divider;
+                    ctx.strokeStyle = color(divider.color);
+                    ctx.lineWidth = divider.width;
+                    if (divider.dash?.length)
+                        ctx.setLineDash([...divider.dash]);
+                    // The far edge of the strip, along the zone: the near edge is the
+                    // plot boundary, already drawn by the frame or by the side band.
+                    if (stackY) {
+                        line(strip.x + strip.w, strip.y, strip.x + strip.w, strip.y + strip.h);
+                    }
+                    else {
+                        line(strip.x, strip.y + strip.h, strip.x + strip.w, strip.y + strip.h);
+                    }
+                    if (divider.dash?.length)
+                        ctx.setLineDash([]);
+                }
+                // An unnamed zone is a band and nothing else; it is not an empty label.
+                if (zone.name === undefined || zone.name === '')
+                    continue;
+                if (strip) {
+                    // Centred ACROSS the strip and ALONG it, the way the participant name
+                    // is centred in its own band one level up. `middle` regardless of
+                    // what the style says: the room the text is given is the width of the
+                    // strip, and a baseline anchor there would push the words against the
+                    // divider.
+                    const style = { ...zoneLabel.style, baseline: 'middle' };
+                    drawText(zone.name, strip.x + strip.w / 2, strip.y + strip.h / 2, style, 'center', stackY);
+                    continue;
+                }
+                drawText(zone.name, x0 + zone.rect.x * pw + dx, y0 + zone.rect.y * ph + dy, zoneLabel.style, 'left', false);
+            }
+        }
     };
 }
 /**

package/dist/_pkgs/affine-block-surface/renderer/overlay.js

@@ -1,6 +1,6 @@
 import { createIdentifier } from '../../global/di/index.js';
 import { BlockSuiteError, ErrorCode } from '../../global/exceptions/index.js';
-import { GfxControllerIdentifier, } from '../../std/gfx/index.js';
+import { GfxControllerIdentifier } from '../../std/gfx/index.js';
 import { Extension } from '../../store/index.js';
 /**
  * An overlay is a layer covered on top of elements,

package/dist/_pkgs/affine-block-surface-ref/portal/note.js

@@ -33,12 +33,12 @@ var __runInitializers = (this && this.__runInitializers) || function (thisArg, i
     return useValue ? value : void 0;
 };
 import { ViewExtensionManagerIdentifier } from '../../affine-ext-loader/index.js';
-import { DefaultTheme, NoteDisplayMode, NoteShadow, } from '../../affine-model/index.js';
+import { DefaultTheme, NoteDisplayMode, NoteShadow } from '../../affine-model/index.js';
 import { EDGELESS_BLOCK_CHILD_BORDER_WIDTH, EDGELESS_BLOCK_CHILD_PADDING, } from '../../affine-shared/consts/index.js';
 import { ThemeProvider } from '../../affine-shared/services/index.js';
 import { deserializeXYWH } from '../../global/gfx/index.js';
 import { WithDisposable } from '../../global/lit/index.js';
-import { BlockStdScope, ShadowlessElement, } from '../../std/index.js';
+import { BlockStdScope, ShadowlessElement } from '../../std/index.js';
 import { RANGE_QUERY_EXCLUDE_ATTR } from '../../std/inline/index.js';
 import {} from '../../store/index.js';
 import { css, nothing } from 'lit';

package/dist/_pkgs/affine-block-table/commands.js

@@ -1,4 +1,4 @@
-import { TableModelFlavour, } from '../affine-model/index.js';
+import { TableModelFlavour } from '../affine-model/index.js';
 import {} from '../store/index.js';
 import { TableDataManager } from './table-data-manager.js';
 export const insertTableBlockCommand = (ctx, next) => {

package/dist/_pkgs/affine-components/edgeless-shape-color-picker/color-picker.js

@@ -34,7 +34,7 @@ var __runInitializers = (this && this.__runInitializers) || function (thisArg, i
 };
 import { DefaultTheme, resolveColor, } from '../../affine-model/index.js';
 import { unsafeCSSVarV2 } from '../../affine-shared/theme/index.js';
-import { stopPropagation, } from '../../affine-shared/utils/index.js';
+import { stopPropagation } from '../../affine-shared/utils/index.js';
 import { SignalWatcher, WithDisposable } from '../../global/lit/index.js';
 import { batch, signal } from '@preact/signals-core';
 import { css, html, LitElement } from 'lit';

package/dist/_pkgs/affine-components/embed-card-modal/embed-card-edit-modal.js

@@ -36,7 +36,7 @@ import { EmbedLinkedDocModel, EmbedSyncedDocModel, isInternalEmbedModel, } from
 import { TelemetryProvider, } from '../../affine-shared/services/index.js';
 import { fontSMStyle, fontXSStyle } from '../../affine-shared/styles/index.js';
 import { unsafeCSSVarV2 } from '../../affine-shared/theme/index.js';
-import { listenClickAway, stopPropagation, } from '../../affine-shared/utils/index.js';
+import { listenClickAway, stopPropagation } from '../../affine-shared/utils/index.js';
 import { SignalWatcher, WithDisposable } from '../../global/lit/index.js';
 import { nextTick } from '../../global/utils/index.js';
 import { EditorLifeCycleExtension, } from '../../std/index.js';

package/dist/_pkgs/affine-components/filterable-list/styles.js

@@ -1,4 +1,4 @@
-import { panelBaseStyle, scrollbarStyle, } from '../../affine-shared/styles/index.js';
+import { panelBaseStyle, scrollbarStyle } from '../../affine-shared/styles/index.js';
 import { css } from 'lit';
 export const filterableListStyles = css `
   ${panelBaseStyle(':host')}

package/dist/_pkgs/affine-components/peek/peekable.js

@@ -1,7 +1,7 @@
 import { NoteBlockModel } from '../../affine-model/index.js';
 import { DocModeProvider } from '../../affine-shared/services/index.js';
 import { isInsideEdgelessEditor, matchModels, } from '../../affine-shared/utils/index.js';
-import { GfxBlockElementModel, GfxControllerIdentifier, } from '../../std/gfx/index.js';
+import { GfxBlockElementModel, GfxControllerIdentifier } from '../../std/gfx/index.js';
 import { PeekableController } from './controller.js';
 const symbol = Symbol('peekable');
 export const isPeekable = (e) => {