@formicoidea/labre-core 0.36.0 → 0.38.1

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

@@ -61,6 +61,30 @@ export interface BackgroundAxisFact {
      */
     transitionsVisibleProp?: string;
 }
+/**
+ * The frame that WHOLLY CONTAINS `bound`, or `null` — the one membership test
+ * every reader of a framework board uses (PF2.4).
+ *
+ * An element belongs to a board (a Wardley map, a BPMN pool, a C4 board) only
+ * when it is ENTIRELY inside the board's element bound. Not its centre: a node
+ * hanging over the edge of a map is a node the author has not finished putting
+ * on it, and the validation engine already judges it that way — reading or
+ * auditing it as a member would give two answers about one node.
+ *
+ * The asymmetry with the INNER regions is deliberate: a zone, an evolution
+ * stage, a BPMN lane keeps the centre test, because a band is meant to be
+ * straddled and a board is not.
+ *
+ * `Bound.contains` is inclusive on all four edges, so an element whose bound
+ * EQUALS the board's is a member — the same answer `containingBackground` gives
+ * inside the engine, which is the whole point of having one function.
+ *
+ * Ties go to the smaller id, never to the order a `Y.Map` was rebuilt in: two
+ * overlapping maps must attribute an artefact the same way on every reload.
+ */
+export declare function containingFrame<T extends {
+    id: string;
+}>(bound: Bound, candidates: Iterable<T>, boundOf: (candidate: T) => Bound): T | null;
 /** The declared axes, as facts. Empty for a background that declares none. */
 export declare function backgroundAxisFacts(def: FrameworkBackgroundDef): readonly BackgroundAxisFact[];
 /** The declared axis with this id, as a fact. */

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

@@ -29,6 +29,37 @@ const FORWARD = {
 Object.freeze(FORWARD.horizontal);
 Object.freeze(FORWARD.vertical);
 Object.freeze(FORWARD);
+/**
+ * The frame that WHOLLY CONTAINS `bound`, or `null` — the one membership test
+ * every reader of a framework board uses (PF2.4).
+ *
+ * An element belongs to a board (a Wardley map, a BPMN pool, a C4 board) only
+ * when it is ENTIRELY inside the board's element bound. Not its centre: a node
+ * hanging over the edge of a map is a node the author has not finished putting
+ * on it, and the validation engine already judges it that way — reading or
+ * auditing it as a member would give two answers about one node.
+ *
+ * The asymmetry with the INNER regions is deliberate: a zone, an evolution
+ * stage, a BPMN lane keeps the centre test, because a band is meant to be
+ * straddled and a board is not.
+ *
+ * `Bound.contains` is inclusive on all four edges, so an element whose bound
+ * EQUALS the board's is a member — the same answer `containingBackground` gives
+ * inside the engine, which is the whole point of having one function.
+ *
+ * Ties go to the smaller id, never to the order a `Y.Map` was rebuilt in: two
+ * overlapping maps must attribute an artefact the same way on every reload.
+ */
+export function containingFrame(bound, candidates, boundOf) {
+    let found = null;
+    for (const candidate of candidates) {
+        if (!boundOf(candidate).contains(bound))
+            continue;
+        if (found === null || candidate.id < found.id)
+            found = candidate;
+    }
+    return found;
+}
 /** The declared axes, as facts. Empty for a background that declares none. */
 export function backgroundAxisFacts(def) {
     return (def.axes ?? []).map(axis => ({

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

@@ -3,3 +3,4 @@ export * from './facts.js';
 export * from './interaction.js';
 export * from './labels.js';
 export * from './renderer.js';
+export * from './stacking.js';

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

@@ -3,3 +3,4 @@ export * from './facts.js';
 export * from './interaction.js';
 export * from './labels.js';
 export * from './renderer.js';
+export * from './stacking.js';

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

@@ -0,0 +1,131 @@
+import { Bound } from '../../global/gfx/index.js';
+import { type GfxController, GfxExtension, type GfxModel } from '../../std/gfx/index.js';
+/**
+ * One already-placed element, as {@link indexOverBackgrounds} needs to read it.
+ *
+ * Three fields and no model, so the placement can be reasoned about — and
+ * tested — without a document: what it is, where it is, and how deep. Blocks
+ * and canvas elements both reduce to this, which is what lets a frame (a
+ * block) and a Wardley zone (a canvas element) share one answer.
+ */
+export interface StackedElement {
+    /** Fractional index. Sorts lexicographically, which IS the paint order. */
+    index: string;
+    /** Serialized box. */
+    xywh: string;
+    /** Whether this is a framework BACKGROUND — a map, a pool, a C4 board… */
+    isBackground: boolean;
+}
+/**
+ * How deep something drawn ON a framework board goes: just ABOVE the
+ * backgrounds it covers, and below everything else. `null` means the back of
+ * the surface.
+ *
+ * "The back" alone was the first answer and it was wrong, as the recette of
+ * #213 found: a Wardley map is a framework BACKGROUND — an opaque one — so an
+ * element sent behind the whole surface went behind the map and vanished. What
+ * it must be under is the artefacts it groups; what it must be over is the
+ * canvas they are drawn on. Those are two different depths, and only the first
+ * one is "the back".
+ *
+ * So: find the topmost background the box actually OVERLAPS — the map it was
+ * drawn on, and not some other framework's board parked elsewhere on the same
+ * canvas — and mint a key between it and whatever sits directly above it. With
+ * no background under it at all there is nothing to clear, and the back of the
+ * surface is right again.
+ *
+ * Two callers want exactly this depth, for the same reason. A Wardley zone is
+ * a wash over the components it names, so it is lowered — but not past the map
+ * (#213). A frame is a container that renders behind everything it owns, so it
+ * too is lowered — and it too vanished under the map. Same problem, same
+ * answer, one function.
+ *
+ * `siblings` need not be sorted: fractional indexes sort lexicographically, so
+ * this sorts them itself and reads the paint order straight off the strings.
+ */
+export declare function indexOverBackgrounds(siblings: readonly StackedElement[], box: Bound): string | null;
+/**
+ * Where a top-level element belongs in the stack, once the rule "a framework
+ * background is a FLOOR, never a lid" is applied. `null` means "leave it
+ * alone".
+ *
+ * ## The rule
+ *
+ * A background is the canvas the user draws ON. It must therefore stay under
+ * everything that overlaps it, and boards must still be able to overlap each
+ * other — a board dropped on a board is a cross-reading, not a mistake. Two
+ * cases, and they are the same sentence read from either side:
+ *
+ * 1. `element` is NOT a background — a shape, a node, a foreign framework's
+ *    artefact. If a background it overlaps sits ABOVE it, it has been buried:
+ *    raise it just above that background ({@link indexOverBackgrounds}), which
+ *    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.
+ *
+ * `siblings` are the OTHER top-level elements of the surface — canvas elements
+ * and blocks alike, since the surface paints both by index — with `element`
+ * itself removed. Nested elements are left out by the caller: a group's child
+ * is ordered by its ancestor's index, so moving it would change nothing.
+ *
+ * ## Idempotence, which is what makes undo safe
+ *
+ * The function never returns the index the element already has, so a second
+ * call about the same element on an unchanged board answers `null`: the rule
+ * has a fixed point and reaches it in one step. It answers about the element
+ * the user just placed or moved, and about that one only — which is what makes
+ * two superposed boards settle in the order the gestures happened rather than
+ * in some order the surface would have to arbitrate.
+ *
+ * That is the whole undo/redo argument, and it restates the frame manager's
+ * (`_watchFrameMoved`, #223): an index restored by undo is one the rule had
+ * already accepted when it was written, so replaying the rule over a restored
+ * state writes nothing — no corrupted depth, and no extra entry pushed onto
+ * the history stack.
+ */
+export declare function stackingIndexFor(element: StackedElement, siblings: readonly StackedElement[]): string | null;
+/**
+ * The top-level elements of a surface as {@link StackedElement}s — blocks as
+ * well as canvas elements, since the surface paints both by index — minus the
+ * one being placed.
+ *
+ * Read off `gfx.layer.layers` because that is the list the canvas draws from,
+ * and shared because both callers of the depth rules need exactly this list:
+ * the frame manager (#223) and {@link BackgroundStackingExtension}.
+ */
+export declare function stackedElementsOf(gfx: GfxController, exclude?: GfxModel): StackedElement[];
+/**
+ * Keeps {@link stackingIndexFor}'s rule true on a live surface: a framework
+ * background is a floor, never a lid — whatever framework it belongs to, and
+ * whichever of the two elements arrived first.
+ *
+ * ENGINE behaviour, not tooling, so it is registered unconditionally: a board
+ * whose framework flag is off still has to sit under what the user drops on it
+ * (`docs/adr/0009`).
+ *
+ * Two gestures produce a wrong depth, and they are the two this listens for:
+ * an element CREATED (every creation site mints the top of the stack, so a
+ * board drawn last covers what it was drawn around) and an element MOVED (onto
+ * a board that is above it, or over free elements it then hides). Anything
+ * else — a resize, a colour, a rename — cannot change who covers whom.
+ *
+ * Frames are BLOCKS: their own two gestures are already handled, at creation
+ * by `frameIndexAt` and on a move by `_watchFrameMoved` (#223), so this never
+ * writes a frame's index. They are read as siblings all the same — a board
+ * lowered under a frame must go under the frame.
+ *
+ * A remote change is ignored: the client that made it ran this same rule and
+ * synced the index it decided on. Applying it again here would be a second
+ * writer for one gesture.
+ */
+export declare class BackgroundStackingExtension extends GfxExtension {
+    static key: string;
+    private readonly _disposable;
+    constructor(gfx: GfxController);
+    private _restack;
+    unmounted(): void;
+}

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

@@ -0,0 +1,184 @@
+import { FrameworkBackgroundElementModel } from '../../affine-model/index.js';
+import { DisposableGroup } from '../../global/disposable/index.js';
+import { Bound } from '../../global/gfx/index.js';
+import { generateKeyBetween, GfxExtension, } from '../../std/gfx/index.js';
+/**
+ * How deep something drawn ON a framework board goes: just ABOVE the
+ * backgrounds it covers, and below everything else. `null` means the back of
+ * the surface.
+ *
+ * "The back" alone was the first answer and it was wrong, as the recette of
+ * #213 found: a Wardley map is a framework BACKGROUND — an opaque one — so an
+ * element sent behind the whole surface went behind the map and vanished. What
+ * it must be under is the artefacts it groups; what it must be over is the
+ * canvas they are drawn on. Those are two different depths, and only the first
+ * one is "the back".
+ *
+ * So: find the topmost background the box actually OVERLAPS — the map it was
+ * drawn on, and not some other framework's board parked elsewhere on the same
+ * canvas — and mint a key between it and whatever sits directly above it. With
+ * no background under it at all there is nothing to clear, and the back of the
+ * surface is right again.
+ *
+ * Two callers want exactly this depth, for the same reason. A Wardley zone is
+ * a wash over the components it names, so it is lowered — but not past the map
+ * (#213). A frame is a container that renders behind everything it owns, so it
+ * too is lowered — and it too vanished under the map. Same problem, same
+ * answer, one function.
+ *
+ * `siblings` need not be sorted: fractional indexes sort lexicographically, so
+ * this sorts them itself and reads the paint order straight off the strings.
+ */
+export function indexOverBackgrounds(siblings, box) {
+    const stack = [...siblings].sort((a, b) => a.index < b.index ? -1 : a.index > b.index ? 1 : 0);
+    // The LAST match, which is the topmost: a board with two maps on it gets the
+    // element above the one it is actually drawn over, whichever was drawn first.
+    const under = stack.reduce((found, element, at) => element.isBackground &&
+        Bound.deserialize(element.xywh).isOverlapWithBound(box)
+        ? at
+        : found, -1);
+    if (under < 0)
+        return null;
+    // `null` for the upper bound when the background is the topmost element
+    // there is — `generateKeyBetween` reads that as "append after".
+    return generateKeyBetween(stack[under].index, stack[under + 1]?.index ?? null);
+}
+/**
+ * Where a top-level element belongs in the stack, once the rule "a framework
+ * background is a FLOOR, never a lid" is applied. `null` means "leave it
+ * alone".
+ *
+ * ## The rule
+ *
+ * A background is the canvas the user draws ON. It must therefore stay under
+ * everything that overlaps it, and boards must still be able to overlap each
+ * other — a board dropped on a board is a cross-reading, not a mistake. Two
+ * cases, and they are the same sentence read from either side:
+ *
+ * 1. `element` is NOT a background — a shape, a node, a foreign framework's
+ *    artefact. If a background it overlaps sits ABOVE it, it has been buried:
+ *    raise it just above that background ({@link indexOverBackgrounds}), which
+ *    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.
+ *
+ * `siblings` are the OTHER top-level elements of the surface — canvas elements
+ * and blocks alike, since the surface paints both by index — with `element`
+ * itself removed. Nested elements are left out by the caller: a group's child
+ * is ordered by its ancestor's index, so moving it would change nothing.
+ *
+ * ## Idempotence, which is what makes undo safe
+ *
+ * The function never returns the index the element already has, so a second
+ * call about the same element on an unchanged board answers `null`: the rule
+ * has a fixed point and reaches it in one step. It answers about the element
+ * the user just placed or moved, and about that one only — which is what makes
+ * two superposed boards settle in the order the gestures happened rather than
+ * in some order the surface would have to arbitrate.
+ *
+ * That is the whole undo/redo argument, and it restates the frame manager's
+ * (`_watchFrameMoved`, #223): an index restored by undo is one the rule had
+ * already accepted when it was written, so replaying the rule over a restored
+ * state writes nothing — no corrupted depth, and no extra entry pushed onto
+ * the history stack.
+ */
+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);
+    const lidding = element.isBackground &&
+        overlapping.some(sibling => !sibling.isBackground && sibling.index < element.index);
+    const next = buried
+        ? indexOverBackgrounds(siblings, 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))
+            : null;
+    return next === element.index ? null : next;
+}
+/** 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);
+    return lowest === null ? null : generateKeyBetween(null, lowest);
+}
+/**
+ * The top-level elements of a surface as {@link StackedElement}s — blocks as
+ * well as canvas elements, since the surface paints both by index — minus the
+ * one being placed.
+ *
+ * Read off `gfx.layer.layers` because that is the list the canvas draws from,
+ * and shared because both callers of the depth rules need exactly this list:
+ * the frame manager (#223) and {@link BackgroundStackingExtension}.
+ */
+export function stackedElementsOf(gfx, exclude) {
+    return gfx.layer.layers.reduce((all, layer) => all.concat(layer.elements
+        .filter(element => element.group === null && element !== exclude)
+        .map(element => ({
+        index: element.index,
+        xywh: element.xywh,
+        isBackground: element instanceof FrameworkBackgroundElementModel,
+    }))), []);
+}
+/**
+ * Keeps {@link stackingIndexFor}'s rule true on a live surface: a framework
+ * background is a floor, never a lid — whatever framework it belongs to, and
+ * whichever of the two elements arrived first.
+ *
+ * ENGINE behaviour, not tooling, so it is registered unconditionally: a board
+ * whose framework flag is off still has to sit under what the user drops on it
+ * (`docs/adr/0009`).
+ *
+ * Two gestures produce a wrong depth, and they are the two this listens for:
+ * an element CREATED (every creation site mints the top of the stack, so a
+ * board drawn last covers what it was drawn around) and an element MOVED (onto
+ * a board that is above it, or over free elements it then hides). Anything
+ * else — a resize, a colour, a rename — cannot change who covers whom.
+ *
+ * Frames are BLOCKS: their own two gestures are already handled, at creation
+ * by `frameIndexAt` and on a move by `_watchFrameMoved` (#223), so this never
+ * writes a frame's index. They are read as siblings all the same — a board
+ * lowered under a frame must go under the frame.
+ *
+ * A remote change is ignored: the client that made it ran this same rule and
+ * synced the index it decided on. Applying it again here would be a second
+ * writer for one gesture.
+ */
+export class BackgroundStackingExtension extends GfxExtension {
+    static { this.key = 'background-stacking'; }
+    constructor(gfx) {
+        super(gfx);
+        this._disposable = new DisposableGroup();
+        const surface = gfx.surface;
+        if (!surface)
+            return;
+        this._disposable.add(surface.elementAdded.subscribe(({ id, local }) => {
+            if (local)
+                this._restack(surface.getElementById(id));
+        }));
+        this._disposable.add(surface.elementUpdated.subscribe(({ id, props, local }) => {
+            if (local && props['xywh'])
+                this._restack(surface.getElementById(id));
+        }));
+    }
+    _restack(model) {
+        // A nested element is ordered by its ancestor's index — `compare` reads
+        // that and ignores the child's own, so restacking it would change nothing.
+        if (!model || model.group !== null)
+            return;
+        const index = stackingIndexFor({
+            index: model.index,
+            xywh: model.xywh,
+            isBackground: model instanceof FrameworkBackgroundElementModel,
+        }, stackedElementsOf(this.gfx, model));
+        if (index !== null)
+            this.gfx.updateElement(model, { index });
+    }
+    unmounted() {
+        this._disposable.dispose();
+    }
+}

package/dist/_pkgs/affine-block-surface/utils/sort.d.ts

@@ -2,6 +2,20 @@ export declare function loadingSort<T extends {
     id: string;
     deps: string[];
 }>(elements: T[]): T[];
+/**
+ * Paint order of two serialized elements, group-aware to ANY depth.
+ *
+ * `groupIndexMap` maps a child id to its parent group's `{ id, index }`. An
+ * element's position is the chain of indexes from its outermost group down to
+ * itself, and two chains compare lexicographically — the same order the live
+ * layer's `compare` derives from the group tree. A group is a strict prefix of
+ * its children's chains, so it sorts before them.
+ *
+ * It used to look ONE level up only, which made the comparator cyclic on a
+ * group inside a group (a leaf of the outer group, a leaf of the inner one and
+ * the inner group itself had no consistent order) — and `Array.sort` on a
+ * cyclic comparator returns whatever it likes.
+ */
 export declare function sortIndex(a: {
     id: string;
     index: string;
@@ -11,4 +25,4 @@ export declare function sortIndex(a: {
 }, groupIndexMap: Map<string, {
     id: string;
     index: string;
-}>): 0 | 1 | -1;
+}>): number;

package/dist/_pkgs/affine-block-surface/utils/sort.js

@@ -38,37 +38,36 @@ export function loadingSort(elements) {
     }
     return sortedOrder.map(id => map.get(id));
 }
+/**
+ * Paint order of two serialized elements, group-aware to ANY depth.
+ *
+ * `groupIndexMap` maps a child id to its parent group's `{ id, index }`. An
+ * element's position is the chain of indexes from its outermost group down to
+ * itself, and two chains compare lexicographically — the same order the live
+ * layer's `compare` derives from the group tree. A group is a strict prefix of
+ * its children's chains, so it sorts before them.
+ *
+ * It used to look ONE level up only, which made the comparator cyclic on a
+ * group inside a group (a leaf of the outer group, a leaf of the inner one and
+ * the inner group itself had no consistent order) — and `Array.sort` on a
+ * cyclic comparator returns whatever it likes.
+ */
 export function sortIndex(a, b, groupIndexMap) {
-    const aGroupIndex = groupIndexMap.get(a.id);
-    const bGroupIndex = groupIndexMap.get(b.id);
-    if (aGroupIndex && bGroupIndex) {
-        return aGroupIndex.id === bGroupIndex.id
-            ? a.index === b.index
-                ? 0
-                : a.index > b.index
-                    ? 1
-                    : -1
-            : aGroupIndex.index > bGroupIndex.index
-                ? 1
-                : -1;
-    }
-    if (aGroupIndex) {
-        return aGroupIndex.id === b.id
-            ? 1
-            : aGroupIndex.index === b.index
-                ? 0
-                : aGroupIndex.index > b.index
-                    ? 1
-                    : -1;
-    }
-    if (bGroupIndex) {
-        return a.id === bGroupIndex.id
-            ? -1
-            : a.index === bGroupIndex.index
-                ? 0
-                : a.index > bGroupIndex.index
-                    ? 1
-                    : -1;
+    const chainOf = (el) => {
+        const chain = [el.index];
+        const seen = new Set([el.id]);
+        for (let group = groupIndexMap.get(el.id); group && !seen.has(group.id); group = groupIndexMap.get(group.id)) {
+            seen.add(group.id);
+            chain.unshift(group.index);
+        }
+        return chain;
+    };
+    const ca = chainOf(a);
+    const cb = chainOf(b);
+    const depth = Math.min(ca.length, cb.length);
+    for (let i = 0; i < depth; i++) {
+        if (ca[i] !== cb[i])
+            return ca[i] > cb[i] ? 1 : -1;
     }
-    return a.index === b.index ? 0 : a.index > b.index ? 1 : -1;
+    return ca.length - cb.length;
 }

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

@@ -4,6 +4,7 @@ import { literal } from 'lit/static-html.js';
 import { effects } from './effects.js';
 import { auditCommands, EdgelessCRUDExtension, EdgelessLegacySlotExtension, EditPropsMiddlewareBuilder, mapQualityCommands, mapQualityWidget, ReadingManager, readingProposalWidget, readingToolbarExtension, SpotlightManager, ValidationManager, validationExceptionToolbarExtension, ValidationOverlay, violationDetailWidget, } from './extensions/index.js';
 import { ExportManagerExtension } from './extensions/export-manager/export-manager.js';
+import { BackgroundStackingExtension } from './framework-background/stacking.js';
 import { ElementHighlightOverlay } from './renderer/element-highlight-overlay.js';
 import { DefaultTool } from './tool/default-tool.js';
 export class SurfaceViewExtension extends ViewExtensionProvider {
@@ -31,6 +32,10 @@ export class SurfaceViewExtension extends ViewExtensionProvider {
             // too — embedded read-only windows are the API's primary consumer — and
             // paints nothing until a host asks for a highlight.
             context.register(ElementHighlightOverlay);
+            // "A framework background is a floor, never a lid" — engine behaviour,
+            // so it is registered unconditionally, like the frame manager it mirrors
+            // (`docs/adr/0009`: a flag gates tooling, never what a board does).
+            context.register(BackgroundStackingExtension);
             // No-op until a framework registers a SpotlightHostExtension.
             context.register(SpotlightManager);
             // No-op until a framework registers a ValidationRuleExtension — which

package/dist/_pkgs/affine-gfx-group/element-renderer/utils.js

@@ -3,7 +3,9 @@ import { FontWeight } from '../../affine-model/index.js';
 import { Bound } from '../../global/gfx/index.js';
 import { GROUP_TITLE_FONT, GROUP_TITLE_FONT_SIZE, GROUP_TITLE_OFFSET, GROUP_TITLE_PADDING, } from './consts.js';
 export function titleRenderParams(group, zoom) {
-    let text = group.title.toString().trim();
+    // A group loaded without a title (older documents, hand-written templates)
+    // must not take the whole canvas down with it.
+    let text = (group.title?.toString() ?? '').trim();
     const font = getGroupTitleFont(zoom);
     const lineWidth = getLineWidth(text, font);
     const lineHeight = getLineHeight(GROUP_TITLE_FONT, GROUP_TITLE_FONT_SIZE / zoom, 'normal');

package/dist/_pkgs/affine-gfx-template/index.d.ts

@@ -1,6 +1,7 @@
 export * from './contribute.js';
 export * from './make-snapshot.js';
 export * from './services/template.js';
+export * from './snapshot-from-action.js';
 export * from './template-tool.js';
 export * from './toolbar/senior-tool.js';
 export * from './toolbar/template-panel.js';

package/dist/_pkgs/affine-gfx-template/index.js

@@ -1,6 +1,7 @@
 export * from './contribute.js';
 export * from './make-snapshot.js';
 export * from './services/template.js';
+export * from './snapshot-from-action.js';
 export * from './template-tool.js';
 export * from './toolbar/senior-tool.js';
 export * from './toolbar/template-panel.js';

package/dist/_pkgs/affine-gfx-template/make-snapshot.d.ts

@@ -12,11 +12,25 @@ export declare function surfaceText(text: string): {
         insert: string;
     }[];
 };
+/**
+ * Serialize a plain record into the surface `Y.Map` JSON form used inside
+ * snapshots — a group's `children`, a mindmap's node table. Same seam as
+ * {@link surfaceText}: what `SurfaceBlockTransformer.toSnapshot` emits.
+ */
+export declare function surfaceYMap(json: Record<string, unknown>): {
+    "affine:surface:ymap": boolean;
+    json: Record<string, unknown>;
+};
 /**
  * Wrap a surface-elements map into the minimal `page → surface` DocSnapshot a
  * template's `content` expects. Block/element ids are remapped on insert by the
- * template job's `replaceIdMiddleware`, and z-order indices are regenerated, so
- * callers only need stable-within-snapshot ids and meaningful element props.
+ * template job's `replaceIdMiddleware`.
+ *
+ * Z-order indices are regenerated on insert too, but IN THE SNAPSHOT'S OWN
+ * ORDER: `createRegenerateIndexMiddleware` sorts the elements by their `index`
+ * (group-aware) and only then mints fresh keys — and it skips any element that
+ * carries no `index` at all. So a missing `index` is filled in here, in key
+ * (insertion) order, which is the order a creation action added the elements.
  */
 export declare function makeTemplateSnapshot(elements: SurfaceElementsJSON, title?: string): {
     type: string;

package/dist/_pkgs/affine-gfx-template/make-snapshot.js

@@ -1,4 +1,4 @@
-import { SURFACE_TEXT_UNIQ_IDENTIFIER } from '../std/gfx/index.js';
+import { generateKeyBetween, SURFACE_TEXT_UNIQ_IDENTIFIER, SURFACE_YMAP_UNIQ_IDENTIFIER, } from '../std/gfx/index.js';
 /**
  * Serialize a plain string into the surface `Y.Text` JSON form used inside
  * snapshots (the shape inner-text / label field). Mirrors what
@@ -11,13 +11,52 @@ export function surfaceText(text) {
         delta: text ? [{ insert: text }] : [],
     };
 }
+/**
+ * Serialize a plain record into the surface `Y.Map` JSON form used inside
+ * snapshots — a group's `children`, a mindmap's node table. Same seam as
+ * {@link surfaceText}: what `SurfaceBlockTransformer.toSnapshot` emits.
+ */
+export function surfaceYMap(json) {
+    return {
+        [SURFACE_YMAP_UNIQ_IDENTIFIER]: true,
+        json,
+    };
+}
 /**
  * Wrap a surface-elements map into the minimal `page → surface` DocSnapshot a
  * template's `content` expects. Block/element ids are remapped on insert by the
- * template job's `replaceIdMiddleware`, and z-order indices are regenerated, so
- * callers only need stable-within-snapshot ids and meaningful element props.
+ * template job's `replaceIdMiddleware`.
+ *
+ * Z-order indices are regenerated on insert too, but IN THE SNAPSHOT'S OWN
+ * ORDER: `createRegenerateIndexMiddleware` sorts the elements by their `index`
+ * (group-aware) and only then mints fresh keys — and it skips any element that
+ * carries no `index` at all. So a missing `index` is filled in here, in key
+ * (insertion) order, which is the order a creation action added the elements.
  */
 export function makeTemplateSnapshot(elements, title = 'Template') {
+    const indexed = {};
+    let last = null;
+    for (const [id, element] of Object.entries(elements)) {
+        const copy = { ...element };
+        // The middleware keys its fresh indexes by the element's OWN `id` field,
+        // not by the map key: a hand-written element without one would collect
+        // every other element's key under `undefined` and land at one shared depth.
+        if (copy['id'] === undefined)
+            copy['id'] = id;
+        // A group's title is a Y.Text the model initialises at creation and reads
+        // back unguarded when it paints (`group.title.toString()`): a group written
+        // without one lands with no key at all, and the renderer threw on every
+        // frame — the inserted map showed its background and nothing else
+        // (recette of 09/09/2026).
+        if (copy['type'] === 'group' && copy['title'] === undefined) {
+            copy['title'] = surfaceText('');
+        }
+        if (copy['index'] === undefined) {
+            last = generateKeyBetween(last, null);
+            copy['index'] = last;
+        }
+        indexed[id] = copy;
+    }
     return {
         type: 'page',
         meta: {
@@ -41,7 +80,7 @@ export function makeTemplateSnapshot(elements, title = 'Template') {
                     type: 'block',
                     id: 'block:template-surface',
                     flavour: 'affine:surface',
-                    props: { elements },
+                    props: { elements: indexed },
                     children: [],
                 },
             ],

package/dist/_pkgs/affine-gfx-template/services/template-middlewares.js

@@ -35,6 +35,7 @@ export const replaceIdMiddleware = (job) => {
                 regeneratedIdMap.set(id, newId);
                 val.id = newId;
                 elements[newId] = val;
+                job.insertedElementIds.push(newId);
                 if (['connector', 'group', 'mindmap'].includes(val['type'])) {
                     defered.push(newId);
                 }