@formicoidea/labre-core 0.42.0 → 0.45.0

package/dist/_pkgs/std/gfx/model/surface/element-model.d.ts

@@ -11,6 +11,10 @@ export type BaseElementProps = {
     index: string;
     seed: number;
     lockedBySelf?: boolean;
+    /** See {@link GfxPrimitiveElementModel.hiddenForEveryone}. */
+    hiddenForEveryone?: true;
+    /** See {@link GfxPrimitiveElementModel.layer}. */
+    layer?: string;
     /** See {@link GfxPrimitiveElementModel.pivotDocId}. */
     pivotDocId?: string;
     /** See {@link GfxPrimitiveElementModel.role}. */
@@ -252,6 +256,29 @@ export declare abstract class GfxPrimitiveElementModel<Props extends BaseElement
      */
     accessor externalXYWH: SerializedXYWH | undefined;
     accessor hidden: boolean;
+    /**
+     * "Hide for everyone" (ADR 0031 §7): stored, synced, and NOT {@link hidden},
+     * which mindmap collapse owns and clears on expand — expanding a branch must
+     * never unhide what somebody hid for everyone.
+     *
+     * `true` or absent, never `false`: unhiding goes through {@link clearField},
+     * which removes the key, so a document goes back to byte-identical. Declared
+     * on the BASE class for the reason {@link role} is: an element re-created
+     * from props (paste, duplicate, template) reaches the Y.Map only through
+     * declared keys. Read by the paint and pick predicate
+     * (`GfxController.hiddenForEveryone`), never by `grid.search`: rules,
+     * legends and semantic exports still count a hidden element.
+     */
+    accessor hiddenForEveryone: true | undefined;
+    /**
+     * The user layer this element belongs to (ADR 0031 §3): a key of the
+     * surface's `layers`, or `undefined` for the default layer — never the
+     * string `'@default'`. A dangling id reads as the default layer and is never
+     * dropped. Ignored while the element is inside a group or a mindmap: the
+     * outermost one's `layer` decides. Declared on the BASE class for the reason
+     * {@link role} is. Clearing goes through {@link clearField}.
+     */
+    accessor layer: string | undefined;
     accessor index: string;
     /**
      * Minimal link target attached to the element. At most one is set.
@@ -590,6 +617,13 @@ export declare abstract class GfxGroupLikeElementModel<Props extends BaseElement
      */
     setChildIds(value: string[], fromLocal: boolean): void;
 }
+/**
+ * Whether `model` itself carries the stored "hide for everyone" (ADR 0031 §7):
+ * the `@field()` on an element, the `prop:` on a gfx block. Not reactive, and
+ * not inherited — a member of a hidden group answers `false` here; the paint
+ * and pick predicate (`GfxLocalVisibility.isHidden`) walks the ancestors.
+ */
+export declare function isStoredHiddenForEveryone(model: unknown): boolean;
 export declare function syncElementFromY(model: GfxPrimitiveElementModel, callback: (payload: {
     props: Record<string, unknown>;
     oldValues: Record<string, unknown>;

package/dist/_pkgs/std/gfx/model/surface/element-model.js

@@ -105,6 +105,12 @@ let GfxPrimitiveElementModel = (() => {
     let _hidden_decorators;
     let _hidden_initializers = [];
     let _hidden_extraInitializers = [];
+    let _hiddenForEveryone_decorators;
+    let _hiddenForEveryone_initializers = [];
+    let _hiddenForEveryone_extraInitializers = [];
+    let _layer_decorators;
+    let _layer_initializers = [];
+    let _layer_extraInitializers = [];
     let _index_decorators;
     let _index_initializers = [];
     let _index_extraInitializers = [];
@@ -155,6 +161,8 @@ let GfxPrimitiveElementModel = (() => {
                     instance['_local'].delete('externalBound');
                 }), local()];
             _hidden_decorators = [field(false)];
+            _hiddenForEveryone_decorators = [field()];
+            _layer_decorators = [field()];
             _index_decorators = [field()];
             _externalLink_decorators = [field()];
             _linkedDocId_decorators = [field()];
@@ -172,6 +180,8 @@ let GfxPrimitiveElementModel = (() => {
             __esDecorate(this, null, _display_decorators, { kind: "accessor", name: "display", static: false, private: false, access: { has: obj => "display" in obj, get: obj => obj.display, set: (obj, value) => { obj.display = value; } }, metadata: _metadata }, _display_initializers, _display_extraInitializers);
             __esDecorate(this, null, _externalXYWH_decorators, { kind: "accessor", name: "externalXYWH", static: false, private: false, access: { has: obj => "externalXYWH" in obj, get: obj => obj.externalXYWH, set: (obj, value) => { obj.externalXYWH = value; } }, metadata: _metadata }, _externalXYWH_initializers, _externalXYWH_extraInitializers);
             __esDecorate(this, null, _hidden_decorators, { kind: "accessor", name: "hidden", static: false, private: false, access: { has: obj => "hidden" in obj, get: obj => obj.hidden, set: (obj, value) => { obj.hidden = value; } }, metadata: _metadata }, _hidden_initializers, _hidden_extraInitializers);
+            __esDecorate(this, null, _hiddenForEveryone_decorators, { kind: "accessor", name: "hiddenForEveryone", static: false, private: false, access: { has: obj => "hiddenForEveryone" in obj, get: obj => obj.hiddenForEveryone, set: (obj, value) => { obj.hiddenForEveryone = value; } }, metadata: _metadata }, _hiddenForEveryone_initializers, _hiddenForEveryone_extraInitializers);
+            __esDecorate(this, null, _layer_decorators, { kind: "accessor", name: "layer", static: false, private: false, access: { has: obj => "layer" in obj, get: obj => obj.layer, set: (obj, value) => { obj.layer = value; } }, metadata: _metadata }, _layer_initializers, _layer_extraInitializers);
             __esDecorate(this, null, _index_decorators, { kind: "accessor", name: "index", static: false, private: false, access: { has: obj => "index" in obj, get: obj => obj.index, set: (obj, value) => { obj.index = value; } }, metadata: _metadata }, _index_initializers, _index_extraInitializers);
             __esDecorate(this, null, _externalLink_decorators, { kind: "accessor", name: "externalLink", static: false, private: false, access: { has: obj => "externalLink" in obj, get: obj => obj.externalLink, set: (obj, value) => { obj.externalLink = value; } }, metadata: _metadata }, _externalLink_initializers, _externalLink_extraInitializers);
             __esDecorate(this, null, _linkedDocId_decorators, { kind: "accessor", name: "linkedDocId", static: false, private: false, access: { has: obj => "linkedDocId" in obj, get: obj => obj.linkedDocId, set: (obj, value) => { obj.linkedDocId = value; } }, metadata: _metadata }, _linkedDocId_initializers, _linkedDocId_extraInitializers);
@@ -261,7 +271,9 @@ let GfxPrimitiveElementModel = (() => {
             this.#display_accessor_storage = __runInitializers(this, _display_initializers, true);
             this.#externalXYWH_accessor_storage = (__runInitializers(this, _display_extraInitializers), __runInitializers(this, _externalXYWH_initializers, undefined));
             this.#hidden_accessor_storage = (__runInitializers(this, _externalXYWH_extraInitializers), __runInitializers(this, _hidden_initializers, false));
-            this.#index_accessor_storage = (__runInitializers(this, _hidden_extraInitializers), __runInitializers(this, _index_initializers, void 0));
+            this.#hiddenForEveryone_accessor_storage = (__runInitializers(this, _hidden_extraInitializers), __runInitializers(this, _hiddenForEveryone_initializers, undefined));
+            this.#layer_accessor_storage = (__runInitializers(this, _hiddenForEveryone_extraInitializers), __runInitializers(this, _layer_initializers, undefined));
+            this.#index_accessor_storage = (__runInitializers(this, _layer_extraInitializers), __runInitializers(this, _index_initializers, void 0));
             this.#externalLink_accessor_storage = (__runInitializers(this, _index_extraInitializers), __runInitializers(this, _externalLink_initializers, undefined));
             this.#linkedDocId_accessor_storage = (__runInitializers(this, _externalLink_extraInitializers), __runInitializers(this, _linkedDocId_initializers, undefined));
             this.#pivotDocId_accessor_storage = (__runInitializers(this, _linkedDocId_extraInitializers), __runInitializers(this, _pivotDocId_initializers, undefined));
@@ -463,6 +475,33 @@ let GfxPrimitiveElementModel = (() => {
         #hidden_accessor_storage;
         get hidden() { return this.#hidden_accessor_storage; }
         set hidden(value) { this.#hidden_accessor_storage = value; }
+        #hiddenForEveryone_accessor_storage;
+        /**
+         * "Hide for everyone" (ADR 0031 §7): stored, synced, and NOT {@link hidden},
+         * which mindmap collapse owns and clears on expand — expanding a branch must
+         * never unhide what somebody hid for everyone.
+         *
+         * `true` or absent, never `false`: unhiding goes through {@link clearField},
+         * which removes the key, so a document goes back to byte-identical. Declared
+         * on the BASE class for the reason {@link role} is: an element re-created
+         * from props (paste, duplicate, template) reaches the Y.Map only through
+         * declared keys. Read by the paint and pick predicate
+         * (`GfxController.hiddenForEveryone`), never by `grid.search`: rules,
+         * legends and semantic exports still count a hidden element.
+         */
+        get hiddenForEveryone() { return this.#hiddenForEveryone_accessor_storage; }
+        set hiddenForEveryone(value) { this.#hiddenForEveryone_accessor_storage = value; }
+        #layer_accessor_storage;
+        /**
+         * The user layer this element belongs to (ADR 0031 §3): a key of the
+         * surface's `layers`, or `undefined` for the default layer — never the
+         * string `'@default'`. A dangling id reads as the default layer and is never
+         * dropped. Ignored while the element is inside a group or a mindmap: the
+         * outermost one's `layer` decides. Declared on the BASE class for the reason
+         * {@link role} is. Clearing goes through {@link clearField}.
+         */
+        get layer() { return this.#layer_accessor_storage; }
+        set layer(value) { this.#layer_accessor_storage = value; }
         #index_accessor_storage;
         get index() { return this.#index_accessor_storage; }
         set index(value) { this.#index_accessor_storage = value; }
@@ -844,6 +883,12 @@ export class GfxGroupLikeElementModel extends GfxPrimitiveElementModel {
             if (child instanceof GfxPrimitiveElementModel && child.hidden) {
                 return;
             }
+            // A member hidden for everyone is not painted, so it does not stretch
+            // the group's box either (ADR 0031 §9). A local hide does: the bound is
+            // computed once for every viewer.
+            if (isStoredHiddenForEveryone(child)) {
+                return;
+            }
             bound = bound ? bound.unite(child.elementBound) : child.elementBound;
         });
         return bound ?? new Bound(0, 0, 0, 0);
@@ -902,6 +947,25 @@ export class GfxGroupLikeElementModel extends GfxPrimitiveElementModel {
         });
     }
 }
+/**
+ * Whether `model` itself carries the stored "hide for everyone" (ADR 0031 §7):
+ * the `@field()` on an element, the `prop:` on a gfx block. Not reactive, and
+ * not inherited — a member of a hidden group answers `false` here; the paint
+ * and pick predicate (`GfxLocalVisibility.isHidden`) walks the ancestors.
+ */
+export function isStoredHiddenForEveryone(model) {
+    if (model instanceof GfxPrimitiveElementModel) {
+        return model.hiddenForEveryone === true;
+    }
+    try {
+        const props = model.props;
+        return props?.hiddenForEveryone === true;
+    }
+    catch {
+        // A block model outside a flat store has no `props` to read.
+        return false;
+    }
+}
 export function syncElementFromY(model, callback) {
     const disposables = {};
     const observer = (event, transaction) => {

package/dist/_pkgs/std/gfx/model/surface/role.d.ts

@@ -77,12 +77,17 @@ export interface EdgeDirectionDef {
     gestureHintFallback?: string;
     /**
      * CSS colour of the chip the reveal draws this verb in (M2). Absent — which
-     * is every role but one — keeps the house affordance blue the mechanism has
-     * always used, so declaring nothing repaints nothing.
+     * is every role today — leaves the chip on the chrome's accent token, so
+     * every typed edge of every framework wears one blue and follows a host
+     * re-skin with the rest of the chrome.
      *
-     * A colour belongs to the ROLE rather than to the widget because the chip is
-     * per-relation: the PO may want one framework's central relation to stand out
-     * without every other framework's edges changing with it. The chip's text is
+     * An extension point, deliberately unused. One role took it (PR #203) so its
+     * framework's central relation would stand out, and the result on a map
+     * carrying two typed relations was two different blues, with nothing
+     * comparing them. Reversed on the PO recette of 23/09/2026; the field stays
+     * because a framework may one day have a real reason to claim its own, and
+     * `affine/all/src/__tests__/direction-chip-accent.unit.spec.ts` is what makes
+     * that a reviewed decision rather than a silent one. The chip's text is
      * white, so a colour declared here must be dark enough to carry it.
      */
     chipColor?: string;

package/dist/_pkgs/std/gfx/model/surface/surface-model.d.ts

@@ -7,6 +7,7 @@ import { type GfxGroupCompatibleInterface } from '../base.js';
 import type { GfxGroupModel, GfxModel } from '../model.js';
 import { type GfxPrimitiveElementModel } from './element-model.js';
 import type { GfxLocalElementModel } from './local-element-model.js';
+import { type SurfaceLayerRecord, SurfaceUserLayers } from './user-layers.js';
 /**
  * Used for text field
  */
@@ -17,6 +18,20 @@ export declare const SURFACE_TEXT_UNIQ_IDENTIFIER = "affine:surface:text";
 export declare const SURFACE_YMAP_UNIQ_IDENTIFIER = "affine:surface:ymap";
 export type SurfaceBlockProps = {
     elements: Boxed<Y.Map<Y.Map<unknown>>>;
+    /**
+     * The canvas grid, saved for everyone by "Save for everyone" (ADR 0031
+     * §2, §11). Absent = nobody decided: the viewer's override, the host
+     * default and the library default decide, in that order. Declared with an
+     * `undefined` default so loading a document writes nothing.
+     */
+    showGrid?: boolean;
+    /**
+     * User layers by id (ADR 0031 §2). Absent until the first layer is
+     * created; every write sets ONE record or ONE field of a record, never the
+     * whole prop, so two peers' edits merge key by key. Declared with an
+     * `undefined` default so loading a document writes nothing.
+     */
+    layers?: Record<string, SurfaceLayerRecord>;
 };
 export interface ElementUpdatedData {
     id: string;
@@ -84,6 +99,12 @@ export declare class SurfaceBlockModel extends BlockModel<SurfaceBlockProps> {
         local: boolean;
     }>;
     elementUpdated: Subject<ElementUpdatedData>;
+    /**
+     * The user layers of this surface, resolved for stacking (ADR 0031 §4).
+     * Read by `compare`; `userLayers.ranks` is `null` while the document has no
+     * layer, and then nothing else here is ever asked.
+     */
+    readonly userLayers: SurfaceUserLayers;
     /**
      * An element was found damaged — see {@link damagedElements}. Pushed at the
      * same moment the console line is written, so a subscriber that arrives
@@ -183,6 +204,12 @@ export declare class SurfaceBlockModel extends BlockModel<SurfaceBlockProps> {
     private _watchChildrenChange;
     protected _extendElement(ctorMap: Record<string, Constructor<GfxPrimitiveElementModel, ConstructorParameters<typeof GfxPrimitiveElementModel>>>): void;
     protected _init(): void;
+    /**
+     * Keeps {@link userLayers}' caches honest (ADR 0031 §4): the ranks follow
+     * the `layers` prop, the effective layers follow every `layer` write, every
+     * regroup and every element added or removed.
+     */
+    private _watchUserLayers;
     getConstructor(type: string): Constructor<GfxPrimitiveElementModel<import("./element-model.js").BaseElementProps>, [options: {
         id: string;
         yMap: Y.Map<unknown>;

package/dist/_pkgs/std/gfx/model/surface/surface-model.js

@@ -9,6 +9,7 @@ import { createDecoratorState } from './decorators/common.js';
 import { getFieldPropsSet, getLocalPropsSet, initializeObservers, initializeWatchers, } from './decorators/index.js';
 import { GfxGroupLikeElementModel, syncElementFromY, } from './element-model.js';
 import { tagsPropToY } from './tags.js';
+import { registerSurfaceOfStore, SurfaceUserLayers, } from './user-layers.js';
 /**
  * Used for text field
  */
@@ -188,6 +189,8 @@ export class SurfaceBlockModel extends BlockModel {
         'xywh',
         'rotate',
         'hidden',
+        // ADR 0031 §9: a member hidden for everyone leaves the group's bound.
+        'hiddenForEveryone',
     ]); }
     /**
      * The elements this surface built from a Y.Map that was missing a key it
@@ -234,6 +237,12 @@ export class SurfaceBlockModel extends BlockModel {
         this.elementAdded = new Subject();
         this.elementRemoved = new Subject();
         this.elementUpdated = new Subject();
+        /**
+         * The user layers of this surface, resolved for stacking (ADR 0031 §4).
+         * Read by `compare`; `userLayers.ranks` is `null` while the document has no
+         * layer, and then nothing else here is ever asked.
+         */
+        this.userLayers = new SurfaceUserLayers(this);
         /**
          * An element was found damaged — see {@link damagedElements}. Pushed at the
          * same moment the console line is written, so a subscriber that arrives
@@ -657,6 +666,40 @@ export class SurfaceBlockModel extends BlockModel {
         this._initElementModels();
         this._watchGroupRelationChange();
         this._watchChildrenChange();
+        this._watchUserLayers();
+    }
+    /**
+     * Keeps {@link userLayers}' caches honest (ADR 0031 §4): the ranks follow
+     * the `layers` prop, the effective layers follow every `layer` write, every
+     * regroup and every element added or removed.
+     */
+    _watchUserLayers() {
+        registerSurfaceOfStore(this.store, this);
+        const membership = () => this.userLayers.invalidateMembership();
+        const subscriptions = [
+            this.propsUpdated.subscribe(({ key }) => {
+                if (key === 'layers')
+                    this.userLayers.invalidateRanks();
+            }),
+            this.elementAdded.subscribe(membership),
+            this.elementRemoved.subscribe(membership),
+            this.elementUpdated.subscribe(({ props, oldValues }) => {
+                if ('layer' in props ||
+                    'layer' in oldValues ||
+                    'childIds' in props ||
+                    'childIds' in oldValues) {
+                    membership();
+                }
+            }),
+            this.store.slots.blockUpdated.subscribe(payload => {
+                if (payload.type !== 'update' || payload.props.key === 'layer') {
+                    membership();
+                }
+            }),
+        ];
+        this.deleted.subscribe(() => {
+            subscriptions.forEach(subscription => subscription.unsubscribe());
+        });
     }
     getConstructor(type) {
         return this._elementCtorMap[type];

package/dist/_pkgs/std/gfx/model/surface/user-layers.d.ts

@@ -0,0 +1,68 @@
+import type { Store } from '../../../../store/index.js';
+import type { GfxModel } from '../model.js';
+import type { SurfaceBlockModel } from './surface-model.js';
+/**
+ * The layer every element belongs to while it names none (ADR 0031 §2, §3).
+ * A `@` cannot appear in a nanoid, so it never collides with a real layer id;
+ * it has no record while the surface has no `layers`, and is written as
+ * `undefined` on an element, never as this string.
+ */
+export declare const DEFAULT_LAYER_ID = "@default";
+/** One user layer, stored on the surface under its id (ADR 0031 §2). */
+export type SurfaceLayerRecord = {
+    /** Seeded through the translation seam at creation; content from then on. */
+    name: string;
+    /** Fractional key, bottom → top; the same alphabet as an element's `index`. */
+    index: string;
+    /** "Hide for everyone" on the whole layer. Absent = visible. */
+    hidden?: true;
+};
+/**
+ * What a model names as its own layer: an element's `layer` field, a gfx
+ * block's `layer` prop. `undefined` = the default layer.
+ */
+export declare function ownLayerOf(model: unknown): string | undefined;
+/**
+ * The model whose `layer` decides `model`'s (ADR 0031 §5): its outermost
+ * group-like ELEMENT ancestor (a group, a mindmap), else `model` itself. A
+ * group lives in one layer, stored once on its outermost group, so this is
+ * what {@link SurfaceUserLayers.effectiveLayerOf} reads and what a "move to
+ * layer" writes on. Frames are blocks and do not count. `groups` walks the
+ * model's surface, which throws on a detached model: that one carries itself.
+ */
+export declare function layerCarrierOf(model: GfxModel): GfxModel;
+/**
+ * The user layers of one surface, resolved for the comparator (ADR 0031 §4).
+ *
+ * Two caches, both thrown away by a revision bump rather than kept in step:
+ *
+ * - the rank of every layer id (its record's `index`), rebuilt when the
+ *   `layers` prop changes — `null` while the surface has no layer, which is
+ *   the fast path: `compare` then never asks for an effective layer at all;
+ * - each model's EFFECTIVE layer, rebuilt when anything that decides it
+ *   changes: a `layer` write, a regroup, an element added or removed.
+ *
+ * The effective layer is the `layer` of the model's outermost group-like
+ * ELEMENT ancestor (a group, a mindmap), else its own; a dangling id or none
+ * is {@link DEFAULT_LAYER_ID}. Frames are not counted: a frame is a slide,
+ * and a background layer under a content layer inside one frame is the point
+ * of layers. Nothing here writes: a dangling id is read as the default and
+ * left as it is.
+ */
+export declare class SurfaceUserLayers {
+    private readonly _surface;
+    private _ranks;
+    private _revision;
+    private readonly _effective;
+    constructor(_surface: SurfaceBlockModel);
+    /** Every layer id with its rank key, or `null` when there is no layer. */
+    get ranks(): ReadonlyMap<string, string> | null;
+    /** The `layers` record changed: ranks and effective layers are stale. */
+    invalidateRanks(): void;
+    /** Something that decides an effective layer changed. */
+    invalidateMembership(): void;
+    /** The layer `model` stacks and shows with. */
+    effectiveLayerOf(model: GfxModel): string;
+}
+export declare function registerSurfaceOfStore(store: Store, surface: SurfaceBlockModel): void;
+export declare function userLayersOf(model: unknown): SurfaceUserLayers | null;

package/dist/_pkgs/std/gfx/model/surface/user-layers.js

@@ -0,0 +1,127 @@
+import { GfxPrimitiveElementModel } from './element-model.js';
+/**
+ * The layer every element belongs to while it names none (ADR 0031 §2, §3).
+ * A `@` cannot appear in a nanoid, so it never collides with a real layer id;
+ * it has no record while the surface has no `layers`, and is written as
+ * `undefined` on an element, never as this string.
+ */
+export const DEFAULT_LAYER_ID = '@default';
+/**
+ * What a model names as its own layer: an element's `layer` field, a gfx
+ * block's `layer` prop. `undefined` = the default layer.
+ */
+export function ownLayerOf(model) {
+    if (model instanceof GfxPrimitiveElementModel)
+        return model.layer;
+    try {
+        const props = model.props;
+        return typeof props?.layer === 'string' ? props.layer : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * The model whose `layer` decides `model`'s (ADR 0031 §5): its outermost
+ * group-like ELEMENT ancestor (a group, a mindmap), else `model` itself. A
+ * group lives in one layer, stored once on its outermost group, so this is
+ * what {@link SurfaceUserLayers.effectiveLayerOf} reads and what a "move to
+ * layer" writes on. Frames are blocks and do not count. `groups` walks the
+ * model's surface, which throws on a detached model: that one carries itself.
+ */
+export function layerCarrierOf(model) {
+    let groups = [];
+    try {
+        groups = model.groups ?? [];
+    }
+    catch {
+        groups = [];
+    }
+    for (let i = groups.length - 1; i >= 0; i--) {
+        if (groups[i] instanceof GfxPrimitiveElementModel) {
+            return groups[i];
+        }
+    }
+    return model;
+}
+/**
+ * The user layers of one surface, resolved for the comparator (ADR 0031 §4).
+ *
+ * Two caches, both thrown away by a revision bump rather than kept in step:
+ *
+ * - the rank of every layer id (its record's `index`), rebuilt when the
+ *   `layers` prop changes — `null` while the surface has no layer, which is
+ *   the fast path: `compare` then never asks for an effective layer at all;
+ * - each model's EFFECTIVE layer, rebuilt when anything that decides it
+ *   changes: a `layer` write, a regroup, an element added or removed.
+ *
+ * The effective layer is the `layer` of the model's outermost group-like
+ * ELEMENT ancestor (a group, a mindmap), else its own; a dangling id or none
+ * is {@link DEFAULT_LAYER_ID}. Frames are not counted: a frame is a slide,
+ * and a background layer under a content layer inside one frame is the point
+ * of layers. Nothing here writes: a dangling id is read as the default and
+ * left as it is.
+ */
+export class SurfaceUserLayers {
+    constructor(_surface) {
+        this._surface = _surface;
+        this._ranks = undefined;
+        this._revision = 0;
+        this._effective = new WeakMap();
+    }
+    /** Every layer id with its rank key, or `null` when there is no layer. */
+    get ranks() {
+        if (this._ranks === undefined) {
+            const layers = this._surface.props.layers;
+            if (!layers || Object.keys(layers).length === 0) {
+                this._ranks = null;
+            }
+            else {
+                const ranks = new Map();
+                for (const [id, record] of Object.entries(layers)) {
+                    if (record && typeof record.index === 'string') {
+                        ranks.set(id, record.index);
+                    }
+                }
+                this._ranks = ranks.size ? ranks : null;
+            }
+        }
+        return this._ranks;
+    }
+    /** The `layers` record changed: ranks and effective layers are stale. */
+    invalidateRanks() {
+        this._ranks = undefined;
+        this._revision++;
+    }
+    /** Something that decides an effective layer changed. */
+    invalidateMembership() {
+        this._revision++;
+    }
+    /** The layer `model` stacks and shows with. */
+    effectiveLayerOf(model) {
+        const cached = this._effective.get(model);
+        if (cached && cached.revision === this._revision)
+            return cached.layer;
+        const named = ownLayerOf(layerCarrierOf(model));
+        const ranks = this.ranks;
+        const layer = named !== undefined && ranks?.has(named) ? named : DEFAULT_LAYER_ID;
+        this._effective.set(model, { revision: this._revision, layer });
+        return layer;
+    }
+}
+/**
+ * Which surface a model's layers are read from. An element knows its
+ * surface; a gfx block knows its store, and the surface registers itself for
+ * its store when it initialises, so the comparator never queries the store.
+ */
+const SURFACE_OF_STORE = new WeakMap();
+export function registerSurfaceOfStore(store, surface) {
+    SURFACE_OF_STORE.set(store, surface);
+}
+export function userLayersOf(model) {
+    if (model instanceof GfxPrimitiveElementModel) {
+        return model.surface?.userLayers ?? null;
+    }
+    const store = model.store;
+    return store ? (SURFACE_OF_STORE.get(store)?.userLayers ?? null) : null;
+}

package/dist/_pkgs/std/utils/layer.d.ts

@@ -8,6 +8,16 @@ export declare function getLayerEndZIndex(layers: Layer[], layerIndex: number):
 export declare function updateLayersZIndex(layers: Layer[], startIdx: number): void;
 export declare function getElementIndex(indexable: GfxModel): string;
 export declare function ungroupIndex(index: string): string;
+/**
+ * Insert `element` after every element that sorts before it or ties with it.
+ *
+ * The array is kept sorted by `compare`, so that predicate holds on a prefix
+ * and the position is found by bisection. The linear scan it replaces asked
+ * `compare` (which walks both elements' group chains) of every element on
+ * every insert: a paste of N elements was N² comparisons. Where an index is
+ * shared by two unrelated subtrees `compare` is not transitive and both pick
+ * a tied position, not always the same one (layer-ordered-insert.unit.spec).
+ */
 export declare function insertToOrderedArray(array: GfxModel[], element: GfxModel): void;
 export declare function removeFromOrderedArray(array: GfxModel[], element: GfxModel): void;
 export declare enum SortOrder {

package/dist/_pkgs/std/utils/layer.js

@@ -1,6 +1,7 @@
 import { isGfxGroupCompatibleModel, } from '../gfx/model/base.js';
 import {} from '../gfx/model/gfx-block-model.js';
 import { GfxLocalElementModel } from '../gfx/model/surface/local-element-model.js';
+import { userLayersOf } from '../gfx/model/surface/user-layers.js';
 export function getLayerEndZIndex(layers, layerIndex) {
     const layer = layers[layerIndex];
     return layer ? layer.zIndex + layer.elements.length - 1 : 0;
@@ -28,13 +29,29 @@ export function getElementIndex(indexable) {
 export function ungroupIndex(index) {
     return index.split('-')[0];
 }
+/**
+ * Insert `element` after every element that sorts before it or ties with it.
+ *
+ * The array is kept sorted by `compare`, so that predicate holds on a prefix
+ * and the position is found by bisection. The linear scan it replaces asked
+ * `compare` (which walks both elements' group chains) of every element on
+ * every insert: a paste of N elements was N² comparisons. Where an index is
+ * shared by two unrelated subtrees `compare` is not transitive and both pick
+ * a tied position, not always the same one (layer-ordered-insert.unit.spec).
+ */
 export function insertToOrderedArray(array, element) {
-    let idx = 0;
-    while (idx < array.length &&
-        [SortOrder.BEFORE, SortOrder.SAME].includes(compare(array[idx], element))) {
-        ++idx;
+    let low = 0;
+    let high = array.length;
+    while (low < high) {
+        const mid = (low + high) >>> 1;
+        if (compare(array[mid], element) === SortOrder.AFTER) {
+            high = mid;
+        }
+        else {
+            low = mid + 1;
+        }
     }
-    array.splice(idx, 0, element);
+    array.splice(low, 0, element);
 }
 export function removeFromOrderedArray(array, element) {
     const idx = array.indexOf(element);
@@ -74,10 +91,40 @@ function compareLocal(a, b) {
     if (isALocal && isBLocal && a.creator && a.creator === b.creator) {
         return compareIndex(a.index, b.index);
     }
-    return {
-        a: isALocal && a.creator ? a.creator : a,
-        b: isBLocal && b.creator ? b.creator : b,
-    };
+    const left = isALocal && a.creator ? a.creator : a;
+    const right = isBLocal && b.creator ? b.creator : b;
+    // ADR 0031 §4: user layer rank first, then everything below unchanged.
+    const byLayer = compareUserLayer(left, right);
+    if (byLayer !== SortOrder.SAME)
+        return byLayer;
+    return { a: left, b: right };
+}
+/**
+ * The first step of {@link compare} (ADR 0031 §4): two models in different
+ * user layers stack by their layers' `index`; anything else is `SAME`, and
+ * today's comparator decides.
+ *
+ * The fast path is the first `return`: a surface with no `layers` answers
+ * `null` ranks after one cached read, so a document without user layers
+ * sorts with exactly the code that sorted it before layers existed. A local
+ * element without a creator has no layer and keeps today's order — above the
+ * content, as overlays always were.
+ */
+function compareUserLayer(a, b) {
+    if (a instanceof GfxLocalElementModel || b instanceof GfxLocalElementModel) {
+        return SortOrder.SAME;
+    }
+    const layers = userLayersOf(a);
+    const ranks = layers?.ranks;
+    if (!layers || !ranks)
+        return SortOrder.SAME;
+    const aLayer = layers.effectiveLayerOf(a);
+    const bLayer = layers.effectiveLayerOf(b);
+    if (aLayer === bLayer)
+        return SortOrder.SAME;
+    // A default layer with no record (the loser of a first-layer race, ADR
+    // 0031 open point 6) stacks at the bottom: `''` precedes every key.
+    return compareIndex(ranks.get(aLayer) ?? '', ranks.get(bLayer) ?? '');
 }
 /**
  * A comparator function for sorting elements in the surface.
@@ -91,15 +138,19 @@ export function compare(a, b) {
     }
     a = result.a;
     b = result.b;
-    if (isGfxGroupCompatibleModel(a) && b.groups.includes(a)) {
+    // Each `groups` read walks the group chain through `getGroup`, a scan of
+    // every container on the surface: read each side once.
+    const aGroups = a.groups;
+    const bGroups = b.groups;
+    if (isGfxGroupCompatibleModel(a) &&
+        bGroups.includes(a)) {
         return SortOrder.BEFORE;
     }
-    else if (isGfxGroupCompatibleModel(b) && a.groups.includes(b)) {
+    else if (isGfxGroupCompatibleModel(b) &&
+        aGroups.includes(b)) {
         return SortOrder.AFTER;
     }
     else {
-        const aGroups = a.groups;
-        const bGroups = b.groups;
         let i = 1;
         let aGroup = aGroups.at(-i);
         let bGroup = bGroups.at(-i);