@formicoidea/labre-core 0.58.0 → 0.59.0

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

@@ -1,4 +1,10 @@
 import { NOTATION_NEUTRALS } from '../../affine-shared/headless.js';
+/**
+ * How many lines a `fit: 'wrap'` label takes when its declaration names no
+ * `maxLines`: enough for a sentence-long name, few enough that a pasted
+ * paragraph does not turn a title band into a column.
+ */
+export const DEFAULT_BACKGROUND_WRAP_MAX_LINES = 3;
 /**
  * The default card: a plain rectangle in the shared notation scale's card
  * fill, no border, no radius.
@@ -6,9 +12,17 @@ import { NOTATION_NEUTRALS } from '../../affine-shared/headless.js';
 export const DEFAULT_BACKGROUND_SURFACE = {
     fill: NOTATION_NEUTRALS.cardFill,
 };
-/** The plot rectangle of a background of size `w × h`, in element-local units. */
-export function backgroundPlot(def, w, h) {
-    const { margin } = def.geometry;
+/**
+ * The plot rectangle of a background of size `w × h`, in element-local units.
+ *
+ * `margin` defaults to the DECLARED one. The painted chrome — the renderer, the
+ * label hit boxes, a framework's own hit tests — passes the margin
+ * `backgroundBandWidths` resolved instead, which a wrapped band label may have
+ * grown. The semantic readers (facts, audit, rules, interchange exports) keep
+ * the declared plot: where an artefact sits in a frame is a question about the
+ * frame, and its answer must not change because somebody renamed it.
+ */
+export function backgroundPlot(def, w, h, margin = def.geometry.margin) {
     const x0 = margin.left;
     const y0 = margin.top;
     const x1 = w - margin.right;
@@ -151,16 +165,21 @@ export function backgroundInstanceZones(def, model) {
  * 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.
+ *
+ * `bandWidth` defaults to the DECLARED strip width; the painted chrome passes
+ * the one `backgroundBandWidths` resolved, which a wrapped name may have grown
+ * — and which is the same for every zone of the instance.
  */
-export function backgroundInstanceZoneBand(def, zone, plot) {
+export function backgroundInstanceZoneBand(def, zone, plot, bandWidth) {
     const spec = def.instanceZones;
     const band = spec?.label?.band;
     if (spec === undefined || band === undefined)
         return null;
-    if (!(band.width > 0))
+    const thickness = bandWidth ?? band.width;
+    if (!(thickness > 0))
         return null;
     if (spec.stack === 'y') {
-        const width = Math.min(band.width, plot.width);
+        const width = Math.min(thickness, plot.width);
         if (!(width > 0))
             return null;
         return {
@@ -170,7 +189,7 @@ export function backgroundInstanceZoneBand(def, zone, plot) {
             h: zone.rect.h * plot.height,
         };
     }
-    const height = Math.min(band.width, plot.height);
+    const height = Math.min(thickness, plot.height);
     if (!(height > 0))
         return null;
     return {

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

@@ -0,0 +1,58 @@
+/**
+ * Fitting a background label to the room it is given: cut it, or wrap it.
+ *
+ * A pool's participant name and its lane names are written ALONG a band — the
+ * participant band and the lane strip of the BPMN pool. A name longer than the
+ * band used to run past its end, across the frame and into the next lane,
+ * because the primitive drew every text with a single `fillText` and never
+ * measured it. Two answers live here, both opt-in per declaration:
+ *
+ * - `'ellipsis'` cuts the words to ONE line with "…" (PR #532);
+ * - `'wrap'` breaks them on words into several lines stacked ACROSS the band,
+ *   and the band grows to hold them (`band-widths.ts`), up to a declared
+ *   `maxLines`, past which the last line is cut with "…" all the same. The PO
+ *   asked for this one over the cut (2026-10-27): a band that thickens with its
+ *   name reads as a title, a cut name reads as a bug.
+ *
+ * Either way the STORED name stays whole (the rename editor shows it in full),
+ * and nothing is written to the document: the band's thickness is derived at
+ * paint time from what is painted.
+ *
+ * Measured on the context the label is painted on, with the font already set,
+ * so the fit matches what is drawn — on screen and in the SVG export, which
+ * paints through these same renderers with real text metrics. The text package
+ * has its own `truncateTextByWidth`, but `gfx/text` sits above this package and
+ * cannot be imported from it; this is the same idea, measured by the context.
+ */
+/** The mark a cut label ends with. */
+export declare const BACKGROUND_TEXT_ELLIPSIS = "\u2026";
+/**
+ * Model units kept clear at each end of the room a fitted label is given, so a
+ * cut name never touches the frame it is written against. A wrapped label keeps
+ * the same clearance on each side ACROSS its band.
+ */
+export declare const BACKGROUND_TEXT_FIT_PADDING = 4;
+/**
+ * `words` as drawn in at most `room` units of the context's current font: the
+ * text itself when it fits, otherwise its longest prefix that still fits once
+ * an ellipsis is appended, and nothing when even the ellipsis is too wide.
+ *
+ * Cut on code points, not UTF-16 units, so an emoji in a lane name is never
+ * split into a lone surrogate.
+ */
+export declare function ellipsizeToWidth(ctx: Pick<CanvasRenderingContext2D, 'measureText'>, words: string, room: number): string;
+/**
+ * `words` broken on whitespace into at most `maxLines` lines of at most `room`
+ * units each, in the context's current font.
+ *
+ * Greedy, which is what every text renderer in the product does: a word goes
+ * on the current line while the line still fits. A single word wider than the
+ * room keeps a line of its own and is cut with "…" — a lane named by one long
+ * identifier still shows its start rather than nothing. When the words do not
+ * fit in `maxLines`, the last line takes everything left over and is cut, so
+ * the "…" says there is more, exactly as the one-line cut always did.
+ *
+ * Empty for empty or blank words and for a room with no width: there is
+ * nothing to draw, and no line to make a band thicker for.
+ */
+export declare function wrapToWidth(ctx: Pick<CanvasRenderingContext2D, 'measureText'>, words: string, room: number, maxLines: number): string[];

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

@@ -0,0 +1,110 @@
+/**
+ * Fitting a background label to the room it is given: cut it, or wrap it.
+ *
+ * A pool's participant name and its lane names are written ALONG a band — the
+ * participant band and the lane strip of the BPMN pool. A name longer than the
+ * band used to run past its end, across the frame and into the next lane,
+ * because the primitive drew every text with a single `fillText` and never
+ * measured it. Two answers live here, both opt-in per declaration:
+ *
+ * - `'ellipsis'` cuts the words to ONE line with "…" (PR #532);
+ * - `'wrap'` breaks them on words into several lines stacked ACROSS the band,
+ *   and the band grows to hold them (`band-widths.ts`), up to a declared
+ *   `maxLines`, past which the last line is cut with "…" all the same. The PO
+ *   asked for this one over the cut (2026-10-27): a band that thickens with its
+ *   name reads as a title, a cut name reads as a bug.
+ *
+ * Either way the STORED name stays whole (the rename editor shows it in full),
+ * and nothing is written to the document: the band's thickness is derived at
+ * paint time from what is painted.
+ *
+ * Measured on the context the label is painted on, with the font already set,
+ * so the fit matches what is drawn — on screen and in the SVG export, which
+ * paints through these same renderers with real text metrics. The text package
+ * has its own `truncateTextByWidth`, but `gfx/text` sits above this package and
+ * cannot be imported from it; this is the same idea, measured by the context.
+ */
+/** The mark a cut label ends with. */
+export const BACKGROUND_TEXT_ELLIPSIS = '…';
+/**
+ * Model units kept clear at each end of the room a fitted label is given, so a
+ * cut name never touches the frame it is written against. A wrapped label keeps
+ * the same clearance on each side ACROSS its band.
+ */
+export const BACKGROUND_TEXT_FIT_PADDING = 4;
+/**
+ * `words` as drawn in at most `room` units of the context's current font: the
+ * text itself when it fits, otherwise its longest prefix that still fits once
+ * an ellipsis is appended, and nothing when even the ellipsis is too wide.
+ *
+ * Cut on code points, not UTF-16 units, so an emoji in a lane name is never
+ * split into a lone surrogate.
+ */
+export function ellipsizeToWidth(ctx, words, room) {
+    if (!words)
+        return words;
+    if (!(room > 0))
+        return '';
+    if (ctx.measureText(words).width <= room)
+        return words;
+    if (ctx.measureText(BACKGROUND_TEXT_ELLIPSIS).width > room)
+        return '';
+    const chars = Array.from(words);
+    // Binary search on the prefix length: the widest prefix whose ellipsized
+    // form still fits. Width grows with the prefix, so the predicate is monotone.
+    let lo = 0;
+    let hi = chars.length - 1;
+    while (lo < hi) {
+        const mid = Math.ceil((lo + hi) / 2);
+        const candidate = chars.slice(0, mid).join('') + BACKGROUND_TEXT_ELLIPSIS;
+        if (ctx.measureText(candidate).width <= room)
+            lo = mid;
+        else
+            hi = mid - 1;
+    }
+    return chars.slice(0, lo).join('').trimEnd() + BACKGROUND_TEXT_ELLIPSIS;
+}
+/**
+ * `words` broken on whitespace into at most `maxLines` lines of at most `room`
+ * units each, in the context's current font.
+ *
+ * Greedy, which is what every text renderer in the product does: a word goes
+ * on the current line while the line still fits. A single word wider than the
+ * room keeps a line of its own and is cut with "…" — a lane named by one long
+ * identifier still shows its start rather than nothing. When the words do not
+ * fit in `maxLines`, the last line takes everything left over and is cut, so
+ * the "…" says there is more, exactly as the one-line cut always did.
+ *
+ * Empty for empty or blank words and for a room with no width: there is
+ * nothing to draw, and no line to make a band thicker for.
+ */
+export function wrapToWidth(ctx, words, room, maxLines) {
+    if (!(room > 0))
+        return [];
+    const tokens = words.split(/\s+/).filter(Boolean);
+    if (tokens.length === 0)
+        return [];
+    const limit = Math.max(1, Math.floor(maxLines));
+    const lines = [];
+    let current = '';
+    let i = 0;
+    for (; i < tokens.length; i++) {
+        const candidate = current ? `${current} ${tokens[i]}` : tokens[i];
+        if (!current || ctx.measureText(candidate).width <= room) {
+            current = candidate;
+            continue;
+        }
+        if (lines.length === limit - 1)
+            break;
+        lines.push(current);
+        current = tokens[i];
+    }
+    // Out of lines with words still waiting: the last line carries them all, and
+    // the cut below ends it with "…".
+    if (i < tokens.length)
+        current = [current, ...tokens.slice(i)].join(' ');
+    lines.push(current);
+    return lines
+        .map(line => ellipsizeToWidth(ctx, line, room))
+        .filter(line => line !== '');
+}

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

@@ -1,8 +1,11 @@
 export * from './background-view.js';
+export * from './band-widths.js';
 export * from './def.js';
+export * from './ellipsis.js';
 export * from './facts.js';
 export * from './fit.js';
 export * from './interaction.js';
 export * from './labels.js';
+export * from './measure-text.js';
 export * from './renderer.js';
 export * from './stacking.js';

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

@@ -1,8 +1,11 @@
 export * from './background-view.js';
+export * from './band-widths.js';
 export * from './def.js';
+export * from './ellipsis.js';
 export * from './facts.js';
 export * from './fit.js';
 export * from './interaction.js';
 export * from './labels.js';
+export * from './measure-text.js';
 export * from './renderer.js';
 export * from './stacking.js';

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

@@ -1,5 +1,6 @@
 import type { TranslationService } from '../../affine-shared/services/index.js';
 import type { BackgroundLabelSource, BackgroundTextDef, FrameworkBackgroundDef } from './def.js';
+import { type BackgroundTextMeasure } from './band-widths.js';
 /** A background element, seen from the primitive: a bag of declared props. */
 export type BackgroundModelLike = Record<string, unknown>;
 /**
@@ -107,8 +108,17 @@ export declare function backgroundTexts(def: FrameworkBackgroundDef): Background
  * not user text, and is not offered for editing.
  *
  * Positions come from the same declaration the renderer paints from, so the
- * boxes track the drawn text by construction.
+ * boxes track the drawn text by construction — including a band grown by a
+ * wrapped label, read off the same resolver (`backgroundBandWidths`, measured
+ * here without a painting context), with one box round all of its lines.
  */
-export declare function backgroundLabelHits(def: FrameworkBackgroundDef, model: BackgroundModelLike, w: number, h: number, translation?: TranslationService | null): BackgroundLabelHit[];
+export declare function backgroundLabelHits(def: FrameworkBackgroundDef, model: BackgroundModelLike, w: number, h: number, translation?: TranslationService | null, 
+/**
+ * How a wrapped band label is measured to size its band. The estimate by
+ * default, since this function is reachable from the headless `./interchange`
+ * entry; a view passes `measureBackgroundText` so its boxes sit on the band
+ * as painted.
+ */
+measure?: BackgroundTextMeasure): BackgroundLabelHit[];
 /** First label whose padded box contains the element-local point, or null. */
 export declare function hitTestBackgroundLabel(hits: readonly BackgroundLabelHit[], lx: number, ly: number): BackgroundLabelHit | null;

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

@@ -1,3 +1,4 @@
+import { backgroundBandWidths, backgroundWrapLineHeight, estimateBackgroundText, } from './band-widths.js';
 import { backgroundPlot, backgroundPoint } from './def.js';
 /**
  * Complain once per distinct problem.
@@ -166,10 +167,20 @@ export function backgroundTexts(def) {
  * not user text, and is not offered for editing.
  *
  * Positions come from the same declaration the renderer paints from, so the
- * boxes track the drawn text by construction.
+ * boxes track the drawn text by construction — including a band grown by a
+ * wrapped label, read off the same resolver (`backgroundBandWidths`, measured
+ * here without a painting context), with one box round all of its lines.
  */
-export function backgroundLabelHits(def, model, w, h, translation) {
-    const plot = backgroundPlot(def, w, h);
+export function backgroundLabelHits(def, model, w, h, translation, 
+/**
+ * How a wrapped band label is measured to size its band. The estimate by
+ * default, since this function is reachable from the headless `./interchange`
+ * entry; a view passes `measureBackgroundText` so its boxes sit on the band
+ * as painted.
+ */
+measure = estimateBackgroundText) {
+    const layout = backgroundBandWidths(def, model, w, h, measure, translation);
+    const plot = backgroundPlot(def, w, h, layout.margin);
     const hits = [];
     for (const text of backgroundTexts(def)) {
         if (text.prop === undefined)
@@ -182,12 +193,25 @@ export function backgroundLabelHits(def, model, w, h, translation) {
         if (!backgroundVisible(text.visibleProp, model))
             continue;
         const words = backgroundLabelText(text, model, translation);
-        const [ax, ay] = backgroundPoint(text.anchor, plot);
+        const [px, py] = backgroundPoint(text.anchor, plot);
+        const wrap = layout.labels.get(text);
+        const ax = px + (wrap?.shift[0] ?? 0);
+        const ay = py + (wrap?.shift[1] ?? 0);
+        const lines = wrap && wrap.lines.length > 1 ? wrap.lines : [words];
+        const lineHeight = backgroundWrapLineHeight(text.style);
+        const boxes = lines.map((line, i) => {
+            // The renderer's own stacking: centred on the anchor, across the text.
+            const across = (i - (lines.length - 1) / 2) * lineHeight;
+            return backgroundTextHitBox(line, text.style.size, text.vertical ? ax + across : ax, text.vertical ? ay : ay + across, text.align, text.vertical);
+        });
         hits.push({
             id: text.id,
             prop: text.prop,
             text: words,
-            ...backgroundTextHitBox(words, text.style.size, ax, ay, text.align, text.vertical),
+            minX: Math.min(...boxes.map(box => box.minX)),
+            minY: Math.min(...boxes.map(box => box.minY)),
+            maxX: Math.max(...boxes.map(box => box.maxX)),
+            maxY: Math.max(...boxes.map(box => box.maxY)),
         });
     }
     return hits;

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

@@ -0,0 +1,14 @@
+/**
+ * Measure background text with no painting context at hand — a hit test runs on
+ * a pointer event, not inside a paint — for `backgroundBandWidths`.
+ *
+ * A module-level offscreen 2D context where a document exists, so a hit box is
+ * measured with the same metrics the canvas paints with, and a band a long name
+ * widened is aimed at where it is drawn; the estimate where there is no
+ * document, or where the DOM is a test double that cannot measure.
+ *
+ * In a file of its own, out of the `./interchange` graph: `band-widths.ts` is
+ * reachable from that headless entry and must not touch the DOM
+ * (`interchange-headless.unit.spec.ts` in `affine/all`).
+ */
+export declare function measureBackgroundText(text: string, font: string): number;

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

@@ -0,0 +1,31 @@
+import { estimateBackgroundText } from './band-widths.js';
+/** `undefined` until first asked; `null` where there is no canvas to ask. */
+let offscreen;
+/**
+ * Measure background text with no painting context at hand — a hit test runs on
+ * a pointer event, not inside a paint — for `backgroundBandWidths`.
+ *
+ * A module-level offscreen 2D context where a document exists, so a hit box is
+ * measured with the same metrics the canvas paints with, and a band a long name
+ * widened is aimed at where it is drawn; the estimate where there is no
+ * document, or where the DOM is a test double that cannot measure.
+ *
+ * In a file of its own, out of the `./interchange` graph: `band-widths.ts` is
+ * reachable from that headless entry and must not touch the DOM
+ * (`interchange-headless.unit.spec.ts` in `affine/all`).
+ */
+export function measureBackgroundText(text, font) {
+    if (offscreen === undefined) {
+        offscreen =
+            typeof document === 'undefined'
+                ? null
+                : (document.createElement('canvas').getContext?.('2d') ?? null);
+    }
+    if (offscreen) {
+        offscreen.font = font;
+        const width = offscreen.measureText(text)?.width;
+        if (typeof width === 'number' && Number.isFinite(width))
+            return width;
+    }
+    return estimateBackgroundText(text, font);
+}

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

@@ -1,8 +1,21 @@
 import type { GfxPrimitiveElementModel } from '../../std/gfx/index.js';
 import type { ElementRenderer } from '../renderer/elements/index.js';
 import type { FrameworkBackgroundDef } from './def.js';
+import { type BackgroundBandLayout } from './band-widths.js';
+/** What a framework may ask of the renderer beyond the declaration. */
+export interface FrameworkBackgroundRendererOptions<T> {
+    /**
+     * Called on every paint with the band widths that paint measured
+     * (`backgroundBandWidths`), before anything is drawn. Named consumer: the
+     * BPMN pool, which caches them on its model (`paintedBands`, a `@local()`
+     * field, never stored) so that picking — which asks the headless model —
+     * selects by the bands as painted. A consumer that writes must write only
+     * when the widths changed: a local write repaints.
+     */
+    onBands?: (model: T, layout: BackgroundBandLayout) => void;
+}
 /**
  * Build the canvas renderer of one declaration. Pure: the same declaration
  * always paints the same picture for the same model and size.
  */
-export declare function createFrameworkBackgroundRenderer<T extends GfxPrimitiveElementModel>(def: FrameworkBackgroundDef): ElementRenderer<T>;
+export declare function createFrameworkBackgroundRenderer<T extends GfxPrimitiveElementModel>(def: FrameworkBackgroundDef, options?: FrameworkBackgroundRendererOptions<T>): ElementRenderer<T>;

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

@@ -1,6 +1,8 @@
 import { TranslationProvider } from '../../affine-shared/services/index.js';
 import { notationColor, } from '../renderer/notation-tint.js';
 import { backgroundColor, backgroundInstanceZoneBand, backgroundInstanceZones, backgroundPlot, backgroundPoint, BROKEN_BACKGROUND_COLOR, DEFAULT_BACKGROUND_SURFACE, warnBrokenBackgroundColor, } from './def.js';
+import { backgroundBandWidths, backgroundFont, backgroundTextRoom, backgroundWrapLineHeight, DEFAULT_BACKGROUND_FONT_FAMILY, } from './band-widths.js';
+import { BACKGROUND_TEXT_FIT_PADDING, ellipsizeToWidth } from './ellipsis.js';
 import { backgroundInVariant, backgroundLabelText, backgroundTexts, backgroundVisible, } from './labels.js';
 /**
  * The framework-background PRIMITIVE (PF2.1): one renderer, driven entirely by
@@ -79,13 +81,6 @@ function rgba(hex, alpha) {
     const b = parseInt(hex.slice(5, 7), 16);
     return `rgba(${r},${g},${b},${alpha})`;
 }
-function fontOf(style, fallbackFamily) {
-    const italic = style.italic ? 'italic ' : '';
-    const weight = style.weight ? `${style.weight} ` : '';
-    return `${italic}${weight}${style.size}px ${style.family ?? 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
@@ -103,9 +98,9 @@ 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.
  */
-export function createFrameworkBackgroundRenderer(def) {
+export function createFrameworkBackgroundRenderer(def, options = {}) {
     const palette = def.chrome?.palette;
-    const family = def.chrome?.fontFamily ?? DEFAULT_FONT_FAMILY;
+    const family = def.chrome?.fontFamily ?? DEFAULT_BACKGROUND_FONT_FAMILY;
     const surface = def.chrome?.surface ?? DEFAULT_BACKGROUND_SURFACE;
     const declared = (c) => backgroundColor(c, palette);
     const texts = backgroundTexts(def);
@@ -140,7 +135,16 @@ export function createFrameworkBackgroundRenderer(def) {
             .translateSelf(cx, cy)
             .rotateSelf(model.rotate)
             .translateSelf(-cx, -cy));
-        const plot = backgroundPlot(def, w, h);
+        // The bands as thick as their wrapped labels need, measured on this very
+        // context so the band holds exactly the lines painted in it. Every piece of
+        // chrome below paints from this plot; a declaration that wraps nothing gets
+        // its declared margin back without a measurement.
+        const layout = backgroundBandWidths(def, props, w, h, (text, font) => {
+            ctx.font = font;
+            return ctx.measureText(text).width;
+        }, translation);
+        options.onBands?.(model, layout);
+        const plot = backgroundPlot(def, w, h, layout.margin);
         const { x0, y0, x1, y1 } = plot;
         const pw = plot.width;
         const ph = plot.height;
@@ -150,26 +154,60 @@ export function createFrameworkBackgroundRenderer(def) {
             ctx.lineTo(bx, by);
             ctx.stroke();
         };
-        const drawText = (words, ax, ay, style, align, vertical) => {
+        const drawText = (words, ax, ay, style, align, vertical, 
+        /**
+         * The length the words may take, in model units; absent draws them
+         * whole. Measured AFTER the font is set, so the cut is in the font the
+         * words are drawn in.
+         */
+        room, 
+        /**
+         * The lines a wrapped label was broken into by `backgroundBandWidths`,
+         * drawn instead of `words`: stacked ACROSS the text's direction and
+         * centred on the anchor, one line height apart. Taken from the resolver
+         * rather than wrapped again here, so the band and its lines are one
+         * measurement.
+         */
+        wrapped) => {
             if (!words)
                 return;
-            if (vertical) {
-                ctx.save();
-                ctx.translate(ax, ay);
-                ctx.rotate(-Math.PI / 2);
-                ctx.font = fontOf(style, family);
+            const font = backgroundFont(style, family);
+            let shown;
+            if (wrapped)
+                shown = wrapped;
+            else if (room === undefined)
+                shown = [words];
+            else {
+                ctx.font = font;
+                shown = [ellipsizeToWidth(ctx, words, room)];
+            }
+            const lineHeight = backgroundWrapLineHeight(style);
+            shown.forEach((text, i) => {
+                if (!text)
+                    return;
+                // Zero for a single line, which is drawn exactly where it always was.
+                const across = (i - (shown.length - 1) / 2) * lineHeight;
+                if (vertical) {
+                    // Rotated -90°, the next line is to the RIGHT of the one before:
+                    // the glyphs' tops point left, so a reader turning their head reads
+                    // the lines left to right.
+                    ctx.save();
+                    ctx.translate(ax + across, ay);
+                    ctx.rotate(-Math.PI / 2);
+                    ctx.font = font;
+                    ctx.fillStyle = color(style.color);
+                    ctx.textAlign = align ?? 'center';
+                    ctx.textBaseline = style.baseline ?? 'alphabetic';
+                    ctx.fillText(text, 0, 0);
+                    ctx.restore();
+                    return;
+                }
+                ctx.font = font;
                 ctx.fillStyle = color(style.color);
-                ctx.textAlign = align ?? 'center';
+                ctx.textAlign = align ?? 'left';
                 ctx.textBaseline = style.baseline ?? 'alphabetic';
-                ctx.fillText(words, 0, 0);
-                ctx.restore();
-                return;
-            }
-            ctx.font = fontOf(style, family);
-            ctx.fillStyle = color(style.color);
-            ctx.textAlign = align ?? 'left';
-            ctx.textBaseline = style.baseline ?? 'alphabetic';
-            ctx.fillText(words, ax, ay);
+                ctx.fillText(text, ax, ay + across);
+            });
         };
         // ── 1. The card, and the bands that dress it ────────────────────────
         const border = surface.border;
@@ -330,8 +368,18 @@ export function createFrameworkBackgroundRenderer(def) {
                 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);
+            const [px, py] = backgroundPoint(text.anchor, plot);
+            // A wrapped band label keeps its place relative to the middle of its
+            // band, however much the band grew (`BackgroundWrappedLabel.shift`).
+            const wrap = layout.labels.get(text);
+            const tx = px + (wrap?.shift[0] ?? 0);
+            const ty = py + (wrap?.shift[1] ?? 0);
+            const vertical = text.vertical === true;
+            drawText(backgroundLabelText(text, props, translation), tx, ty, text.style, text.align, vertical, 
+            // `'wrap'` on a text with no band to grow is cut like `'ellipsis'`.
+            text.fit !== undefined
+                ? backgroundTextRoom(tx, ty, text.align, vertical, w, h)
+                : undefined, wrap?.lines);
         }
         // 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
@@ -350,6 +398,7 @@ export function createFrameworkBackgroundRenderer(def) {
             const dx = zoneLabel.dx ?? DEFAULT_INSTANCE_ZONE_LABEL_DX;
             const dy = zoneLabel.dy ?? DEFAULT_INSTANCE_ZONE_LABEL_DY;
             const stackY = instanceZonesDef?.stack === 'y';
+            const fitZone = zoneLabel.fit !== undefined;
             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 —
@@ -357,7 +406,7 @@ export function createFrameworkBackgroundRenderer(def) {
                 // 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)
+                    ? backgroundInstanceZoneBand(def, zone, plot, layout.zoneBandWidth)
                     : null;
                 if (strip && labelBand?.divider) {
                     const divider = labelBand.divider;
@@ -386,10 +435,14 @@ export function createFrameworkBackgroundRenderer(def) {
                     // 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);
+                    drawText(zone.name, strip.x + strip.w / 2, strip.y + strip.h / 2, style, 'center', stackY, fitZone
+                        ? (stackY ? strip.h : strip.w) - 2 * BACKGROUND_TEXT_FIT_PADDING
+                        : undefined, layout.zoneLines.get(zone.id));
                     continue;
                 }
-                drawText(zone.name, x0 + zone.rect.x * pw + dx, y0 + zone.rect.y * ph + dy, zoneLabel.style, 'left', false);
+                drawText(zone.name, x0 + zone.rect.x * pw + dx, y0 + zone.rect.y * ph + dy, zoneLabel.style, 'left', false, fitZone
+                    ? zone.rect.w * pw - dx - BACKGROUND_TEXT_FIT_PADDING
+                    : undefined);
             }
         }
     };