@formicoidea/labre-core 0.37.0 → 0.38.2

package/dist/_pkgs/affine-block-frame/frame-manager.d.ts

@@ -35,6 +35,37 @@ export declare class EdgelessFrameManager extends GfxExtension {
     }>(a: T, b: T): 0 | 1 | -1;
     private _addChildrenToLegacyFrame;
     private _addFrameBlock;
+    /**
+     * The index a frame gets when it is placed at `bound`.
+     *
+     * A frame's index is deliberately at the BACK of the stack, so it renders
+     * behind everything it owns. On a bare canvas that is right. On a framework
+     * board it is not: a Wardley map — a C4 board, a BPMN pool, any
+     * `FrameworkBackgroundElementModel` — is an OPAQUE canvas element, so a
+     * frame sent behind the whole surface goes behind the paint and only the
+     * part overhanging the board stays visible. The back of the SURFACE and the
+     * back of the BOARD are two different depths.
+     *
+     * So the frame lands just above the topmost background it covers, which is
+     * still behind every artefact drawn on that board — the depth a Wardley zone
+     * already needed, for the same reason, in #213. See
+     * {@link indexOverBackgrounds}.
+     */
+    frameIndexAt(bound: Bound): string;
+    /**
+     * A frame DROPPED onto a framework background is raised above it, exactly as
+     * a frame drawn there is ({@link frameIndexAt}) — same gesture, arriving a
+     * moment later.
+     *
+     * Only ever upwards, and only while the frame is actually BELOW a background
+     * it overlaps. So a frame already above one is left alone (a drag writes an
+     * index at most once, and only on the move that buries it), and undo is safe
+     * for the same reason: the restored position is the one the frame came from,
+     * where nothing overlapping was above it. A frame the author sent to the
+     * back on purpose is only raised again if they move it — on a board, moving
+     * a frame means wanting to see it.
+     */
+    private _watchFrameMoved;
     private _watchElementAdded;
     /**
      * Whether `element` fully encloses `frame`.

package/dist/_pkgs/affine-block-frame/frame-manager.js

@@ -1,4 +1,4 @@
-import { Overlay } from '../affine-block-surface/index.js';
+import { indexOverBackgrounds, Overlay, stackedElementsOf, } from '../affine-block-surface/index.js';
 import { FrameworkBackgroundElementModel } from '../affine-model/index.js';
 import { EditPropsStore } from '../affine-shared/services/index.js';
 import { DisposableGroup } from '../global/disposable/index.js';
@@ -100,6 +100,7 @@ export class EdgelessFrameManager extends GfxExtension {
         super(gfx);
         this._disposable = new DisposableGroup();
         this._watchElementAdded();
+        this._watchFrameMoved();
     }
     static framePresentationComparator(a, b) {
         function stringCompare(a, b) {
@@ -145,7 +146,7 @@ export class EdgelessFrameManager extends GfxExtension {
             .applyLastProps('affine:frame', {
             title: new Text(new Y.Text(`Frame ${this.frames.length + 1}`)),
             xywh: bound.serialize(),
-            index: this.gfx.layer.generateIndex(true),
+            index: this.frameIndexAt(bound),
             presentationIndex: this.generatePresentationIndex(),
         });
         const id = this.gfx.doc.addBlock('affine:frame', props, surfaceModel);
@@ -155,6 +156,65 @@ export class EdgelessFrameManager extends GfxExtension {
         }
         return frameModel;
     }
+    /**
+     * The index a frame gets when it is placed at `bound`.
+     *
+     * A frame's index is deliberately at the BACK of the stack, so it renders
+     * behind everything it owns. On a bare canvas that is right. On a framework
+     * board it is not: a Wardley map — a C4 board, a BPMN pool, any
+     * `FrameworkBackgroundElementModel` — is an OPAQUE canvas element, so a
+     * frame sent behind the whole surface goes behind the paint and only the
+     * part overhanging the board stays visible. The back of the SURFACE and the
+     * back of the BOARD are two different depths.
+     *
+     * So the frame lands just above the topmost background it covers, which is
+     * still behind every artefact drawn on that board — the depth a Wardley zone
+     * already needed, for the same reason, in #213. See
+     * {@link indexOverBackgrounds}.
+     */
+    frameIndexAt(bound) {
+        return (indexOverBackgrounds(stackedElementsOf(this.gfx), bound) ??
+            this.gfx.layer.generateIndex(true));
+    }
+    /**
+     * A frame DROPPED onto a framework background is raised above it, exactly as
+     * a frame drawn there is ({@link frameIndexAt}) — same gesture, arriving a
+     * moment later.
+     *
+     * Only ever upwards, and only while the frame is actually BELOW a background
+     * it overlaps. So a frame already above one is left alone (a drag writes an
+     * index at most once, and only on the move that buries it), and undo is safe
+     * for the same reason: the restored position is the one the frame came from,
+     * where nothing overlapping was above it. A frame the author sent to the
+     * back on purpose is only raised again if they move it — on a board, moving
+     * a frame means wanting to see it.
+     */
+    _watchFrameMoved() {
+        this._disposable.add(this.gfx.doc.slots.blockUpdated.subscribe(payload => {
+            if (payload.type !== 'update' ||
+                !payload.isLocal ||
+                payload.flavour !== 'affine:frame' ||
+                payload.props.key !== 'xywh') {
+                return;
+            }
+            const frame = this.gfx.getElementById(payload.id);
+            // A nested frame keeps its parent's ordering: `compare` reads the
+            // ancestor's index, so raising the child would change nothing.
+            if (!frame || !isFrameBlock(frame) || frame.group !== null)
+                return;
+            const siblings = stackedElementsOf(this.gfx, frame);
+            const box = frame.elementBound;
+            const buried = siblings.some(element => element.isBackground &&
+                element.index > frame.index &&
+                Bound.deserialize(element.xywh).isOverlapWithBound(box));
+            if (!buried)
+                return;
+            const over = indexOverBackgrounds(siblings, box);
+            if (over !== null) {
+                this.gfx.updateElement(frame, { index: over });
+            }
+        }));
+    }
     _watchElementAdded() {
         if (!this.gfx.surface) {
             return;

package/dist/_pkgs/affine-block-frame/frame-tool.js

@@ -44,12 +44,16 @@ export class FrameTool extends BaseTool {
             return;
         if (!this._frame) {
             const frames = this.gfx.layer.blocks.filter(block => block.flavour === 'affine:frame');
+            const bound = Bound.fromPoints([this._startPoint, currentPoint]);
             const props = this.std
                 .get(EditPropsStore)
                 .applyLastProps('affine:frame', {
                 title: new Text(new Y.Text(`Frame ${frames.length + 1}`)),
-                xywh: Bound.fromPoints([this._startPoint, currentPoint]).serialize(),
-                index: this.gfx.layer.generateIndex(true),
+                xywh: bound.serialize(),
+                // Not the raw back of the stack: a frame drawn on a framework
+                // background must sit just above it, or the author draws blind
+                // behind an opaque map. See `EdgelessFrameManager.frameIndexAt`.
+                index: this.frameManager.frameIndexAt(bound),
                 presentationIndex: this.frameManager.generatePresentationIndex(),
             });
             const id = this.doc.addBlock('affine:frame', props, this.gfx.surface);

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

@@ -31,7 +31,7 @@ import { getAuditCriteria, requestAudit, TelemetryProvider, } from '../../affine
 import { GfxControllerIdentifier, GfxPrimitiveElementModel, roleIsA, } from '../../std/gfx/index.js';
 import { z } from 'zod';
 import { backgroundInstanceZones, backgroundPlot, } from '../framework-background/def.js';
-import { backgroundAxisFacts } from '../framework-background/facts.js';
+import { backgroundAxisFacts, containingFrame, } from '../framework-background/facts.js';
 import { ValidationManager, ValidationRuleIdentifier, } from './validation.js';
 /**
  * `map.audit` takes no required parameter: the assistant audits what is
@@ -105,6 +105,7 @@ function collectFrames(rules, elements) {
             const profileId = el.validationProfile;
             frames.push({
                 def,
+                id: el.id,
                 bound: el.elementBound,
                 fact: {
                     elementId: el.id,
@@ -135,41 +136,12 @@ function collectFrames(rules, elements) {
     }
     return frames;
 }
-/** Squared edge-to-edge gap — the same attribution heuristic the engine uses. */
-function gapSquared(frame, bound) {
-    const dx = Math.max(frame.x - bound.maxX, bound.x - frame.maxX, 0);
-    const dy = Math.max(frame.y - bound.maxY, bound.y - frame.maxY, 0);
-    return dx * dx + dy * dy;
-}
-/**
- * The frame an element belongs to: the one that CONTAINS it, failing that the
- * nearest by edge-to-edge gap, ties broken by the smaller id.
- *
- * Deliberately the same answer `attributeBackground` gives inside the engine —
- * an audit that attributed an element to a different map than the rule that
- * indicted it would produce two findings about one component that disagree
- * about which map it is on.
- */
-function attribute(bound, frames) {
-    let nearest = null;
-    let nearestDistance = Infinity;
-    for (const frame of frames) {
-        if (frame.bound.contains(bound))
-            return frame;
-        const distance = gapSquared(frame.bound, bound);
-        if (distance < nearestDistance ||
-            (distance === nearestDistance &&
-                nearest !== null &&
-                frame.fact.elementId < nearest.fact.elementId)) {
-            nearestDistance = distance;
-            nearest = frame;
-        }
-    }
-    return nearest;
-}
 /**
  * Where an element's centre sits inside a frame's PLOT, as ratios.
  *
+ * A POSITION, not a membership test: it is asked only about an element some
+ * frame already contains, and answers where in that frame's plot it lies.
+ *
  * Ratios of the plot and not of the element box: a Wardley transition drawn at
  * `0.4` is 40 % of the PLOT, not of the map element, and the margin between the
  * two is exactly where the axis titles live. `backgroundPlot` is the one place
@@ -262,7 +234,13 @@ export function collectAuditFacts(std) {
         if (role === undefined || frameIds.has(el.id))
             continue;
         const bound = el.elementBound;
-        const frame = attribute(bound, frames);
+        // Membership is WHOLE containment (PF2.4), and there is no nearest-frame
+        // fallback: an element straddling the edge of a map is not on it, so the
+        // audit reports it exactly as it reports one on bare canvas — id and role,
+        // no frame, no position, no zone. Anything else would tell an assistant a
+        // component is on a map the engine is simultaneously indicting it for
+        // hanging off.
+        const frame = containingFrame(bound, frames, candidate => candidate.bound);
         if (frame === null) {
             elementFacts.push({ id: el.id, role });
             continue;

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

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

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

@@ -8,7 +8,7 @@ import { effect, signal } from '@preact/signals-core';
 // reading is a one-way read of pure declaration data that must never pull a
 // canvas in.
 import { backgroundPlot, } from '../framework-background/def.js';
-import { backgroundTransitionBands } from '../framework-background/facts.js';
+import { backgroundTransitionBands, containingFrame, } from '../framework-background/facts.js';
 /** Deepest role chain reported by {@link ReadingNodeType.specialises}. */
 const MAX_ROLE_DEPTH = 32;
 /** Numeric slack on the two geometry comparisons. Model units. */
@@ -127,7 +127,7 @@ const centreOf = (bound) => [
     bound.y + bound.h / 2,
 ];
 /**
- * The frame the subject sits ON — containment of its CENTRE, and nothing else.
+ * The frame the subject sits ON — the one that WHOLLY CONTAINS it (PF2.4).
  *
  * Deliberately not the "nearest map" attribution the validation engine uses: a
  * finding has to be filed against some map even when the subject is off in the
@@ -135,40 +135,22 @@ const centreOf = (bound) => [
  * invented fact. A component beside the map has no phase, and the panel says
  * nothing rather than something plausible.
  *
- * The centre, not the whole bound: a node overhanging the edge of the map is
- * still on it to every reader.
+ * The whole bound and not the centre: a node overhanging the edge of the map is
+ * not on it yet, which is what the engine already says about it.
  *
  * ## Two frames under one component
  *
- * The first match in DOCUMENT order wins — not the smallest, not the topmost.
- * Deterministic, and deliberately not clever: z-order is a paint concern and
- * "the smallest frame containing it" is a rule nobody declared. Two overlapping
- * maps of different sizes are a board that has not decided what it is, and a
- * reading that quietly picked one of them by area would be harder to argue with
- * than one that picked the first. The day a framework needs nesting, this is the
- * one function to change.
+ * Ties go to the SMALLER id, which is the tie-break `containingFrame` and the
+ * engine share — one function for one question, and an answer that cannot
+ * depend on the order a `Y.Map` was rebuilt in.
  */
 function frameOf(element, elements, profile) {
     const frame = profile.frame;
     if (!frame)
         return null;
-    const [cx, cy] = centreOf(element.elementBound);
-    for (const candidate of elements) {
-        if (candidate.id === element.id)
-            continue;
-        if (candidate.role === undefined)
-            continue;
-        if (!roleIsA(candidate.role, frame.backgroundRole, profile.roles))
-            continue;
-        const bound = candidate.elementBound;
-        if (cx >= bound.x &&
-            cx <= bound.x + bound.w &&
-            cy >= bound.y &&
-            cy <= bound.y + bound.h) {
-            return candidate;
-        }
-    }
-    return null;
+    return containingFrame(element.elementBound, elements.filter(candidate => candidate.id !== element.id &&
+        candidate.role !== undefined &&
+        roleIsA(candidate.role, frame.backgroundRole, profile.roles)), candidate => candidate.elementBound);
 }
 /**
  * The phase, read from the position and the frame's DECLARED zones.