@formicoidea/labre-core 0.58.0 → 0.59.0

package/dist/_pkgs/affine-block-root/view.js

@@ -1,11 +1,12 @@
 import { ExportToHtmlIcon, ExportToMarkdownIcon } from '@blocksuite/icons/lit';
 import { ViewExtensionProvider, } from '../affine-ext-loader/index.js';
 import { NoteBlockSchema } from '../affine-model/index.js';
-import { ToolbarModuleExtension, ViewportElementExtension, } from '../affine-shared/services/index.js';
+import { InvisibleCharacters, ToolbarModuleExtension, ViewportElementExtension, } from '../affine-shared/services/index.js';
 import { BlockFlavourIdentifier, BlockViewExtension, FlavourExtension, CommandExtension, ShortcutKeymapExtension, } from '../std/index.js';
 import { literal } from 'lit/static-html.js';
 import { PageClipboard, ReadOnlyClipboard } from './clipboard/index.js';
 import { copyLinkCommands } from './commands/copy-link-commands.js';
+import { invisibleCharactersCommands } from './commands/invisible-characters-commands.js';
 import { pageExportCommands } from './commands/page-export-commands.js';
 import { pivotCommands } from './commands/pivot-commands.js';
 import { readingCommands } from './commands/reading-commands.js';
@@ -74,6 +75,7 @@ export class RootViewExtension extends ViewExtensionProvider {
                 ...tagCommands,
                 ...readingCommands,
                 ...copyLinkCommands,
+                ...invisibleCharactersCommands,
             ]),
             // The page as Markdown or HTML (ADR 0034, amendment of 2026-10-14):
             // view actions of both views, never gated — the page's own text.
@@ -82,6 +84,9 @@ export class RootViewExtension extends ViewExtensionProvider {
                 'page.export.html': ExportToHtmlIcon(),
             }),
             ShortcutKeymapExtension('global'),
+            // "Show special characters", this viewer's display choice, read by
+            // every `v-text` under the host; both views, previews included.
+            InvisibleCharacters,
             ToolbarModuleExtension({
                 id: BlockFlavourIdentifier(NoteBlockSchema.model.flavour),
                 config: builtinToolbarConfig,

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

@@ -1,2 +1,2 @@
 export { autoArrangeElementsCommand, autoResizeElementsCommand, } from './auto-align.js';
-export { reassociateConnectorsCommand } from './reassociate-connectors.js';
+export { reassociateConnectors, reassociateConnectorsCommand, } from './reassociate-connectors.js';

package/dist/_pkgs/affine-block-surface/commands/index.js

@@ -1,2 +1,2 @@
 export { autoArrangeElementsCommand, autoResizeElementsCommand, } from './auto-align.js';
-export { reassociateConnectorsCommand } from './reassociate-connectors.js';
+export { reassociateConnectors, reassociateConnectorsCommand, } from './reassociate-connectors.js';

package/dist/_pkgs/affine-block-surface/commands/reassociate-connectors.d.ts

@@ -1,4 +1,13 @@
 import type { Command } from '../../std/index.js';
+import type { SurfaceBlockModel } from '../surface-model.js';
+/**
+ * Re-point every connector end bound to `oldId` at `newId`, keeping the rest
+ * of the endpoint (its `position`). The caller owns the transaction and the
+ * undo step: a model converted into another (a bookmark into an embed, a
+ * shape into an image, ADR 0044) re-points its connectors before the old one
+ * is deleted.
+ */
+export declare function reassociateConnectors(surface: Pick<SurfaceBlockModel, 'getConnectors' | 'updateElement'>, oldId: string, newId: string): void;
 /**
  * Re-associate bindings for block that have been converted.
  *

package/dist/_pkgs/affine-block-surface/commands/reassociate-connectors.js

@@ -1,18 +1,12 @@
 import { GfxControllerIdentifier } from '../../std/gfx/index.js';
 /**
- * Re-associate bindings for block that have been converted.
- *
- * @param oldId - the old block id
- * @param newId - the new block id
+ * Re-point every connector end bound to `oldId` at `newId`, keeping the rest
+ * of the endpoint (its `position`). The caller owns the transaction and the
+ * undo step: a model converted into another (a bookmark into an embed, a
+ * shape into an image, ADR 0044) re-points its connectors before the old one
+ * is deleted.
  */
-export const reassociateConnectorsCommand = (ctx, next) => {
-    const { oldId, newId } = ctx;
-    const gfx = ctx.std.get(GfxControllerIdentifier);
-    if (!oldId || !newId || !gfx.surface) {
-        next();
-        return;
-    }
-    const surface = gfx.surface;
+export function reassociateConnectors(surface, oldId, newId) {
     const connectors = surface.getConnectors(oldId);
     for (const { id, source, target } of connectors) {
         if (source.id === oldId) {
@@ -32,5 +26,20 @@ export const reassociateConnectorsCommand = (ctx, next) => {
             });
         }
     }
+}
+/**
+ * Re-associate bindings for block that have been converted.
+ *
+ * @param oldId - the old block id
+ * @param newId - the new block id
+ */
+export const reassociateConnectorsCommand = (ctx, next) => {
+    const { oldId, newId } = ctx;
+    const gfx = ctx.std.get(GfxControllerIdentifier);
+    if (!oldId || !newId || !gfx.surface) {
+        next();
+        return;
+    }
+    reassociateConnectors(gfx.surface, oldId, newId);
     next();
 };

package/dist/_pkgs/affine-block-surface/extensions/clipboard-config.d.ts

@@ -15,6 +15,15 @@ export type ClipboardConfigCreationContext = {
      */
     newPresentationIndexes: Map<string, string>;
 };
+/**
+ * A block a paste is ready to write (`EdgelessClipboardConfig.prepare`).
+ * `write` is synchronous for a config that follows the contract; a Promise is
+ * the legacy `createBlock` behind the default `prepare`.
+ */
+export interface PreparedClipboardBlock {
+    write(): string | null | Promise<string | null>;
+    afterWrite?(): void;
+}
 export declare const EdgelessClipboardConfigIdentifier: import("../../global/di/types.js").ServiceIdentifier<EdgelessClipboardConfig> & (<U extends EdgelessClipboardConfig = EdgelessClipboardConfig>(variant: import("../../global/di/types.js").ServiceVariant) => import("../../global/di/types.js").ServiceIdentifier<U>);
 export declare abstract class EdgelessClipboardConfig extends Extension {
     readonly std: BlockStdScope;
@@ -23,6 +32,30 @@ export declare abstract class EdgelessClipboardConfig extends Extension {
     get surface(): import("../surface-block.js").SurfaceBlockComponent | null;
     get crud(): import("./crud-extension.js").EdgelessCRUDExtension;
     onBlockSnapshotPaste: (snapshot: BlockSnapshot, doc: Store, parent?: string, index?: number) => Promise<string | null>;
+    /**
+     * `onBlockSnapshotPaste` in two halves, for `prepare`: the snapshot is
+     * converted now, the blocks are written by `write`, and the import
+     * middlewares run in `afterWrite`.
+     */
+    prepareBlockSnapshotPaste: (snapshot: BlockSnapshot, doc: Store, parent?: string, index?: number) => Promise<PreparedClipboardBlock | null>;
     abstract createBlock(snapshot: BlockSnapshot, context: ClipboardConfigCreationContext): string | null | Promise<string | null>;
+    /**
+     * The paste's two-phase contract (ADR 0042): everything slow (a blob fetch,
+     * a snapshot conversion) happens here and writes nothing; the returned
+     * `write` adds the block synchronously, because the paste calls every
+     * block's `write` and creates every canvas element in ONE transaction, which
+     * is one undo step and one update for a peer. `afterWrite` runs in the
+     * paste's second transaction, once every pasted model exists.
+     *
+     * The default defers to `createBlock`, so a config written before the
+     * contract keeps working; an async `createBlock` then still writes after
+     * the paste's transaction and may cost its own undo step.
+     */
+    prepare(snapshot: BlockSnapshot, context: ClipboardConfigCreationContext): PreparedClipboardBlock | null | Promise<PreparedClipboardBlock | null>;
+    /**
+     * `createBlock` for a config that implements `prepare`: prepares, then
+     * writes in one transaction of its own.
+     */
+    protected createPreparedBlock(snapshot: BlockSnapshot, context: ClipboardConfigCreationContext): Promise<string | null>;
     static setup(di: Container): void;
 }

package/dist/_pkgs/affine-block-surface/extensions/clipboard-config.js

@@ -17,6 +17,26 @@ export class EdgelessClipboardConfig extends Extension {
             const block = await this.std.clipboard.pasteBlockSnapshot(snapshot, doc, parent, index);
             return block?.id ?? null;
         };
+        /**
+         * `onBlockSnapshotPaste` in two halves, for `prepare`: the snapshot is
+         * converted now, the blocks are written by `write`, and the import
+         * middlewares run in `afterWrite`.
+         */
+        this.prepareBlockSnapshotPaste = async (snapshot, doc, parent, index) => {
+            applyCreationLayer(this.std, snapshot.props);
+            const prepared = await this.std.clipboard.prepareBlockSnapshot(snapshot, parent, index);
+            if (!prepared)
+                return null;
+            let flush;
+            return {
+                write: () => {
+                    const inserted = prepared.insert(doc);
+                    flush = inserted?.flushAfterImport;
+                    return inserted?.id ?? null;
+                },
+                afterWrite: () => flush?.(),
+            };
+        };
     }
     get surface() {
         return getSurfaceComponent(this.std);
@@ -24,6 +44,39 @@ export class EdgelessClipboardConfig extends Extension {
     get crud() {
         return this.std.get(EdgelessCRUDIdentifier);
     }
+    /**
+     * The paste's two-phase contract (ADR 0042): everything slow (a blob fetch,
+     * a snapshot conversion) happens here and writes nothing; the returned
+     * `write` adds the block synchronously, because the paste calls every
+     * block's `write` and creates every canvas element in ONE transaction, which
+     * is one undo step and one update for a peer. `afterWrite` runs in the
+     * paste's second transaction, once every pasted model exists.
+     *
+     * The default defers to `createBlock`, so a config written before the
+     * contract keeps working; an async `createBlock` then still writes after
+     * the paste's transaction and may cost its own undo step.
+     */
+    prepare(snapshot, context) {
+        return { write: () => this.createBlock(snapshot, context) };
+    }
+    /**
+     * `createBlock` for a config that implements `prepare`: prepares, then
+     * writes in one transaction of its own.
+     */
+    async createPreparedBlock(snapshot, context) {
+        const prepared = await this.prepare(snapshot, context);
+        if (!prepared)
+            return null;
+        const result = {
+            id: null,
+        };
+        this.std.store.transact(() => {
+            result.id = prepared.write();
+        });
+        const id = await result.id;
+        prepared.afterWrite?.();
+        return id;
+    }
     static setup(di) {
         if (!this.key) {
             throw new BlockSuiteError(BlockSuiteError.ErrorCode.ValueNotExists, 'Key is not defined in the EdgelessClipboardConfig');

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

@@ -3,6 +3,7 @@ import { rotatePoint } from '../../global/gfx/index.js';
 import { GfxElementModelView } from '../../std/gfx/index.js';
 import { EdgelessCRUDIdentifier } from '../extensions/crud-extension.js';
 import { backgroundLabelHits, hitTestBackgroundLabel } from './labels.js';
+import { measureBackgroundText } from './measure-text.js';
 /**
  * The rename gesture every framework background shares: double-click a label,
  * type, Enter or click away.
@@ -179,7 +180,7 @@ export class FrameworkBackgroundView extends GfxElementModelView {
  */
 export class DeclaredBackgroundView extends FrameworkBackgroundView {
     labelAt(lx, ly, w, h) {
-        const hit = hitTestBackgroundLabel(backgroundLabelHits(this.def, this.model, w, h, this.gfx.std.getOptional(TranslationProvider)), lx, ly);
+        const hit = hitTestBackgroundLabel(backgroundLabelHits(this.def, this.model, w, h, this.gfx.std.getOptional(TranslationProvider), measureBackgroundText), lx, ly);
         return hit ? { prop: hit.prop, text: hit.text } : null;
     }
 }

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

@@ -0,0 +1,104 @@
+import type { TranslationService } from '../../affine-shared/services/index.js';
+import type { BackgroundInset, BackgroundTextDef, BackgroundTextStyle, FrameworkBackgroundDef } from './def.js';
+import type { BackgroundModelLike } from './labels.js';
+/**
+ * How thick a background's bands are, once their labels have been measured.
+ *
+ * A band whose label declares `fit: 'wrap'` is as thick as its declaration says
+ * OR as thick as its wrapped words need, whichever is more (PO, 2026-10-27: a
+ * BPMN pool's title band grows with its name instead of cutting it). That is a
+ * function of measured text, so it cannot live in the declaration, and it must
+ * not be computed twice: the renderer paints the band, the label hit boxes
+ * (`labels.ts`) and a framework's own hit tests (`gfx/bpmn/src/pool-hit.ts`)
+ * aim at it, and the three disagreeing by a unit is a double-click that lands
+ * on the flow area beside the name it was aimed at. {@link backgroundBandWidths}
+ * is the one resolver they all read.
+ *
+ * Nothing is written to the document. The stored geometry is the declared one,
+ * and so is the plot the SEMANTIC readers use (facts, audit, rules, exports):
+ * where an artefact sits in a frame must not move because a title was renamed.
+ * Only the chrome — what is painted and what is aimed at — reads the grown
+ * widths.
+ *
+ * Kept beside `def.ts` rather than in it because it needs the label resolution
+ * of `labels.ts`, which itself reads `def.ts`.
+ */
+/** Width of `text` in model units when drawn in the CSS `font`. */
+export type BackgroundTextMeasure = (text: string, font: string) => number;
+/**
+ * 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 declare const BACKGROUND_WRAP_LINE_HEIGHT = 1.2;
+/** The family a declaration that names none falls back to. */
+export declare const DEFAULT_BACKGROUND_FONT_FAMILY = "Inter, sans-serif";
+/** The CSS font a background text is drawn in. */
+export declare function backgroundFont(style: BackgroundTextStyle, fallbackFamily?: string): string;
+/** Distance between two wrapped lines of this style, in model units. */
+export declare function backgroundWrapLineHeight(style: BackgroundTextStyle): number;
+/**
+ * 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 declare function backgroundTextRoom(ax: number, ay: number, align: BackgroundTextDef['align'], vertical: boolean, w: number, h: number): number;
+/**
+ * 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 declare function estimateBackgroundText(text: string, font: string): number;
+/** A side band's label once wrapped: what to draw and where. */
+export interface BackgroundWrappedLabel {
+    lines: readonly string[];
+    /**
+     * Model units to add to the label's anchor, resolved against the GROWN plot,
+     * so it keeps its offset from the middle of its band: half the growth, back
+     * towards the card edge.
+     */
+    shift: readonly [number, number];
+}
+/** The bands of one instance, sized by what they hold. */
+export interface BackgroundBandLayout {
+    /** The margins, each side band grown to what its wrapped label needs. */
+    margin: BackgroundInset;
+    /**
+     * Thickness of every instance-zone strip — the declared width or the one the
+     * most demanding wrapped name needs. `undefined` without a strip.
+     */
+    zoneBandWidth: number | undefined;
+    /** Each wrapped side-band label, by its declaration. */
+    labels: ReadonlyMap<BackgroundTextDef, BackgroundWrappedLabel>;
+    /** Each wrapped instance-zone name, by reported zone id. */
+    zoneLines: ReadonlyMap<string, readonly string[]>;
+}
+/**
+ * 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 declare function backgroundBandWidths(def: FrameworkBackgroundDef, model: BackgroundModelLike, w: number, h: number, measure?: BackgroundTextMeasure, translation?: TranslationService | null): BackgroundBandLayout;

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.
  *