@formicoidea/labre-core 0.58.0 → 0.60.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/extensions/index.d.ts

@@ -10,6 +10,7 @@ export * from './element-renderer.js';
 export * from './export-manager/index.js';
 export * from './export-svg/index.js';
 export * from './interchange.js';
+export * from './toolbox.js';
 export * from './interchange-export.js';
 export * from './interchange-import.js';
 export * from './legacy-slot-extension.js';

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

@@ -10,6 +10,7 @@ export * from './element-renderer.js';
 export * from './export-manager/index.js';
 export * from './export-svg/index.js';
 export * from './interchange.js';
+export * from './toolbox.js';
 export * from './interchange-export.js';
 export * from './interchange-import.js';
 export * from './legacy-slot-extension.js';

package/dist/_pkgs/affine-block-surface/extensions/legend-label.d.ts

@@ -0,0 +1,11 @@
+/**
+ * The ink and the type a notation writes its labels in: the legend box's rows,
+ * and the words the DDD prefabs set beside a dot or a marker.
+ *
+ * Declared HERE and re-exported by `@labre/affine-gfx-ddd-shared`, rather than
+ * the other way round, because that bundle depends on this one and a legend
+ * must not depend on a DDD bundle to be drawn.
+ */
+export declare const LABEL_COLOR: string;
+export declare const LABEL_FONT = "blocksuite:surface:Inter";
+export declare const LABEL_FONT_SIZE = 14;

package/dist/_pkgs/affine-block-surface/extensions/legend-label.js

@@ -0,0 +1,16 @@
+import { NOTATION_NEUTRALS } from '../../affine-shared/headless.js';
+// Its own module so the headless interchange entry (`./interchange`) can read
+// it without the legend's editor graph: the DDD element builders of
+// `@labre/affine-gfx-ddd-shared/headless` write their captions in these three
+// values (`docs/adr/0045`). `legend.ts` re-exports them unchanged.
+/**
+ * The ink and the type a notation writes its labels in: the legend box's rows,
+ * and the words the DDD prefabs set beside a dot or a marker.
+ *
+ * Declared HERE and re-exported by `@labre/affine-gfx-ddd-shared`, rather than
+ * the other way round, because that bundle depends on this one and a legend
+ * must not depend on a DDD bundle to be drawn.
+ */
+export const LABEL_COLOR = NOTATION_NEUTRALS.ink;
+export const LABEL_FONT = 'blocksuite:surface:Inter';
+export const LABEL_FONT_SIZE = 14;

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

@@ -46,17 +46,7 @@ export interface LegendLayout {
 }
 /** A block of the box that is not a row. See {@link CommandLegendBox.extras}. */
 export type LegendExtra = CommandLegendExtra;
-/**
- * The ink and the type a notation writes its labels in: this box's rows, and
- * the words the DDD prefabs set beside a dot or a marker.
- *
- * Declared HERE and re-exported by `@labre/affine-gfx-ddd-shared`, rather than
- * the other way round, because that bundle depends on this one and a legend
- * must not depend on a DDD bundle to be drawn.
- */
-export declare const LABEL_COLOR: string;
-export declare const LABEL_FONT = "blocksuite:surface:Inter";
-export declare const LABEL_FONT_SIZE = 14;
+export { LABEL_COLOR, LABEL_FONT, LABEL_FONT_SIZE } from './legend-label.js';
 export { LEGEND_ROLE };
 /**
  * How big the box {@link addLegend} would draw for these sections is — without

package/dist/_pkgs/affine-block-surface/extensions/legend.js

@@ -5,18 +5,9 @@ import { Bound } from '../../global/gfx/index.js';
 import { CATALOGUE_CATEGORY_KEY_PREFIX, getRegisteredCommands, humanizeCategory, } from '../../std/index.js';
 import { GfxControllerIdentifier, roleIsA, RoleVocabularyIdentifier, } from '../../std/gfx/index.js';
 import { EdgelessCRUDIdentifier } from './crud-extension.js';
+import { LABEL_COLOR, LABEL_FONT, LABEL_FONT_SIZE } from './legend-label.js';
 import { LEGEND_ROLE } from './legend-role.js';
-/**
- * The ink and the type a notation writes its labels in: this box's rows, and
- * the words the DDD prefabs set beside a dot or a marker.
- *
- * Declared HERE and re-exported by `@labre/affine-gfx-ddd-shared`, rather than
- * the other way round, because that bundle depends on this one and a legend
- * must not depend on a DDD bundle to be drawn.
- */
-export const LABEL_COLOR = NOTATION_NEUTRALS.ink;
-export const LABEL_FONT = 'blocksuite:surface:Inter';
-export const LABEL_FONT_SIZE = 14;
+export { LABEL_COLOR, LABEL_FONT, LABEL_FONT_SIZE } from './legend-label.js';
 const NO_STROKE = '#00000000';
 /**
  * The box's geometry, in one place because two callers need it: the one that

package/dist/_pkgs/affine-block-surface/extensions/reading-toolbar.js

@@ -58,18 +58,18 @@ const READ_LABEL_FALLBACK = 'Read this component';
  * Drawn inline like its neighbours: this package does not depend on
  * `@blocksuite/icons` and one glyph is not worth a new dependency.
  */
-const ReadIcon = html `<svg
-  width="20"
-  height="20"
-  viewBox="0 0 24 24"
-  fill="none"
-  stroke="currentColor"
-  stroke-width="2"
-  stroke-linecap="round"
-  stroke-linejoin="round"
->
-  <path d="M2 12s3.5-6 10-6 10 6 10 6-3.5 6-10 6-10-6-10-6z" />
-  <circle cx="12" cy="12" r="3" />
+const ReadIcon = html `<svg
+  width="20"
+  height="20"
+  viewBox="0 0 24 24"
+  fill="none"
+  stroke="currentColor"
+  stroke-width="2"
+  stroke-linecap="round"
+  stroke-linejoin="round"
+>
+  <path d="M2 12s3.5-6 10-6 10 6 10 6-3.5 6-10 6-10-6-10-6z" />
+  <circle cx="12" cy="12" r="3" />
 </svg>`;
 /** The command this module drives. Spelled once. */
 const ELEMENT_READ_ID = 'element.read';

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

@@ -0,0 +1,62 @@
+import type { SerializedElementProps } from './interchange.js';
+/**
+ * A framework's TOOLBOX, with no editor behind it (`docs/adr/0045`): every
+ * item of its toolbar as a pure builder, so a host with no editor — the Labre
+ * workspace connector, labre-mcp — places the very elements a user places
+ * from the toolbar, never shapes that imitate them.
+ *
+ * ## The same contract as a reader's result
+ *
+ * A builder returns what an import capability returns (ADR 0012 D3): element
+ * props in painting order, each composite's members before the group that
+ * holds them, and LOCAL `id`s the group's `children` and a link's ends name.
+ * `surface.addElement` mints the real ids and the materializer
+ * (`materializeInterchangeImport`) rewrites the references, so one writer
+ * serves a whole file read by a reader and one item built here.
+ *
+ * ## What a builder does not do
+ *
+ * It places ONE item at the point it is given: where things go on a board is
+ * the caller's. It writes the texts it is given, or the English seed: a seed
+ * in the host's language is resolved by the editor's creation site, which has
+ * the catalogue (ADR 0023). It persists nothing.
+ */
+/** Where an item lands: the top-left of its box, in canvas units. */
+export interface ToolboxPoint {
+    x: number;
+    y: number;
+}
+/** One toolbar item that places elements. */
+export interface ToolboxItem {
+    /** Stable within the framework, kebab-case: `container`, `system-boundary`. */
+    readonly id: string;
+    /** The toolbar command's own label, so a host names it as the toolbar does. */
+    readonly labelKey: string;
+    readonly labelFallback: string;
+    /** The text slots `build` fills, in reading order (`title`, `description`…). */
+    readonly texts: readonly string[];
+    /** The box the item is born with. */
+    readonly size: {
+        readonly w: number;
+        readonly h: number;
+    };
+    /**
+     * The elements, with local ids and the group last. `local` prefixes those
+     * ids, so two items built for one batch never share a name.
+     */
+    build(at: ToolboxPoint, texts?: Readonly<Record<string, string>>, local?: string): SerializedElementProps[];
+}
+/** One relation style of the framework: a connector between two elements. */
+export interface ToolboxLink {
+    readonly id: string;
+    readonly labelKey: string;
+    readonly labelFallback: string;
+    /** The connector props; `from` and `to` are element ids or local ids. */
+    build(from: string, to: string, label?: string): SerializedElementProps;
+}
+export interface FrameworkToolbox {
+    /** The framework's descriptor id (`c4`, `bpmn`…). */
+    readonly framework: string;
+    readonly items: readonly ToolboxItem[];
+    readonly links: readonly ToolboxLink[];
+}

package/dist/_pkgs/affine-block-surface/extensions/toolbox.js

@@ -0,0 +1 @@
+export {};

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;