@formicoidea/labre-core 0.58.0 → 0.60.0

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

@@ -0,0 +1,156 @@
+import { backgroundInstanceZones, backgroundPlot, backgroundPoint, DEFAULT_BACKGROUND_WRAP_MAX_LINES, } from './def.js';
+import { BACKGROUND_TEXT_FIT_PADDING, wrapToWidth } from './ellipsis.js';
+import { backgroundInVariant, backgroundLabelText, backgroundVisible, } from './labels.js';
+/**
+ * The line height of a wrapped label, as a multiple of its font size: the CSS
+ * `normal` line height. Not the 1.25 the slides use — at 1.25 a single 13-unit
+ * lane name would need 24.25 units and widen the BPMN pool's 24-unit lane strip
+ * by a quarter unit for a name that fits it; a band only grows for a SECOND
+ * line.
+ */
+export const BACKGROUND_WRAP_LINE_HEIGHT = 1.2;
+/** The family a declaration that names none falls back to. */
+export const DEFAULT_BACKGROUND_FONT_FAMILY = 'Inter, sans-serif';
+/** The CSS font a background text is drawn in. */
+export function backgroundFont(style, fallbackFamily = DEFAULT_BACKGROUND_FONT_FAMILY) {
+    const italic = style.italic ? 'italic ' : '';
+    const weight = style.weight ? `${style.weight} ` : '';
+    return `${italic}${weight}${style.size}px ${style.family ?? fallbackFamily}`;
+}
+/** Distance between two wrapped lines of this style, in model units. */
+export function backgroundWrapLineHeight(style) {
+    return style.size * BACKGROUND_WRAP_LINE_HEIGHT;
+}
+/**
+ * The room a fitted declared text has: from its anchor to the card's edges
+ * along the direction it reads, on the side(s) its alignment grows towards,
+ * less {@link BACKGROUND_TEXT_FIT_PADDING} at each end. A vertical text reads
+ * bottom-to-top, so `left` grows UP from its anchor.
+ */
+export function backgroundTextRoom(ax, ay, align, vertical, w, h) {
+    const pad = BACKGROUND_TEXT_FIT_PADDING;
+    if (vertical) {
+        const up = ay - pad;
+        const down = h - ay - pad;
+        const side = align ?? 'center';
+        if (side === 'left')
+            return up;
+        if (side === 'right')
+            return down;
+        return 2 * Math.min(up, down);
+    }
+    const leftward = ax - pad;
+    const rightward = w - ax - pad;
+    const side = align ?? 'left';
+    if (side === 'left')
+        return rightward;
+    if (side === 'right')
+        return leftward;
+    return 2 * Math.min(leftward, rightward);
+}
+/** Rough advance per code point, as a fraction of the font size. */
+const ESTIMATED_ADVANCE = 0.55;
+/**
+ * A rough width with no canvas at all: 0.55 × the font size per code point, the
+ * ratio `svg-sketch.ts` estimates with. The default of every headless caller
+ * (this file is reachable from the `./interchange` entry, which loads no DOM);
+ * a caller with a document passes `measureBackgroundText` (`measure-text.ts`),
+ * which measures with the canvas's own metrics.
+ */
+export function estimateBackgroundText(text, font) {
+    const size = Number(/(\d+(?:\.\d+)?)px/.exec(font)?.[1]) || 12;
+    return Array.from(text).length * size * ESTIMATED_ADVANCE;
+}
+const NO_LABELS = new Map();
+const NO_ZONE_LINES = new Map();
+/**
+ * THE resolver of band thickness. Pure in its inputs: the declaration, the
+ * instance's props, its size, and how to measure text — the renderer passes its
+ * context, a hit test outside a paint `measureBackgroundText` (the same metrics
+ * from an offscreen canvas), and a caller with no DOM gets the estimate.
+ *
+ * - a SIDE band whose label wraps is `max(declared margin, lines × line height
+ *   + 2 × padding)` thick, the lines broken over the room the label has along
+ *   the band (`backgroundTextRoom`, from its anchor in the declared plot);
+ * - every INSTANCE-ZONE strip is one thickness: the declared width, or the
+ *   most any zone's wrapped name needs, each name broken over its own zone's
+ *   length less the padding. A lane with a long name widens every lane's strip,
+ *   so the leading edges stay aligned.
+ *
+ * A declaration with no `'wrap'` anywhere gets its declared numbers back
+ * without a single measurement, so the frameworks that never asked for this
+ * pay nothing for it.
+ *
+ * ponytail: a text's room is measured against the DECLARED plot, so a
+ * declaration wrapping both a left and a top band would size each without the
+ * other's growth. Nothing declares two; upgrade by resolving the sides in turn
+ * against the plot resolved so far, the day one does.
+ */
+export function backgroundBandWidths(def, model, w, h, measure = estimateBackgroundText, translation) {
+    const declared = def.geometry.margin;
+    const zoneLabel = def.instanceZones?.label;
+    const wrapsBand = (def.chrome?.sideBands ?? []).some(band => band.label?.fit === 'wrap');
+    const wrapsZones = zoneLabel?.band !== undefined && zoneLabel.fit === 'wrap';
+    if (!wrapsBand && !wrapsZones) {
+        return {
+            margin: declared,
+            zoneBandWidth: zoneLabel?.band?.width,
+            labels: NO_LABELS,
+            zoneLines: NO_ZONE_LINES,
+        };
+    }
+    const family = def.chrome?.fontFamily ?? DEFAULT_BACKGROUND_FONT_FAMILY;
+    const pad = BACKGROUND_TEXT_FIT_PADDING;
+    const measurer = (font) => ({
+        measureText: (text) => ({ width: measure(text, font) }),
+    });
+    const thicknessFor = (lines, style) => lines > 0 ? lines * backgroundWrapLineHeight(style) + 2 * pad : 0;
+    const margin = { ...declared };
+    const wrapped = [];
+    const lines = new Map();
+    if (wrapsBand) {
+        const plot = backgroundPlot(def, w, h);
+        for (const band of def.chrome?.sideBands ?? []) {
+            const label = band.label;
+            if (label?.fit !== 'wrap')
+                continue;
+            // A label the instance does not paint holds nothing open.
+            if (!backgroundInVariant(def, label.variants, model))
+                continue;
+            if (!backgroundVisible(label.visibleProp, model))
+                continue;
+            const vertical = label.vertical === true;
+            const [ax, ay] = backgroundPoint(label.anchor, plot);
+            const shown = wrapToWidth(measurer(backgroundFont(label.style, family)), backgroundLabelText(label, model, translation), backgroundTextRoom(ax, ay, label.align, vertical, w, h), label.maxLines ?? DEFAULT_BACKGROUND_WRAP_MAX_LINES);
+            lines.set(label, shown);
+            wrapped.push({ label, side: band.side });
+            margin[band.side] = Math.max(margin[band.side], thicknessFor(shown.length, label.style));
+        }
+    }
+    const labels = new Map();
+    for (const { label, side } of wrapped) {
+        const back = (declared[side] - margin[side]) / 2;
+        labels.set(label, {
+            lines: lines.get(label) ?? [],
+            shift: side === 'left' ? [back, 0] : [0, back],
+        });
+    }
+    let zoneBandWidth = zoneLabel?.band?.width;
+    const zoneLines = new Map();
+    if (wrapsZones && zoneLabel && zoneBandWidth !== undefined) {
+        const plot = backgroundPlot(def, w, h, margin);
+        const stackY = def.instanceZones?.stack === 'y';
+        const ctx = measurer(backgroundFont(zoneLabel.style, family));
+        for (const zone of backgroundInstanceZones(def, model)) {
+            if (zone.name === undefined || zone.name === '')
+                continue;
+            const length = stackY
+                ? zone.rect.h * plot.height
+                : zone.rect.w * plot.width;
+            const shown = wrapToWidth(ctx, zone.name, length - 2 * pad, zoneLabel.maxLines ?? DEFAULT_BACKGROUND_WRAP_MAX_LINES);
+            zoneLines.set(zone.id, shown);
+            zoneBandWidth = Math.max(zoneBandWidth, thicknessFor(shown.length, zoneLabel.style));
+        }
+    }
+    return { margin, zoneBandWidth, labels, zoneLines };
+}

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

@@ -122,7 +122,41 @@ export interface BackgroundTextDef extends BackgroundLabelSource {
     vertical?: boolean;
     /** Model prop gating this text. Absent means always drawn. */
     visibleProp?: string;
+    /**
+     * What happens to words longer than the room they are written in.
+     *
+     * Absent — what every declaration written before this existed says — draws
+     * the words whole, however far they run. `'ellipsis'` cuts them to the room
+     * between the anchor and the card's edges along the text's direction, minus
+     * a small padding, ending with "…" (`ellipsis.ts`). Opt-in, because the
+     * frameworks that do not ask for it have exact-drawing tests and labels that
+     * are meant to overhang.
+     *
+     * `'wrap'` breaks the words into lines over the same room and stacks them
+     * ACROSS the text's direction, at most {@link maxLines}, the last one cut
+     * with "…" if the words still do not fit. It is honoured on a SIDE BAND's
+     * label ({@link BackgroundSideBandDef}), whose band then grows to hold the
+     * lines (`backgroundBandWidths`); any other text has no band to grow and
+     * treats `'wrap'` as `'ellipsis'`. Named consumer: the BPMN participant name,
+     * written up its band, which thickens as the name needs more lines (PO,
+     * 2026-10-27) rather than cutting it as PR #532 did.
+     *
+     * Append-only, like every enum-like value a declaration states.
+     */
+    fit?: 'ellipsis' | 'wrap';
+    /**
+     * Under `fit: 'wrap'`, the most lines the words may take before the last one
+     * is cut with "…". Defaults to {@link DEFAULT_BACKGROUND_WRAP_MAX_LINES}.
+     * Ignored by every other fit.
+     */
+    maxLines?: number;
 }
+/**
+ * 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 declare const DEFAULT_BACKGROUND_WRAP_MAX_LINES = 3;
 /** One graduation on an axis. */
 export interface BackgroundTickDef {
     /** Position along the axis, as a ratio of the plot span it runs on. */
@@ -261,7 +295,10 @@ export interface BackgroundInstanceZoneItem {
  * wrong.
  */
 export interface BackgroundInstanceZoneBandDef {
-    /** Strip thickness in FIXED model units — across the stacking direction. */
+    /**
+     * Strip thickness in FIXED model units — across the stacking direction. The
+     * MINIMUM thickness under a `fit: 'wrap'` label, which may grow it.
+     */
     width: number;
     /** The line between the strip and the rest of the zone. Absent means none. */
     divider?: BackgroundStroke;
@@ -329,6 +366,28 @@ export interface BackgroundInstanceZonesDef {
         dy?: number;
         /** Present = band placement. */
         band?: BackgroundInstanceZoneBandDef;
+        /**
+         * `'ellipsis'` cuts a name longer than its room — the strip's length under
+         * a band, the zone's width from the inset under the corner — and ends it
+         * with "…", as {@link BackgroundTextDef.fit} does. Absent draws the name
+         * whole.
+         *
+         * `'wrap'` breaks a name into lines stacked across the strip, at most
+         * {@link maxLines}, and every strip of the instance grows to the SAME
+         * thickness: the one its most demanding name needs, never less than
+         * {@link BackgroundInstanceZoneBandDef.width} (`backgroundBandWidths`). One
+         * thickness, because strips of different widths would stagger the lanes'
+         * leading edges and read as lanes nested at different depths. Band
+         * placement only: the corner placement has no strip to grow and treats
+         * `'wrap'` as `'ellipsis'`. Named consumer: the BPMN lane title (PO,
+         * 2026-10-27).
+         */
+        fit?: 'ellipsis' | 'wrap';
+        /**
+         * Under `fit: 'wrap'`, the most lines a name may take. Defaults to
+         * {@link DEFAULT_BACKGROUND_WRAP_MAX_LINES}.
+         */
+        maxLines?: number;
     };
     /**
      * Prefix of the reported zone ids: `'lane'` reports `lane:sales`.
@@ -390,6 +449,17 @@ export interface BackgroundSurfaceDef {
  * and one day will not. An element smaller than its own margin clamps the band
  * to the element, which is the only case where the two can disagree.
  *
+ * ## A band that grows with its label
+ *
+ * Under a `fit: 'wrap'` label the declared margin is the MINIMUM thickness:
+ * the band grows to `lines × line height + 2 × padding` when the words need
+ * more lines than it holds, and the plot gives up the extra room with it.
+ * Derived at paint time from the measured words, never stored — the one
+ * resolver is `backgroundBandWidths`, and the renderer, the label hit boxes
+ * and a framework's own hit tests all read the margin it returns. The label
+ * keeps its offset from the MIDDLE of the band, so a label centred in the
+ * declared band stays centred in the grown one.
+ *
  * 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
@@ -499,8 +569,17 @@ export interface FrameworkBackgroundDef {
  * fill, no border, no radius.
  */
 export declare const DEFAULT_BACKGROUND_SURFACE: BackgroundSurfaceDef;
-/** The plot rectangle of a background of size `w × h`, in element-local units. */
-export declare function backgroundPlot(def: FrameworkBackgroundDef, w: number, h: number): {
+/**
+ * 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 declare function backgroundPlot(def: FrameworkBackgroundDef, w: number, h: number, margin?: BackgroundInset): {
     x0: number;
     y0: number;
     x1: number;
@@ -592,8 +671,12 @@ export interface BackgroundRect {
  * 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 declare function backgroundInstanceZoneBand(def: FrameworkBackgroundDef, zone: BackgroundInstanceZone, plot: ReturnType<typeof backgroundPlot>): BackgroundRect | null;
+export declare function backgroundInstanceZoneBand(def: FrameworkBackgroundDef, zone: BackgroundInstanceZone, plot: ReturnType<typeof backgroundPlot>, bandWidth?: number): BackgroundRect | null;
 /**
  * Whether the resize handles are offered for this element.
  *

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;