@formicoidea/labre-core 0.40.0 → 0.42.0

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, #1e96eb)',
+            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/index.d.ts

@@ -1,3 +1,4 @@
+export * from './background-view.js';
 export * from './def.js';
 export * from './facts.js';
 export * from './interaction.js';

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

@@ -1,3 +1,4 @@
+export * from './background-view.js';
 export * from './def.js';
 export * from './facts.js';
 export * from './interaction.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`

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

@@ -61,10 +61,12 @@ export function indexOverBackgrounds(siblings, box) {
  *    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`
@@ -89,18 +91,64 @@ export function indexOverBackgrounds(siblings, box) {
 export function stackingIndexFor(element, siblings) {
     const box = Bound.deserialize(element.xywh);
     const overlapping = siblings.filter(sibling => Bound.deserialize(sibling.xywh).isOverlapWithBound(box));
-    const buried = overlapping.some(sibling => sibling.isBackground && sibling.index > element.index);
+    // The stack {@link indexOverBackgrounds} is allowed to land ON, which is the
+    // same carve-out as `buried`'s applied to the DESTINATION rather than to the
+    // question. The recette of 2026-09-15 needed both halves: a frame buried under
+    // a PEER board is raised, and the depth it was raised to was read off the
+    // unfiltered list — whose topmost overlapping background is the frame's OWN
+    // inner subject. So the sheet cleared the peer and landed just above the thing
+    // drawn on it, which is the very state `encloses` exists to prevent.
+    //
+    // DEMOTED, not removed: what it encloses is not a floor it may stand on, but
+    // it is still something the minted key has to stay UNDER. Dropping those
+    // entries would take the upper bound away with them and `generateKeyBetween`
+    // would append past its own content instead of slotting in below it.
+    const floors = siblings.map(sibling => encloses(element, box, sibling)
+        ? { ...sibling, isBackground: false }
+        : sibling);
+    const buried = overlapping.some(sibling => sibling.isBackground &&
+        sibling.index > element.index &&
+        !encloses(element, box, sibling));
     const lidding = element.isBackground &&
         overlapping.some(sibling => !sibling.isBackground && sibling.index < element.index);
     const next = buried
-        ? indexOverBackgrounds(siblings, box)
+        ? indexOverBackgrounds(floors, box)
         : lidding
             ? // Down to the floor it lies on, or to the back of the surface when
-                // there is none — the depth `createWardleyArea` mints by hand.
-                (indexOverBackgrounds(siblings, box) ?? backOf(siblings))
+                // there is none — the depth `createWardleyArea` mints by hand. The back
+                // is measured against EVERY sibling: "under everything" means under the
+                // content too, enclosed or not.
+                (indexOverBackgrounds(floors, box) ?? backOf(siblings))
             : null;
     return next === element.index ? null : next;
 }
+/**
+ * Whether `element` is the SHEET `sibling` is drawn on — a background that
+ * strictly encloses another background.
+ *
+ * The carve-out the "superposed boards" clause needs, and the recette of
+ * 2026-09-15 is what named it: a UML diagram frame holds inner backgrounds of
+ * its own — a use case subject (§18.1.4), an activity partition (§15.6.4), a
+ * composite state (§14.2.4), a combined fragment (§17.6.4) — and a C4 board
+ * holds boundaries. Every one of them is drawn INSIDE the sheet and therefore
+ * above it, which made the sheet permanently "buried" under its own content:
+ * moving or resizing it raised it just above the topmost background it
+ * overlapped, and when that background was the topmost element of the stack the
+ * opaque sheet went to the very front and hid everything drawn on it.
+ *
+ * Two superposed PEER boards are a different gesture and keep the old answer.
+ * The discriminator is containment and not mere overlap: a sheet is bigger than
+ * what is drawn on it, so `element` is its floor only when it wholly encloses
+ * it AND covers more ground than it. Equal boxes — two boards dropped on the
+ * same spot — enclose each other, which is no statement at all, so they are
+ * peers and the raise still applies.
+ */
+function encloses(element, box, sibling) {
+    if (!element.isBackground)
+        return false;
+    const inner = Bound.deserialize(sibling.xywh);
+    return box.contains(inner) && inner.w * inner.h < box.w * box.h;
+}
 /** A key below every sibling: the back of the surface. */
 function backOf(siblings) {
     const lowest = siblings.reduce((min, sibling) => min === null || sibling.index < min ? sibling.index : min, null);

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

@@ -4,6 +4,7 @@ import type { BlockStdScope } from '../../std/index.js';
 import type { GfxLocalElementModel, GridManager, LayerManager, SurfaceBlockModel, Viewport } from '../../std/gfx/index.js';
 import { Subject } from 'rxjs';
 import type { SurfaceElementModel } from '../element-model/base.js';
+import { RoughCanvas } from '../utils/rough/canvas.js';
 import type { Overlay } from './overlay.js';
 type EnvProvider = {
     generateColorProperty: (color: Color, fallback?: Color) => string;
@@ -131,6 +132,17 @@ export declare class CanvasRenderer {
     dispose(): void;
     generateColorProperty(color: Color, fallback?: Color): string;
     getCanvasByBound(bound?: IBound, surfaceElements?: SurfaceElementModel[], canvas?: HTMLCanvasElement, clearBeforeDrawing?: boolean, withZoom?: boolean): HTMLCanvasElement;
+    /**
+     * Paint `bound` into any 2D context at 1:1 — no device pixel ratio, no zoom.
+     * The SVG export's door: it hands the same element renderers an SVG-emitting
+     * context instead of a canvas one.
+     *
+     * `surfaceElements` is painted in the order given, so a caller that wants the
+     * canvas' z-order passes what `GfxController.getElementsByBound` returned
+     * (already sorted by `layer.compare`). Omitting it falls back to the grid
+     * search, which is NOT layer-ordered.
+     */
+    renderBoundTo(ctx: CanvasRenderingContext2D, rc: RoughCanvas, bound: IBound, surfaceElements?: SurfaceElementModel[]): void;
     getColorScheme(): ColorScheme;
     getColorValue(color: Color, fallback?: Color, real?: boolean): string;
     getPropertyValue(property: string): string;

package/dist/_pkgs/affine-block-surface/renderer/canvas-renderer.js

@@ -527,6 +527,21 @@ export class CanvasRenderer {
         this._renderByBound(ctx, matrix, rc, bound, surfaceElements);
         return canvas;
     }
+    /**
+     * Paint `bound` into any 2D context at 1:1 — no device pixel ratio, no zoom.
+     * The SVG export's door: it hands the same element renderers an SVG-emitting
+     * context instead of a canvas one.
+     *
+     * `surfaceElements` is painted in the order given, so a caller that wants the
+     * canvas' z-order passes what `GfxController.getElementsByBound` returned
+     * (already sorted by `layer.compare`). Omitting it falls back to the grid
+     * search, which is NOT layer-ordered.
+     */
+    renderBoundTo(ctx, rc, bound, surfaceElements) {
+        const matrix = new DOMMatrix();
+        ctx.setTransform(matrix);
+        this._renderByBound(ctx, matrix, rc, bound, surfaceElements);
+    }
     getColorScheme() {
         return this.provider.getColorScheme?.() ?? ColorScheme.Light;
     }