@formicoidea/labre-core 0.43.1 → 0.46.0

package/dist/_pkgs/std/gfx/local-visibility.d.ts

@@ -0,0 +1,88 @@
+import type { Store } from '../../store/index.js';
+import { type ReadonlySignal } from '@preact/signals-core';
+import type { GfxLocalElementModel } from './model/surface/local-element-model.js';
+import type { GfxModel } from './model/model.js';
+import type { SurfaceBlockModel } from './model/surface/surface-model.js';
+/**
+ * The ids of the elements and gfx blocks hidden for everyone (ADR 0031 §7) —
+ * the SHARED half of the paint and pick predicate, kept as a set so the
+ * renderers ask one `has` per element and pay nothing when nobody hid
+ * anything.
+ *
+ * Built from the document once per surface, then kept current by the
+ * surface's element events and the store's block events, local or remote
+ * alike: a peer's "hide for everyone" reaches this viewer the moment its
+ * update does. Registered by `GfxController` into its
+ * {@link GfxLocalVisibility}, beside the viewer's own local hide, so every
+ * site that already skips what this viewer hid skips this too — and
+ * `grid.search`, which reads neither, keeps counting both.
+ */
+export declare class GfxHiddenForEveryone {
+    private readonly _ids$;
+    private readonly _layerIds$;
+    private _unwatch;
+    /** Every id carrying the stored `hiddenForEveryone`. */
+    get ids$(): ReadonlySignal<ReadonlySet<string>>;
+    /**
+     * Every user layer hidden for everyone — `hidden: true` on its record (ADR
+     * 0031 §7): one write for a whole layer, never one per member.
+     */
+    get layerIds$(): ReadonlySignal<ReadonlySet<string>>;
+    /** Follow `surface` and `store`; `null` stops following. */
+    watch(store: Store, surface: SurfaceBlockModel | null): void;
+    dispose(): void;
+}
+/**
+ * What THIS viewer does not see on the canvas — the per-editor predicate hook
+ * of ADR 0031 §8.
+ *
+ * `std` knows nothing about why an element is hidden for one viewer; the
+ * affine layer (`CanvasLocalVisibility`) registers a signal of ids and owns
+ * their persistence. `GfxController` registers one more source, the ids
+ * hidden for everyone ({@link GfxHiddenForEveryone}): the shared half of the
+ * same predicate, so the sites below skip both with one question. Layers
+ * have their own sources (`registerLayers`), local and shared alike: a model
+ * whose EFFECTIVE layer is hidden is hidden. This class answers the one
+ * question the gfx plumbing asks — "does this viewer see that model?" — at the places a viewer's eye
+ * and hand reach the canvas: the renderers, the DOM block views, pointer
+ * picking and the marquee.
+ *
+ * It is deliberately NOT consulted by `GridManager.search`: that answer is
+ * shared with rules, legends and semantic exports, and one viewer's local
+ * hide must never change what another viewer's rules say about the same
+ * document.
+ *
+ * Reactive: `isHidden` reads a signal, so an effect or a `computed` that asks
+ * re-runs when the set changes (the DOM block views rely on it). With nothing
+ * registered, or nothing hidden, every answer is `false` after one size check.
+ */
+export declare class GfxLocalVisibility {
+    private readonly _sources$;
+    /** Every id hidden for this viewer, across every registered source. */
+    readonly hiddenIds$: ReadonlySignal<ReadonlySet<string>>;
+    private readonly _layerSources$;
+    /** Every user layer hidden for this viewer, across every layer source. */
+    readonly hiddenLayerIds$: ReadonlySignal<ReadonlySet<string>>;
+    /** Add a source of hidden ids. Returns its disposer. */
+    register(source: ReadonlySignal<ReadonlySet<string>>): () => void;
+    /** Add a source of hidden LAYER ids (ADR 0031, stage 7). Returns its disposer. */
+    registerLayers(source: ReadonlySignal<ReadonlySet<string>>): () => void;
+    /**
+     * Is `model` hidden for this viewer — itself, or through a group-like
+     * ELEMENT ancestor (a group, a mindmap)?
+     *
+     * Frames are not walked, although they are group-compatible: a frame is a
+     * slide, and hiding the frame hides the frame, not what it holds (ADR 0031
+     * §5). A model no surface holds has no ancestors to ask about.
+     */
+    isHidden(model: GfxModel | GfxLocalElementModel): boolean;
+    /**
+     * Whether `model`'s EFFECTIVE layer is one of `layers` — the outermost
+     * group's layer, so a whole group hides with its layer. A hidden frame's
+     * layer hides the frame, not what it holds (ADR 0031 §5). Local elements
+     * belong to no layer. A surface with no `layers` record still has the
+     * default layer, shown and hideable before it is recorded (ADR 0031
+     * amendments): every model is then in it.
+     */
+    private _inHiddenLayer;
+}

package/dist/_pkgs/std/gfx/local-visibility.js

@@ -0,0 +1,217 @@
+import { computed, signal } from '@preact/signals-core';
+import { GfxBlockElementModel } from './model/gfx-block-model.js';
+import { GfxPrimitiveElementModel, isStoredHiddenForEveryone, } from './model/surface/element-model.js';
+import { userLayersOf } from './model/surface/user-layers.js';
+const NOTHING_HIDDEN = new Set();
+/**
+ * The ids of the elements and gfx blocks hidden for everyone (ADR 0031 §7) —
+ * the SHARED half of the paint and pick predicate, kept as a set so the
+ * renderers ask one `has` per element and pay nothing when nobody hid
+ * anything.
+ *
+ * Built from the document once per surface, then kept current by the
+ * surface's element events and the store's block events, local or remote
+ * alike: a peer's "hide for everyone" reaches this viewer the moment its
+ * update does. Registered by `GfxController` into its
+ * {@link GfxLocalVisibility}, beside the viewer's own local hide, so every
+ * site that already skips what this viewer hid skips this too — and
+ * `grid.search`, which reads neither, keeps counting both.
+ */
+export class GfxHiddenForEveryone {
+    constructor() {
+        this._ids$ = signal(NOTHING_HIDDEN);
+        this._layerIds$ = signal(NOTHING_HIDDEN);
+        this._unwatch = null;
+    }
+    /** Every id carrying the stored `hiddenForEveryone`. */
+    get ids$() {
+        return this._ids$;
+    }
+    /**
+     * Every user layer hidden for everyone — `hidden: true` on its record (ADR
+     * 0031 §7): one write for a whole layer, never one per member.
+     */
+    get layerIds$() {
+        return this._layerIds$;
+    }
+    /** Follow `surface` and `store`; `null` stops following. */
+    watch(store, surface) {
+        this.dispose();
+        if (!surface)
+            return;
+        const initial = new Set();
+        for (const element of surface.elementModels) {
+            if (isStoredHiddenForEveryone(element))
+                initial.add(element.id);
+        }
+        for (const model of store.getAllModels()) {
+            if (model instanceof GfxBlockElementModel &&
+                isStoredHiddenForEveryone(model)) {
+                initial.add(model.id);
+            }
+        }
+        this._ids$.value = initial.size ? initial : NOTHING_HIDDEN;
+        const readLayers = () => {
+            const hidden = new Set();
+            for (const [id, record] of Object.entries(surface.props.layers ?? {})) {
+                if (record?.hidden === true)
+                    hidden.add(id);
+            }
+            const current = this._layerIds$.peek();
+            if (hidden.size === current.size &&
+                [...hidden].every(id => current.has(id))) {
+                return;
+            }
+            this._layerIds$.value = hidden.size ? hidden : NOTHING_HIDDEN;
+        };
+        readLayers();
+        const recheck = (id, model) => {
+            const hidden = model !== null && isStoredHiddenForEveryone(model);
+            const current = this._ids$.peek();
+            if (current.has(id) === hidden)
+                return;
+            const next = new Set(current);
+            if (hidden)
+                next.add(id);
+            else
+                next.delete(id);
+            this._ids$.value = next.size ? next : NOTHING_HIDDEN;
+        };
+        const subscriptions = [
+            surface.propsUpdated.subscribe(({ key }) => {
+                if (key === 'layers')
+                    readLayers();
+            }),
+            surface.elementAdded.subscribe(({ id }) => recheck(id, surface.getElementById(id))),
+            surface.elementUpdated.subscribe(({ id }) => recheck(id, surface.getElementById(id))),
+            surface.elementRemoved.subscribe(({ id }) => recheck(id, null)),
+            store.slots.blockUpdated.subscribe(payload => {
+                if (payload.type === 'delete') {
+                    recheck(payload.id, null);
+                    return;
+                }
+                if (payload.type === 'update' &&
+                    payload.props.key !== 'hiddenForEveryone') {
+                    return;
+                }
+                recheck(payload.id, store.getBlock(payload.id)?.model ?? null);
+            }),
+        ];
+        this._unwatch = () => subscriptions.forEach(sub => sub.unsubscribe());
+    }
+    dispose() {
+        this._unwatch?.();
+        this._unwatch = null;
+        this._ids$.value = NOTHING_HIDDEN;
+        this._layerIds$.value = NOTHING_HIDDEN;
+    }
+}
+/**
+ * What THIS viewer does not see on the canvas — the per-editor predicate hook
+ * of ADR 0031 §8.
+ *
+ * `std` knows nothing about why an element is hidden for one viewer; the
+ * affine layer (`CanvasLocalVisibility`) registers a signal of ids and owns
+ * their persistence. `GfxController` registers one more source, the ids
+ * hidden for everyone ({@link GfxHiddenForEveryone}): the shared half of the
+ * same predicate, so the sites below skip both with one question. Layers
+ * have their own sources (`registerLayers`), local and shared alike: a model
+ * whose EFFECTIVE layer is hidden is hidden. This class answers the one
+ * question the gfx plumbing asks — "does this viewer see that model?" — at the places a viewer's eye
+ * and hand reach the canvas: the renderers, the DOM block views, pointer
+ * picking and the marquee.
+ *
+ * It is deliberately NOT consulted by `GridManager.search`: that answer is
+ * shared with rules, legends and semantic exports, and one viewer's local
+ * hide must never change what another viewer's rules say about the same
+ * document.
+ *
+ * Reactive: `isHidden` reads a signal, so an effect or a `computed` that asks
+ * re-runs when the set changes (the DOM block views rely on it). With nothing
+ * registered, or nothing hidden, every answer is `false` after one size check.
+ */
+export class GfxLocalVisibility {
+    constructor() {
+        this._sources$ = signal([]);
+        /** Every id hidden for this viewer, across every registered source. */
+        this.hiddenIds$ = computed(() => unionOf(this._sources$.value));
+        this._layerSources$ = signal([]);
+        /** Every user layer hidden for this viewer, across every layer source. */
+        this.hiddenLayerIds$ = computed(() => unionOf(this._layerSources$.value));
+    }
+    /** Add a source of hidden ids. Returns its disposer. */
+    register(source) {
+        this._sources$.value = [...this._sources$.peek(), source];
+        return () => {
+            this._sources$.value = this._sources$
+                .peek()
+                .filter(existing => existing !== source);
+        };
+    }
+    /** Add a source of hidden LAYER ids (ADR 0031, stage 7). Returns its disposer. */
+    registerLayers(source) {
+        this._layerSources$.value = [...this._layerSources$.peek(), source];
+        return () => {
+            this._layerSources$.value = this._layerSources$
+                .peek()
+                .filter(existing => existing !== source);
+        };
+    }
+    /**
+     * Is `model` hidden for this viewer — itself, or through a group-like
+     * ELEMENT ancestor (a group, a mindmap)?
+     *
+     * Frames are not walked, although they are group-compatible: a frame is a
+     * slide, and hiding the frame hides the frame, not what it holds (ADR 0031
+     * §5). A model no surface holds has no ancestors to ask about.
+     */
+    isHidden(model) {
+        const hiddenLayers = this.hiddenLayerIds$.value;
+        if (hiddenLayers.size > 0 && this._inHiddenLayer(model, hiddenLayers)) {
+            return true;
+        }
+        const hidden = this.hiddenIds$.value;
+        if (hidden.size === 0)
+            return false;
+        if (hidden.has(model.id))
+            return true;
+        let ancestors;
+        try {
+            ancestors = model.groups ?? [];
+        }
+        catch {
+            return false;
+        }
+        return ancestors.some(ancestor => ancestor instanceof GfxPrimitiveElementModel && hidden.has(ancestor.id));
+    }
+    /**
+     * Whether `model`'s EFFECTIVE layer is one of `layers` — the outermost
+     * group's layer, so a whole group hides with its layer. A hidden frame's
+     * layer hides the frame, not what it holds (ADR 0031 §5). Local elements
+     * belong to no layer. A surface with no `layers` record still has the
+     * default layer, shown and hideable before it is recorded (ADR 0031
+     * amendments): every model is then in it.
+     */
+    _inHiddenLayer(model, layers) {
+        const userLayers = userLayersOf(model);
+        if (!userLayers)
+            return false;
+        if (!(model instanceof GfxPrimitiveElementModel) &&
+            !(model instanceof GfxBlockElementModel)) {
+            return false;
+        }
+        return layers.has(userLayers.effectiveLayerOf(model));
+    }
+}
+function unionOf(sources) {
+    if (sources.length === 0)
+        return NOTHING_HIDDEN;
+    if (sources.length === 1)
+        return sources[0].value;
+    const union = new Set();
+    for (const source of sources) {
+        for (const id of source.value)
+            union.add(id);
+    }
+    return union;
+}

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

@@ -13,6 +13,19 @@ export type GfxCompatibleProps = {
     xywh: SerializedXYWH;
     index: string;
     lockedBySelf?: boolean;
+    /**
+     * "Hide for everyone" (ADR 0031 §7). `true` or absent, never `false`:
+     * unhiding deletes the `prop:` key through the props proxy, so the block
+     * goes back to byte-identical. Every gfx block schema declares it with an
+     * `undefined` default, the way it declares `lockedBySelf`.
+     */
+    hiddenForEveryone?: true;
+    /**
+     * The user layer this block belongs to (ADR 0031 §3); `undefined` = the
+     * default layer. Declared by every gfx block schema with an `undefined`
+     * default, like `hiddenForEveryone`.
+     */
+    layer?: string;
 };
 /**
  * This type include the common props for the graphic block model.

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/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];