@formicoidea/labre-core 0.41.0 → 0.43.1

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

@@ -0,0 +1,115 @@
+import type { EditorHost } from '../../std/index.js';
+import type { GfxPrimitiveElementModel, PointTestOptions } from '../../std/gfx/index.js';
+import { GfxElementModelView } from '../../std/gfx/index.js';
+import type { FrameworkBackgroundDef } from './def.js';
+/** A label a double-click may rename: the prop to write, and the words shown. */
+export interface EditableBackgroundLabel {
+    /** The model prop the in-place editor writes back to. */
+    prop: string;
+    /**
+     * The words currently DRAWN there.
+     *
+     * The editor opens on this, not on `model[prop]`: a label whose prop has
+     * never been written shows its vocabulary, and opening an empty box on it
+     * would silently offer to erase a name the user can see.
+     */
+    text: string;
+    /**
+     * Where the edited words go, when a flat `{ [prop]: value }` patch cannot say
+     * it. Absent — the case for every label a declaration binds — the editor
+     * writes `updateElement(id, { [prop]: value })`.
+     *
+     * The one label shape that needs it is a name kept INSIDE a structured prop:
+     * a UML combined fragment's operand guard lives in `operands[i].name`, and
+     * renaming it means rewriting that array (trimmed, the key dropped when
+     * cleared), which no single-prop patch expresses. A write hook on the label
+     * rather than on the view, because the target is a property of the label hit
+     * — one view carries labels of both kinds.
+     *
+     * Called only for an ACTUAL change (the untouched-value rule below still
+     * applies), after the editor has closed and after the undo boundary has been
+     * captured: the hook writes, and nothing else.
+     */
+    commit?: (value: string) => void;
+}
+/**
+ * The rename gesture every framework background shares: double-click a label,
+ * type, Enter or click away.
+ *
+ * Written ONCE here, and that is the whole point of the file. The Wardley map
+ * shipped it first, EDGY copied the half it needed, C4 and BPMN copied other
+ * halves — and the three backgrounds that never got a copy (the Core Domain
+ * Chart, the Event Storming board, Cynefin and Estuarine) simply had no way to
+ * rename anything, which is how issue #355 was reported. R14 of
+ * `docs/add-a-framework/02-framework-rules.md` — extend, never copy — applies
+ * to a view's overrides exactly as it applies to a model's: seven copies of an
+ * `<input>` is not a seam, it is six places for the next fix to miss.
+ *
+ * A subclass says only WHERE its labels are, through {@link labelAt}. Almost
+ * every framework answers that from its declaration and should extend
+ * {@link DeclaredBackgroundView} instead; a framework that paints its words by
+ * hand (Cynefin, Estuarine — figurative reproductions of an official drawing,
+ * with no `FrameworkBackgroundDef` behind them) extends this class and hit-tests
+ * in its own reference space.
+ *
+ * UML's five frames were the last copy standing and now extend
+ * {@link DeclaredBackgroundView} like the rest (2026-09-17); the combined
+ * fragment's operand guards are why a label may carry its own
+ * {@link EditableBackgroundLabel.commit}.
+ */
+export declare abstract class FrameworkBackgroundView<T extends GfxPrimitiveElementModel = GfxPrimitiveElementModel> extends GfxElementModelView<T> {
+    /** The in-place `<input>` used to edit a label, or null when idle. */
+    private _labelEditor;
+    onCreated(): void;
+    onDestroyed(): void;
+    /**
+     * The editable label under an ELEMENT-LOCAL point, or null.
+     *
+     * `lx` / `ly` are already de-rotated and relative to the element's top-left
+     * corner, and `w` / `h` are its current size: a subclass never repeats the
+     * rotation arithmetic, which is precisely what four copies of it got wrong in
+     * four slightly different ways.
+     */
+    protected abstract labelAt(lx: number, ly: number, w: number, h: number): EditableBackgroundLabel | null;
+    /**
+     * A background is SELECTED by its border (`FrameworkBackgroundElementModel`,
+     * issue #194) — but the words written on it must still receive the
+     * double-click that renames them.
+     *
+     * So the two areas differ, and this is where they are allowed to: the pointer
+     * router asks the VIEW (`GfxViewEventManager`), and the view adds the zones
+     * its labels are drawn in. Picking is unaffected — `getElementByPoint` still
+     * asks the model, so a click in the middle of the frame still goes to
+     * whatever the user put there.
+     */
+    includesPoint(x: number, y: number, options: PointTestOptions, host: EditorHost): boolean;
+    /** The editable label under a MODEL-space point, or null. */
+    private _labelAtModelPoint;
+    /** Double-click on a label → edit its text in place. */
+    private _onDblClick;
+    /**
+     * @param label the label aimed at. The editor opens on `label.text`, the
+     * words currently DRAWN — which is the vocabulary, not `model[prop]`, for a
+     * label the user has never renamed. Opening on the raw prop would show an
+     * empty box for a label that plainly reads "Evolution".
+     */
+    private _openLabelEditor;
+    private _closeLabelEditor;
+}
+/**
+ * The same gesture, aimed by the DECLARATION the renderer paints.
+ *
+ * Which labels exist, where they sit, what they SAY and which are editable all
+ * come from one place, resolved through the same catalogue — so a label can
+ * never be drawn in one place and clicked in another, nor read one thing and
+ * open on another. A subclass supplies its {@link def} and nothing else.
+ *
+ * A framework that needs to narrow the answer — a closed list of writable
+ * props, a hit region wider than the words — overrides {@link labelAt} and
+ * calls `super.labelAt` for the declaration's answer first.
+ */
+export declare abstract class DeclaredBackgroundView<T extends GfxPrimitiveElementModel = GfxPrimitiveElementModel> extends FrameworkBackgroundView<T> {
+    /** The declaration this view hit-tests against — the one the renderer paints. */
+    protected abstract get def(): FrameworkBackgroundDef;
+    protected labelAt(lx: number, ly: number, w: number, h: number): EditableBackgroundLabel | null;
+}

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

@@ -0,0 +1,185 @@
+import { TranslationProvider } from '../../affine-shared/services/index.js';
+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';
+/**
+ * The rename gesture every framework background shares: double-click a label,
+ * type, Enter or click away.
+ *
+ * Written ONCE here, and that is the whole point of the file. The Wardley map
+ * shipped it first, EDGY copied the half it needed, C4 and BPMN copied other
+ * halves — and the three backgrounds that never got a copy (the Core Domain
+ * Chart, the Event Storming board, Cynefin and Estuarine) simply had no way to
+ * rename anything, which is how issue #355 was reported. R14 of
+ * `docs/add-a-framework/02-framework-rules.md` — extend, never copy — applies
+ * to a view's overrides exactly as it applies to a model's: seven copies of an
+ * `<input>` is not a seam, it is six places for the next fix to miss.
+ *
+ * A subclass says only WHERE its labels are, through {@link labelAt}. Almost
+ * every framework answers that from its declaration and should extend
+ * {@link DeclaredBackgroundView} instead; a framework that paints its words by
+ * hand (Cynefin, Estuarine — figurative reproductions of an official drawing,
+ * with no `FrameworkBackgroundDef` behind them) extends this class and hit-tests
+ * in its own reference space.
+ *
+ * UML's five frames were the last copy standing and now extend
+ * {@link DeclaredBackgroundView} like the rest (2026-09-17); the combined
+ * fragment's operand guards are why a label may carry its own
+ * {@link EditableBackgroundLabel.commit}.
+ */
+export class FrameworkBackgroundView extends GfxElementModelView {
+    constructor() {
+        super(...arguments);
+        /** The in-place `<input>` used to edit a label, or null when idle. */
+        this._labelEditor = null;
+    }
+    onCreated() {
+        super.onCreated();
+        this.on('dblclick', e => this._onDblClick(e));
+    }
+    onDestroyed() {
+        this._closeLabelEditor();
+        super.onDestroyed();
+    }
+    /**
+     * A background is SELECTED by its border (`FrameworkBackgroundElementModel`,
+     * issue #194) — but the words written on it must still receive the
+     * double-click that renames them.
+     *
+     * So the two areas differ, and this is where they are allowed to: the pointer
+     * router asks the VIEW (`GfxViewEventManager`), and the view adds the zones
+     * its labels are drawn in. Picking is unaffected — `getElementByPoint` still
+     * asks the model, so a click in the middle of the frame still goes to
+     * whatever the user put there.
+     */
+    includesPoint(x, y, options, host) {
+        if (super.includesPoint(x, y, options, host))
+            return true;
+        return this._labelAtModelPoint(x, y) !== null;
+    }
+    /** The editable label under a MODEL-space point, or null. */
+    _labelAtModelPoint(mx, my) {
+        const [bx, by, w, h] = this.model.deserializedXYWH;
+        // Element-local coordinates, undoing the element rotation about its centre.
+        let lx = mx - bx;
+        let ly = my - by;
+        const rot = this.model.rotate ?? 0;
+        if (rot) {
+            const center = [bx + w / 2, by + h / 2];
+            const [ux, uy] = rotatePoint([mx, my], center, -rot);
+            lx = ux - bx;
+            ly = uy - by;
+        }
+        return this.labelAt(lx, ly, w, h);
+    }
+    /** Double-click on a label → edit its text in place. */
+    _onDblClick(e) {
+        if (this.gfx.std.store.readonly || this.model.isLocked())
+            return;
+        const [mx, my] = this.gfx.viewport.toModelCoord(e.x, e.y);
+        const hit = this._labelAtModelPoint(mx, my);
+        if (!hit)
+            return;
+        this._openLabelEditor(hit, e);
+    }
+    /**
+     * @param label the label aimed at. The editor opens on `label.text`, the
+     * words currently DRAWN — which is the vocabulary, not `model[prop]`, for a
+     * label the user has never renamed. Opening on the raw prop would show an
+     * empty box for a label that plainly reads "Evolution".
+     */
+    _openLabelEditor(label, e) {
+        this._closeLabelEditor();
+        const current = label.text;
+        const input = document.createElement('input');
+        input.value = current;
+        Object.assign(input.style, {
+            position: 'fixed',
+            left: `${e.raw.clientX}px`,
+            top: `${e.raw.clientY}px`,
+            transform: 'translate(-50%, -50%)',
+            zIndex: '10000',
+            minWidth: '140px',
+            padding: '3px 8px',
+            font: '14px Inter, sans-serif',
+            color: 'var(--affine-text-primary-color, #1f2328)',
+            background: 'var(--affine-background-overlay-panel-color, #ffffff)',
+            border: '1px solid var(--affine-primary-color)',
+            borderRadius: '6px',
+            boxShadow: 'var(--affine-shadow-2, 0 2px 8px rgba(0,0,0,0.18))',
+            outline: 'none',
+        });
+        document.body.append(input);
+        this._labelEditor = input;
+        // Mark the element as "editing" so the global edgeless key handlers
+        // (delete, escape, etc.) don't act on it while the user types.
+        this.gfx.selection.set({ elements: [this.model.id], editing: true });
+        input.focus();
+        input.select();
+        const commit = () => {
+            // Guard against re-entrancy: removing the input fires `blur` — Chrome
+            // fires it SYNCHRONOUSLY inside `remove()` — which would otherwise call
+            // `commit` a second time. `_closeLabelEditor` clears the field before it
+            // removes the node, so that nested call finds it gone and returns.
+            if (this._labelEditor !== input)
+                return;
+            const value = input.value;
+            this._closeLabelEditor();
+            // Opening an editor is not renaming. Writing back an untouched value
+            // would persist the resolved VOCABULARY as the user's own text, freezing
+            // the label in whatever language it was read in and putting it beyond
+            // any catalogue for good — and it would push an empty entry onto undo.
+            if (value === current)
+                return;
+            this.gfx.std.store.captureSync();
+            if (label.commit) {
+                label.commit(value);
+                return;
+            }
+            this.gfx.std
+                .get(EdgelessCRUDIdentifier)
+                .updateElement(this.model.id, { [label.prop]: value });
+        };
+        input.addEventListener('keydown', ev => {
+            ev.stopPropagation();
+            if (ev.key === 'Enter') {
+                ev.preventDefault();
+                commit();
+            }
+            else if (ev.key === 'Escape') {
+                ev.preventDefault();
+                this._closeLabelEditor();
+            }
+        });
+        input.addEventListener('blur', commit);
+    }
+    _closeLabelEditor() {
+        if (!this._labelEditor)
+            return;
+        const input = this._labelEditor;
+        this._labelEditor = null;
+        input.remove();
+        if (this.isConnected) {
+            this.gfx.selection.set({ elements: [this.model.id], editing: false });
+        }
+    }
+}
+/**
+ * The same gesture, aimed by the DECLARATION the renderer paints.
+ *
+ * Which labels exist, where they sit, what they SAY and which are editable all
+ * come from one place, resolved through the same catalogue — so a label can
+ * never be drawn in one place and clicked in another, nor read one thing and
+ * open on another. A subclass supplies its {@link def} and nothing else.
+ *
+ * A framework that needs to narrow the answer — a closed list of writable
+ * props, a hit region wider than the words — overrides {@link labelAt} and
+ * calls `super.labelAt` for the declaration's answer first.
+ */
+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);
+        return hit ? { prop: hit.prop, text: hit.text } : null;
+    }
+}

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

@@ -0,0 +1,36 @@
+/**
+ * How a framework that draws a FIXED reference artwork puts it in its element.
+ *
+ * A declared background (`FrameworkBackgroundDef`) never needs this: it is made
+ * of ratios of a plot and stretches with the element by construction. The
+ * frameworks that reproduce an authored drawing — Cynefin, Estuarine, EDGY, the
+ * DDD stencils — cannot stretch: circles would turn into ellipses and a
+ * hand-drawn boundary into a smear. They fit the artwork uniformly instead and
+ * centre what is left over.
+ *
+ * This was written three times over — `gfx/cynefin-estuarine/src/utils.ts`,
+ * `gfx/ddd-shared/src/shared/utils.ts` and `gfx/edgy/src/consts.ts` — with the
+ * same body each time. One source of truth (R37): the three call it, and a
+ * board that crops itself onto its drawing
+ * (`gfx/cynefin-estuarine/src/cynefin/crop.ts`) reads the very function the
+ * renderer painted through, so the two can never disagree about where the
+ * drawing is.
+ */
+/** A uniform fit: the scale, and the offsets that centre the letterbox. */
+export interface RefFit {
+    /** Scale from reference units to element units. */
+    s: number;
+    /** Left offset of the fitted artwork inside the element, in element units. */
+    ox: number;
+    /** Top offset of the fitted artwork inside the element, in element units. */
+    oy: number;
+}
+/**
+ * Uniform fit of a `refW × refH` reference design into a `w × h` box: the
+ * scale factor plus the centring offsets (letterboxed), undistorted.
+ *
+ * The fitted artwork is `refW * s` by `refH * s` and shares the box's CENTRE —
+ * `ox + refW * s / 2 === w / 2` — which is what lets a board crop itself onto
+ * its drawing without the drawing moving, rotation included.
+ */
+export declare function refScale(w: number, h: number, refW: number, refH: number): RefFit;

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

@@ -0,0 +1,30 @@
+/**
+ * How a framework that draws a FIXED reference artwork puts it in its element.
+ *
+ * A declared background (`FrameworkBackgroundDef`) never needs this: it is made
+ * of ratios of a plot and stretches with the element by construction. The
+ * frameworks that reproduce an authored drawing — Cynefin, Estuarine, EDGY, the
+ * DDD stencils — cannot stretch: circles would turn into ellipses and a
+ * hand-drawn boundary into a smear. They fit the artwork uniformly instead and
+ * centre what is left over.
+ *
+ * This was written three times over — `gfx/cynefin-estuarine/src/utils.ts`,
+ * `gfx/ddd-shared/src/shared/utils.ts` and `gfx/edgy/src/consts.ts` — with the
+ * same body each time. One source of truth (R37): the three call it, and a
+ * board that crops itself onto its drawing
+ * (`gfx/cynefin-estuarine/src/cynefin/crop.ts`) reads the very function the
+ * renderer painted through, so the two can never disagree about where the
+ * drawing is.
+ */
+/**
+ * Uniform fit of a `refW × refH` reference design into a `w × h` box: the
+ * scale factor plus the centring offsets (letterboxed), undistorted.
+ *
+ * The fitted artwork is `refW * s` by `refH * s` and shares the box's CENTRE —
+ * `ox + refW * s / 2 === w / 2` — which is what lets a board crop itself onto
+ * its drawing without the drawing moving, rotation included.
+ */
+export function refScale(w, h, refW, refH) {
+    const s = Math.min(w / refW, h / refH);
+    return { s, ox: (w - refW * s) / 2, oy: (h - refH * s) / 2 };
+}

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

@@ -1,5 +1,7 @@
+export * from './background-view.js';
 export * from './def.js';
 export * from './facts.js';
+export * from './fit.js';
 export * from './interaction.js';
 export * from './labels.js';
 export * from './renderer.js';

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

@@ -1,5 +1,7 @@
+export * from './background-view.js';
 export * from './def.js';
 export * from './facts.js';
+export * from './fit.js';
 export * from './interaction.js';
 export * from './labels.js';
 export * from './renderer.js';

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

@@ -36,7 +36,7 @@ export declare function backgroundVisible(visibleProp: string | undefined, model
  */
 export declare function backgroundInVariant(def: FrameworkBackgroundDef, variants: readonly string[] | undefined, model: BackgroundModelLike): boolean;
 /** A label's clickable box in element-local coordinates (axis-aligned, padded). */
-export interface BackgroundLabelHit {
+export interface BackgroundLabelHit extends BackgroundTextBox {
     /** The declaration id of the text. */
     id: string;
     /** The model prop the in-place editor must write back to. */
@@ -49,11 +49,26 @@ export interface BackgroundLabelHit {
      * would silently offer to erase a name the user can see.
      */
     text: string;
+}
+/** The padded box of one drawn word, in the space its anchor is expressed in. */
+export interface BackgroundTextBox {
     minX: number;
     minY: number;
     maxX: number;
     maxY: number;
 }
+/**
+ * The clickable box of a word drawn at `(ax, ay)` on an ALPHABETIC baseline —
+ * the one convention every background in the library paints its text on.
+ *
+ * Exported because two frameworks place their words without a declaration
+ * (Cynefin and Estuarine are figurative reproductions of an official drawing,
+ * scaled by their own fit) and still have to offer the same forgiving target as
+ * everybody else. They pass a point already mapped into element coordinates;
+ * the padding, the rough advance and the baseline arithmetic stay here, in one
+ * place, so a label is not easier to hit on one framework than on the next.
+ */
+export declare function backgroundTextHitBox(words: string, fontSize: number, ax: number, ay: number, align?: 'left' | 'center' | 'right', vertical?: boolean): BackgroundTextBox;
 /**
  * Every text of a declaration, in PAINTING ORDER: the side-band labels, the
  * zone labels, then each axis' title followed by its end labels.

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

@@ -75,6 +75,36 @@ export function backgroundInVariant(def, variants, model) {
 const approxTextWidth = (text, fontSize) => Math.max(fontSize, text.length * fontSize * 0.6);
 /** Padding so double-clicking a label is forgiving. */
 const HIT_PAD = 6;
+/**
+ * The clickable box of a word drawn at `(ax, ay)` on an ALPHABETIC baseline —
+ * the one convention every background in the library paints its text on.
+ *
+ * Exported because two frameworks place their words without a declaration
+ * (Cynefin and Estuarine are figurative reproductions of an official drawing,
+ * scaled by their own fit) and still have to offer the same forgiving target as
+ * everybody else. They pass a point already mapped into element coordinates;
+ * the padding, the rough advance and the baseline arithmetic stay here, in one
+ * place, so a label is not easier to hit on one framework than on the next.
+ */
+export function backgroundTextHitBox(words, fontSize, ax, ay, align = 'left', vertical = false) {
+    const tw = approxTextWidth(words, fontSize);
+    if (vertical) {
+        return {
+            minX: ax - fontSize - HIT_PAD,
+            maxX: ax + fontSize * 0.4 + HIT_PAD,
+            minY: ay - tw / 2 - HIT_PAD,
+            maxY: ay + tw / 2 + HIT_PAD,
+        };
+    }
+    const minX = align === 'right' ? ax - tw : align === 'center' ? ax - tw / 2 : ax;
+    const maxX = align === 'right' ? ax : align === 'center' ? ax + tw / 2 : ax + tw;
+    return {
+        minX: minX - HIT_PAD,
+        maxX: maxX + HIT_PAD,
+        minY: ay - fontSize - HIT_PAD,
+        maxY: ay + fontSize * 0.3 + HIT_PAD,
+    };
+}
 /**
  * Every text of a declaration, in PAINTING ORDER: the side-band labels, the
  * zone labels, then each axis' title followed by its end labels.
@@ -152,32 +182,12 @@ export function backgroundLabelHits(def, model, w, h, translation) {
         if (!backgroundVisible(text.visibleProp, model))
             continue;
         const words = backgroundLabelText(text, model, translation);
-        const size = text.style.size;
-        const tw = approxTextWidth(words, size);
         const [ax, ay] = backgroundPoint(text.anchor, plot);
-        if (text.vertical) {
-            hits.push({
-                id: text.id,
-                prop: text.prop,
-                text: words,
-                minX: ax - size - HIT_PAD,
-                maxX: ax + size * 0.4 + HIT_PAD,
-                minY: ay - tw / 2 - HIT_PAD,
-                maxY: ay + tw / 2 + HIT_PAD,
-            });
-            continue;
-        }
-        const align = text.align ?? 'left';
-        const minX = align === 'right' ? ax - tw : align === 'center' ? ax - tw / 2 : ax;
-        const maxX = align === 'right' ? ax : align === 'center' ? ax + tw / 2 : ax + tw;
         hits.push({
             id: text.id,
             prop: text.prop,
             text: words,
-            minX: minX - HIT_PAD,
-            maxX: maxX + HIT_PAD,
-            minY: ay - size - HIT_PAD,
-            maxY: ay + size * 0.3 + HIT_PAD,
+            ...backgroundTextHitBox(words, text.style.size, ax, ay, text.align, text.vertical),
         });
     }
     return hits;

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

@@ -33,8 +33,22 @@ import { backgroundInVariant, backgroundLabelText, backgroundTexts, backgroundVi
  * legible however large the background is stretched. Only the plot interior
  * moves.
  */
+/**
+ * Trace the card, and say whether there was one to trace.
+ *
+ * The drawable box has the border subtracted from it, so a background dragged
+ * to nothing — or one whose `xywh` came back degenerate from a damaged
+ * document — asks for a negative radius: a 1.5 border on a 1-unit card gives
+ * -0.75. `arcTo` throws `IndexSizeError` on that rather than clamping, and the
+ * surface render loop wraps no renderer in a `try`, so one such throw aborts
+ * the rest of the frame with an unbalanced save stack. Returning `false` lets
+ * the caller skip the fill and the stroke too, rather than painting a
+ * degenerate path.
+ */
 function roundRectPath(ctx, x, y, w, h, r) {
-    const rr = Math.min(r, w / 2, h / 2);
+    if (!(w > 0) || !(h > 0))
+        return false;
+    const rr = Math.max(0, Math.min(r, w / 2, h / 2));
     ctx.beginPath();
     ctx.moveTo(x + rr, y);
     ctx.arcTo(x + w, y, x + w, y + h, rr);
@@ -42,6 +56,7 @@ function roundRectPath(ctx, x, y, w, h, r) {
     ctx.arcTo(x, y + h, x, y, rr);
     ctx.arcTo(x, y, x + w, y, rr);
     ctx.closePath();
+    return true;
 }
 const HEX6 = /^#[0-9a-fA-F]{6}$/;
 /**
@@ -108,6 +123,13 @@ export function createFrameworkBackgroundRenderer(def) {
         // that ships no locale pack — both fall back to the declared wording.
         const translation = renderer?.std.getOptional(TranslationProvider) ?? null;
         const [, , w, h] = model.deserializedXYWH;
+        // A background with no area has no card, no bands, no plot and no text, so
+        // there is nothing to paint and every ratio below would divide by zero.
+        // Bailing here is also what keeps a degenerate element from reaching
+        // `arcTo` at all; `roundRectPath` stays the second line of defence for a
+        // card that is positive but smaller than its own border.
+        if (!(w > 0) || !(h > 0))
+            return;
         const cx = w / 2;
         const cy = h / 2;
         ctx.setTransform(matrix
@@ -149,8 +171,10 @@ export function createFrameworkBackgroundRenderer(def) {
         const border = surface.border;
         const inset = border ? border.width / 2 : 0;
         const cardPath = () => roundRectPath(ctx, inset, inset, w - inset * 2, h - inset * 2, border?.radius ?? 0);
-        cardPath();
-        if (surface.fill) {
+        // A card whose border eats the whole element is not traced at all, and then
+        // neither its fill nor its frame is painted.
+        const carded = cardPath();
+        if (carded && surface.fill) {
             ctx.fillStyle = color(surface.fill);
             ctx.fill();
         }
@@ -191,10 +215,10 @@ export function createFrameworkBackgroundRenderer(def) {
                         ctx.setLineDash([]);
                 }
             }
-            if (border)
+            if (border && carded)
                 cardPath();
         }
-        if (border) {
+        if (border && carded) {
             ctx.strokeStyle = color(border.color);
             ctx.lineWidth = border.width;
             if (border.dash?.length)

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

@@ -62,10 +62,12 @@ export declare function indexOverBackgrounds(siblings: readonly StackedElement[]
  *    is still below every artefact already drawn there. Otherwise nothing.
  * 2. `element` IS a background. If another background it overlaps sits above
  *    it, the same raise applies — superposed boards stack in the order they
- *    were placed, each still under its own artefacts. Otherwise, if it covers
- *    an artefact it overlaps, it is acting as a lid: lower it to just above
- *    the floor it lies on, or to the back of the surface when it lies on bare
- *    canvas. Otherwise nothing.
+ *    were placed, each still under its own artefacts — unless it ENCLOSES that
+ *    background, in which case it is the sheet the other is drawn on and stays
+ *    under it ({@link encloses}). Otherwise, if it covers an artefact it
+ *    overlaps, it is acting as a lid: lower it to just above the floor it lies
+ *    on, or to the back of the surface when it lies on bare canvas. Otherwise
+ *    nothing.
  *
  * `siblings` are the OTHER top-level elements of the surface — canvas elements
  * and blocks alike, since the surface paints both by index — with `element`