@formicoidea/labre-core 0.43.1 → 0.46.0

package/dist/_pkgs/affine-block-surface/extensions/user-layers/creation.d.ts

@@ -0,0 +1,40 @@
+import type { BlockStdScope } from '../../../std/index.js';
+import { type SurfaceMiddleware, SurfaceMiddlewareBuilder } from '../../../std/gfx/index.js';
+/**
+ * The layer to REQUEST for a model derived from `source` — the note an
+ * auto-complete arrow clones, the note the slicer splits off, the block that
+ * replaces another when its view changes — so it lands beside its source
+ * once {@link resolveCreationLayer} has read it. A source in the default
+ * layer asks for {@link DEFAULT_LAYER_ID} explicitly: "absent" would hand the
+ * derived model to the viewer's active layer instead.
+ */
+export declare function sourceLayerOf(source: unknown): string;
+/**
+ * The layer a model being CREATED is stored in (ADR 0031 §6), as the value
+ * to write: a layer id, or `undefined` for the default layer.
+ *
+ * - `requested` names a layer of THIS surface → kept (a duplicate, an
+ *   alt-drag clone, a paste within the document stays beside its source);
+ * - `requested` is {@link DEFAULT_LAYER_ID} → the default layer, explicitly:
+ *   a caller that computed "default" (a new group whose highest member is in
+ *   it) is not overridden by the active layer;
+ * - anything else — absent, or an id with no record here (a paste from
+ *   another document, a template, an import) → the viewer's active layer.
+ *
+ * A surface with no layer at all writes nothing, whatever was asked.
+ */
+export declare function resolveCreationLayer(std: BlockStdScope, requested: unknown): string | undefined;
+/**
+ * Stamp the creation layer on `props` in place: set it, or remove the key so
+ * a default-layer model writes no `layer` at all.
+ */
+export declare function applyCreationLayer(std: BlockStdScope, props: Record<string, unknown>): void;
+/**
+ * Every `surface.addElement` goes through this `beforeAdd` middleware, beside
+ * `EditPropsMiddlewareBuilder` (ADR 0031 §6): a framework command adding an
+ * element directly gets the same rule as the canvas tools.
+ */
+export declare class UserLayerMiddlewareBuilder extends SurfaceMiddlewareBuilder {
+    static key: string;
+    middleware: SurfaceMiddleware;
+}

package/dist/_pkgs/affine-block-surface/extensions/user-layers/creation.js

@@ -0,0 +1,69 @@
+import { DEFAULT_LAYER_ID, GfxControllerIdentifier, ownLayerOf, SurfaceMiddlewareBuilder, } from '../../../std/gfx/index.js';
+import { CanvasActiveLayer } from './active-layer.js';
+/**
+ * The layer to REQUEST for a model derived from `source` — the note an
+ * auto-complete arrow clones, the note the slicer splits off, the block that
+ * replaces another when its view changes — so it lands beside its source
+ * once {@link resolveCreationLayer} has read it. A source in the default
+ * layer asks for {@link DEFAULT_LAYER_ID} explicitly: "absent" would hand the
+ * derived model to the viewer's active layer instead.
+ */
+export function sourceLayerOf(source) {
+    return ownLayerOf(source) ?? DEFAULT_LAYER_ID;
+}
+/**
+ * The layer a model being CREATED is stored in (ADR 0031 §6), as the value
+ * to write: a layer id, or `undefined` for the default layer.
+ *
+ * - `requested` names a layer of THIS surface → kept (a duplicate, an
+ *   alt-drag clone, a paste within the document stays beside its source);
+ * - `requested` is {@link DEFAULT_LAYER_ID} → the default layer, explicitly:
+ *   a caller that computed "default" (a new group whose highest member is in
+ *   it) is not overridden by the active layer;
+ * - anything else — absent, or an id with no record here (a paste from
+ *   another document, a template, an import) → the viewer's active layer.
+ *
+ * A surface with no layer at all writes nothing, whatever was asked.
+ */
+export function resolveCreationLayer(std, requested) {
+    const layers = std.get(GfxControllerIdentifier).surface?.props.layers;
+    if (!layers)
+        return undefined;
+    if (requested === DEFAULT_LAYER_ID)
+        return undefined;
+    if (typeof requested === 'string' && layers[requested])
+        return requested;
+    const active = std.getOptional(CanvasActiveLayer)?.resolve() ?? DEFAULT_LAYER_ID;
+    return active === DEFAULT_LAYER_ID ? undefined : active;
+}
+/**
+ * Stamp the creation layer on `props` in place: set it, or remove the key so
+ * a default-layer model writes no `layer` at all.
+ */
+export function applyCreationLayer(std, props) {
+    const layer = resolveCreationLayer(std, props.layer);
+    if (layer === undefined) {
+        delete props.layer;
+    }
+    else {
+        props.layer = layer;
+    }
+}
+/**
+ * Every `surface.addElement` goes through this `beforeAdd` middleware, beside
+ * `EditPropsMiddlewareBuilder` (ADR 0031 §6): a framework command adding an
+ * element directly gets the same rule as the canvas tools.
+ */
+export class UserLayerMiddlewareBuilder extends SurfaceMiddlewareBuilder {
+    constructor() {
+        super(...arguments);
+        this.middleware = ctx => {
+            if (ctx.type !== 'beforeAdd')
+                return;
+            const props = { ...ctx.payload.props };
+            applyCreationLayer(this.std, props);
+            ctx.payload.props = props;
+        };
+    }
+    static { this.key = 'userLayer'; }
+}

package/dist/_pkgs/affine-block-surface/extensions/user-layers/index.d.ts

@@ -0,0 +1,5 @@
+export { CanvasActiveLayer } from './active-layer.js';
+export { createUserLayer, deleteUserLayer, moveModelsToUserLayer, renameUserLayer, reorderUserLayer, setUserLayersHiddenForEveryone, userLayerName, userLayersBottomUp, writeModelLayer, } from './actions.js';
+export { type CanvasLayerAction, type CreateLayerParams, createLayerParams, type DeleteLayerParams, deleteLayerParams, type MoveElementsToLayerParams, moveElementsToLayerParams, type RenameLayerParams, renameLayerParams, type ReorderLayerParams, reorderLayerParams, reportLayerChange, userLayerCommands, } from './commands.js';
+export { applyCreationLayer, resolveCreationLayer, sourceLayerOf, UserLayerMiddlewareBuilder, } from './creation.js';
+export { LAYER_SEED_NAME, USER_LAYER_SEED_WORDINGS } from './translations.js';

package/dist/_pkgs/affine-block-surface/extensions/user-layers/index.js

@@ -0,0 +1,5 @@
+export { CanvasActiveLayer } from './active-layer.js';
+export { createUserLayer, deleteUserLayer, moveModelsToUserLayer, renameUserLayer, reorderUserLayer, setUserLayersHiddenForEveryone, userLayerName, userLayersBottomUp, writeModelLayer, } from './actions.js';
+export { createLayerParams, deleteLayerParams, moveElementsToLayerParams, renameLayerParams, reorderLayerParams, reportLayerChange, userLayerCommands, } from './commands.js';
+export { applyCreationLayer, resolveCreationLayer, sourceLayerOf, UserLayerMiddlewareBuilder, } from './creation.js';
+export { LAYER_SEED_NAME, USER_LAYER_SEED_WORDINGS } from './translations.js';

package/dist/_pkgs/affine-block-surface/extensions/user-layers/translations.d.ts

@@ -0,0 +1,10 @@
+import type { ChromeWording } from '../../../affine-shared/services/index.js';
+/**
+ * The name a new user layer is created with (ADR 0031 §2). A SEED: the
+ * creation site resolves it through the translation seam once and writes
+ * the result into the document, where it is content from then on — a layer
+ * renamed, or opened under another locale, keeps its name.
+ */
+export declare const LAYER_SEED_NAME: ChromeWording;
+/** The seeds this package writes into a document for user layers. */
+export declare const USER_LAYER_SEED_WORDINGS: readonly ChromeWording[];

package/dist/_pkgs/affine-block-surface/extensions/user-layers/translations.js

@@ -0,0 +1,14 @@
+/**
+ * The name a new user layer is created with (ADR 0031 §2). A SEED: the
+ * creation site resolves it through the translation seam once and writes
+ * the result into the document, where it is content from then on — a layer
+ * renamed, or opened under another locale, keeps its name.
+ */
+export const LAYER_SEED_NAME = [
+    'com.labre.layer.seed.name',
+    'Layer {{n}}',
+];
+/** The seeds this package writes into a document for user layers. */
+export const USER_LAYER_SEED_WORDINGS = [
+    LAYER_SEED_NAME,
+];

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

@@ -1,6 +1,6 @@
 import type { Bound } from '../../global/gfx/index.js';
-import { type FrameworkBackgroundDef, type Ratio } from './def.js';
-import type { BackgroundModelLike } from './labels.js';
+import { type BackgroundTextDef, type FrameworkBackgroundDef, type Ratio } from './def.js';
+import { type BackgroundModelLike } from './labels.js';
 /**
  * The framework-background declaration read as EVALUATION FACTS (PF5.15/PF5.16).
  *
@@ -85,6 +85,59 @@ export interface BackgroundAxisFact {
 export declare function containingFrame<T extends {
     id: string;
 }>(bound: Bound, candidates: Iterable<T>, boundOf: (candidate: T) => Bound): T | null;
+/**
+ * One zone of ONE instance, as a reader sees it: a framework zone the instance
+ * shows, or a zone the instance declares for itself.
+ */
+export interface BackgroundZoneFact {
+    /** The declared id, or `${idPrefix}:${item.id}` for an instance zone. */
+    id: string;
+    rect: {
+        x: Ratio;
+        y: Ratio;
+        w: Ratio;
+        h: Ratio;
+    };
+    /** A framework zone's name, as declared — key, fallback and stored prop. */
+    label?: BackgroundTextDef;
+    /** An instance zone's name, as the user wrote it. */
+    name?: string;
+}
+/**
+ * Every zone ONE instance actually has: the framework's zones in the variant
+ * the instance is turned to, then the zones it declares for itself — a BPMN
+ * pool's lanes.
+ *
+ * THE answer to "which zones are on this frame", shared by the reading and the
+ * audit so they cannot disagree. Before it existed the audit concatenated every
+ * declared zone whatever the instance's variant, and could place a sub-domain
+ * on a migration chart in a classic quadrant nobody can see — the same gate
+ * the renderer and the validation engine already passed through
+ * (`backgroundInVariant`), forgotten in one reader out of three.
+ *
+ * Framework zones first, so a framework zone still wins a genuine overlap: the
+ * order the audit has always reported them in.
+ */
+export declare function backgroundZones(def: FrameworkBackgroundDef, model: BackgroundModelLike): BackgroundZoneFact[];
+/**
+ * Where the centre of `bound` sits inside the PLOT of the instance occupying
+ * `frame`, as ratios.
+ *
+ * Ratios of the plot and not of the element box: a Wardley transition drawn at
+ * `0.4` is 40 % of the PLOT, and the margin between the two is exactly where the
+ * axis titles live. Not clamped — an element just off the left edge reads as
+ * `-0.03`, which is a true and useful thing to say. `null` for a degenerate
+ * plot.
+ */
+export declare function backgroundPlotRatios(def: FrameworkBackgroundDef, frame: Bound, bound: Bound): readonly [number, number] | null;
+/**
+ * The first zone whose rectangle holds a plot-ratio point, in the order given.
+ *
+ * Inclusive on all four edges and first match wins, so a point exactly on a
+ * divider belongs to the zone declared first — the tie the audit and
+ * `bpmnLaneOf` have always broken that way.
+ */
+export declare function backgroundZoneAt<T extends Pick<BackgroundZoneFact, 'rect'>>(zones: readonly T[], at: readonly [number, number]): T | undefined;
 /** 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

@@ -1,4 +1,5 @@
-import { backgroundPlot, } from './def.js';
+import { backgroundInstanceZones, backgroundPlot, } from './def.js';
+import { backgroundInVariant } from './labels.js';
 const FORWARD = {
     horizontal: [1, 0],
     vertical: [0, -1],
@@ -60,6 +61,67 @@ export function containingFrame(bound, candidates, boundOf) {
     }
     return found;
 }
+/**
+ * Every zone ONE instance actually has: the framework's zones in the variant
+ * the instance is turned to, then the zones it declares for itself — a BPMN
+ * pool's lanes.
+ *
+ * THE answer to "which zones are on this frame", shared by the reading and the
+ * audit so they cannot disagree. Before it existed the audit concatenated every
+ * declared zone whatever the instance's variant, and could place a sub-domain
+ * on a migration chart in a classic quadrant nobody can see — the same gate
+ * the renderer and the validation engine already passed through
+ * (`backgroundInVariant`), forgotten in one reader out of three.
+ *
+ * Framework zones first, so a framework zone still wins a genuine overlap: the
+ * order the audit has always reported them in.
+ */
+export function backgroundZones(def, model) {
+    const zones = [];
+    for (const zone of def.zones ?? []) {
+        if (!backgroundInVariant(def, zone.variants, model))
+            continue;
+        zones.push({
+            id: zone.id,
+            rect: zone.rect,
+            ...(zone.label !== undefined ? { label: zone.label } : {}),
+        });
+    }
+    zones.push(...backgroundInstanceZones(def, model));
+    return zones;
+}
+/**
+ * Where the centre of `bound` sits inside the PLOT of the instance occupying
+ * `frame`, as ratios.
+ *
+ * Ratios of the plot and not of the element box: a Wardley transition drawn at
+ * `0.4` is 40 % of the PLOT, and the margin between the two is exactly where the
+ * axis titles live. Not clamped — an element just off the left edge reads as
+ * `-0.03`, which is a true and useful thing to say. `null` for a degenerate
+ * plot.
+ */
+export function backgroundPlotRatios(def, frame, bound) {
+    const plot = backgroundPlot(def, frame.w, frame.h);
+    if (!(plot.width > 0) || !(plot.height > 0))
+        return null;
+    return [
+        (bound.x + bound.w / 2 - frame.x - plot.x0) / plot.width,
+        (bound.y + bound.h / 2 - frame.y - plot.y0) / plot.height,
+    ];
+}
+/**
+ * The first zone whose rectangle holds a plot-ratio point, in the order given.
+ *
+ * Inclusive on all four edges and first match wins, so a point exactly on a
+ * divider belongs to the zone declared first — the tie the audit and
+ * `bpmnLaneOf` have always broken that way.
+ */
+export function backgroundZoneAt(zones, at) {
+    return zones.find(({ rect }) => at[0] >= rect.x &&
+        at[0] <= rect.x + rect.w &&
+        at[1] >= rect.y &&
+        at[1] <= rect.y + rect.h);
+}
 /** 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/stacking.d.ts

@@ -64,10 +64,16 @@ export declare function indexOverBackgrounds(siblings: readonly StackedElement[]
  *    it, the same raise applies — superposed boards stack in the order they
  *    were placed, each still under its own artefacts — unless it ENCLOSES that
  *    background, in which case it is the sheet the other is drawn on and stays
- *    under it ({@link encloses}). Otherwise, if it covers an artefact it
- *    overlaps, it is acting as a lid: lower it to just above the floor it lies
- *    on, or to the back of the surface when it lies on bare canvas. Otherwise
- *    nothing.
+ *    under it ({@link encloses}). Otherwise, if it was just PLACED and 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.
+ *
+ * `gesture` says which: `'placed'` (created, pasted, duplicated, inserted from
+ * a template or an import) or `'moved'`. A move never lowers a board (ADR
+ * 0033): the user may have put it above an artefact on purpose, from the
+ * selection pane or with "bring forward", and their own drag of that board
+ * must not undo it. Moved over free elements, a board now covers them.
  *
  * `siblings` are the OTHER top-level elements of the surface — canvas elements
  * and blocks alike, since the surface paints both by index — with `element`
@@ -89,7 +95,7 @@ export declare function indexOverBackgrounds(siblings: readonly StackedElement[]
  * 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;
+export declare function stackingIndexFor(element: StackedElement, siblings: readonly StackedElement[], gesture?: 'placed' | 'moved'): 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
@@ -111,9 +117,11 @@ export declare function stackedElementsOf(gfx: GfxController, exclude?: GfxModel
  *
  * 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.
+ * board drawn last covers what it was drawn around) and an element MOVED onto
+ * a board that is above it. A board moved over free elements it then hides is
+ * deliberately NOT one of them (ADR 0033): a board's depth after it is placed
+ * is the user's. 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

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

@@ -63,10 +63,16 @@ export function indexOverBackgrounds(siblings, box) {
  *    it, the same raise applies — superposed boards stack in the order they
  *    were placed, each still under its own artefacts — unless it ENCLOSES that
  *    background, in which case it is the sheet the other is drawn on and stays
- *    under it ({@link encloses}). Otherwise, if it covers an artefact it
- *    overlaps, it is acting as a lid: lower it to just above the floor it lies
- *    on, or to the back of the surface when it lies on bare canvas. Otherwise
- *    nothing.
+ *    under it ({@link encloses}). Otherwise, if it was just PLACED and 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.
+ *
+ * `gesture` says which: `'placed'` (created, pasted, duplicated, inserted from
+ * a template or an import) or `'moved'`. A move never lowers a board (ADR
+ * 0033): the user may have put it above an artefact on purpose, from the
+ * selection pane or with "bring forward", and their own drag of that board
+ * must not undo it. Moved over free elements, a board now covers them.
  *
  * `siblings` are the OTHER top-level elements of the surface — canvas elements
  * and blocks alike, since the surface paints both by index — with `element`
@@ -88,7 +94,7 @@ export function indexOverBackgrounds(siblings, box) {
  * state writes nothing — no corrupted depth, and no extra entry pushed onto
  * the history stack.
  */
-export function stackingIndexFor(element, siblings) {
+export function stackingIndexFor(element, siblings, gesture = 'placed') {
     const box = Bound.deserialize(element.xywh);
     const overlapping = siblings.filter(sibling => Bound.deserialize(sibling.xywh).isOverlapWithBound(box));
     // The stack {@link indexOverBackgrounds} is allowed to land ON, which is the
@@ -109,7 +115,10 @@ export function stackingIndexFor(element, siblings) {
     const buried = overlapping.some(sibling => sibling.isBackground &&
         sibling.index > element.index &&
         !encloses(element, box, sibling));
-    const lidding = element.isBackground &&
+    // Only where it is PLACED (ADR 0033): a board lowered by its own move would
+    // undo the depth a user gave it by hand, so a move never lowers one.
+    const lidding = gesture === 'placed' &&
+        element.isBackground &&
         overlapping.some(sibling => !sibling.isBackground && sibling.index < element.index);
     const next = buried
         ? indexOverBackgrounds(floors, box)
@@ -183,9 +192,11 @@ export function stackedElementsOf(gfx, exclude) {
  *
  * 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.
+ * board drawn last covers what it was drawn around) and an element MOVED onto
+ * a board that is above it. A board moved over free elements it then hides is
+ * deliberately NOT one of them (ADR 0033): a board's depth after it is placed
+ * is the user's. 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
@@ -206,14 +217,15 @@ export class BackgroundStackingExtension extends GfxExtension {
             return;
         this._disposable.add(surface.elementAdded.subscribe(({ id, local }) => {
             if (local)
-                this._restack(surface.getElementById(id));
+                this._restack(surface.getElementById(id), 'placed');
         }));
         this._disposable.add(surface.elementUpdated.subscribe(({ id, props, local }) => {
-            if (local && props['xywh'])
-                this._restack(surface.getElementById(id));
+            if (local && props['xywh']) {
+                this._restack(surface.getElementById(id), 'moved');
+            }
         }));
     }
-    _restack(model) {
+    _restack(model, gesture) {
         // 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)
@@ -222,7 +234,7 @@ export class BackgroundStackingExtension extends GfxExtension {
             index: model.index,
             xywh: model.xywh,
             isBackground: model instanceof FrameworkBackgroundElementModel,
-        }, stackedElementsOf(this.gfx, model));
+        }, stackedElementsOf(this.gfx, model), gesture);
         if (index !== null)
             this.gfx.updateElement(model, { index });
     }

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

@@ -4,11 +4,12 @@ import { requestConnectedFrame } from '../../affine-shared/utils/index.js';
 import { DisposableGroup } from '../../global/disposable/index.js';
 import { Bound, getBoundWithRotation, intersects, } from '../../global/gfx/index.js';
 import { GfxControllerIdentifier } from '../../std/gfx/index.js';
-import { effect } from '@preact/signals-core';
+import { effect, untracked } from '@preact/signals-core';
 import last from 'lodash-es/last.js';
 import { Subject } from 'rxjs';
 import { ElementRendererIdentifier } from '../extensions/element-renderer.js';
 import { RoughCanvas } from '../utils/rough/canvas.js';
+import { isPainted } from './paint-predicate.js';
 const STACKING_CANVAS_PADDING = 32;
 export class CanvasRenderer {
     get stackingCanvas() {
@@ -188,7 +189,7 @@ export class CanvasRenderer {
     _getLayerRenderBound(elements, viewportBounds) {
         let layerBound = null;
         for (const element of elements) {
-            const display = (element.display ?? true) && !element.hidden;
+            const display = isPainted(element, this._gfx.localVisibility);
             if (!display) {
                 continue;
             }
@@ -310,6 +311,19 @@ export class CanvasRenderer {
                 this.refresh({ type: 'all' });
             }
         }));
+        // A local hide or show changes what is painted without touching any
+        // element: repaint everything once (ADR 0031 §8). The first run only
+        // subscribes.
+        let visibilityRead = false;
+        this._disposables.add(effect(() => {
+            this._gfx.localVisibility.hiddenIds$.value;
+            this._gfx.localVisibility.hiddenLayerIds$.value;
+            if (!visibilityRead) {
+                visibilityRead = true;
+                return;
+            }
+            untracked(() => this.refresh({ type: 'all' }));
+        }));
         let wasDragging = false;
         this._disposables.add(effect(() => {
             const isDragging = this._gfx.tool.dragging$.value;
@@ -427,7 +441,7 @@ export class CanvasRenderer {
                 filter: ['canvas', 'local'],
             });
         for (const element of elements) {
-            const display = (element.display ?? true) && !element.hidden;
+            const display = isPainted(element, this._gfx.localVisibility);
             if (display && intersects(getBoundWithRotation(element), bound)) {
                 renderStats && (renderStats.visibleElementCount += 1);
                 if (this.usePlaceholder &&

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

@@ -1,6 +1,6 @@
 import { type Color, ColorScheme } from '../../affine-model/index.js';
 import type { BlockStdScope } from '../../std/index.js';
-import type { GridManager, LayerManager, SurfaceBlockModel, Viewport } from '../../std/gfx/index.js';
+import { type GridManager, type LayerManager, type SurfaceBlockModel, type Viewport } from '../../std/gfx/index.js';
 import { Subject } from 'rxjs';
 import type { Overlay } from './overlay.js';
 type EnvProvider = {
@@ -99,6 +99,8 @@ export declare class DomRenderer {
         removed: HTMLElement[];
     }>;
     constructor(options: RendererOptions);
+    /** The viewer's local hide (ADR 0031 §8), read by the paint predicate. */
+    private readonly _localVisibility;
     private _initViewport;
     private _resetSize;
     private _renderElement;

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

@@ -3,8 +3,11 @@ import { FeatureFlagService } from '../../affine-shared/services/index.js';
 import { requestConnectedFrame } from '../../affine-shared/utils/index.js';
 import { DisposableGroup } from '../../global/disposable/index.js';
 import { getBoundWithRotation, intersects, } from '../../global/gfx/index.js';
+import { GfxControllerIdentifier, } from '../../std/gfx/index.js';
+import { effect, untracked } from '@preact/signals-core';
 import { Subject } from 'rxjs';
 import { DomElementRendererIdentifier } from './dom-elements/index.js';
+import { isPainted } from './paint-predicate.js';
 const UpdateType = {
     ELEMENT_ADDED: 'element-added',
     ELEMENT_REMOVED: 'element-removed',
@@ -185,10 +188,27 @@ export class DomRenderer {
             const featureFlagService = options.std.get(FeatureFlagService);
             return featureFlagService.getFlag('enable_turbo_renderer');
         };
+        this._localVisibility = this.std.get(GfxControllerIdentifier).localVisibility;
         this._initViewport();
         this._watchSurface(options.surfaceModel);
     }
     _initViewport() {
+        // A local hide or show changes what is painted without touching any
+        // element: the whole viewport is dirty once. The first run only
+        // subscribes.
+        let visibilityRead = false;
+        this._disposables.add(effect(() => {
+            this._localVisibility.hiddenIds$.value;
+            this._localVisibility.hiddenLayerIds$.value;
+            if (!visibilityRead) {
+                visibilityRead = true;
+                return;
+            }
+            untracked(() => {
+                this._markViewportDirty();
+                this.refresh();
+            });
+        }));
         this._disposables.add(this.viewport.viewportUpdated.subscribe(() => {
             this._markViewportDirty();
             this.refresh();
@@ -386,7 +406,7 @@ export class DomRenderer {
         const visibleElementIds = new Set();
         // 1. Update dirty elements
         for (const elementModel of elementsFromGrid) {
-            const display = (elementModel.display ?? true) && !elementModel.hidden;
+            const display = isPainted(elementModel, this._localVisibility);
             if (display &&
                 intersects(getBoundWithRotation(elementModel), viewportBounds)) {
                 visibleElementIds.add(elementModel.id);
@@ -449,7 +469,7 @@ export class DomRenderer {
         });
         const visibleElementIds = new Set();
         for (const elementModel of elementsFromGrid) {
-            const display = (elementModel.display ?? true) && !elementModel.hidden;
+            const display = isPainted(elementModel, this._localVisibility);
             if (display &&
                 intersects(getBoundWithRotation(elementModel), viewportBounds)) {
                 visibleElementIds.add(elementModel.id);

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

@@ -0,0 +1,30 @@
+/**
+ * The one question every renderer site asks before it paints an element:
+ * "is this painted?".
+ *
+ * Four sites asked it inline, with the same expression copied four times — the
+ * canvas renderer's layer bound and its bound pass, the DOM renderer's full
+ * and incremental passes. ADR 0031 adds two more visibilities beside the two
+ * this reads (a viewer's local hide, a stored "hide for everyone"), and a
+ * fifth copy of a three-term conjunction is how one site ends up painting
+ * what the others skip. So the expression lives here, once.
+ *
+ * - `display` is the text editor's session flag (`edgeless-text-editor.ts`
+ *   sets it to `false` while it edits); `undefined` means painted.
+ * - `hidden` is stored, and owned by mindmap collapse alone (ADR 0031 §1).
+ * - `visibility` is what this viewer does not see (`gfx.localVisibility`, ADR
+ *   0031 §8): their own local hide, and the stored "hide for everyone" that
+ *   `GfxController` registers into the same hook (§7). The exports paint
+ *   through the same renderer, so both are left out of an SVG or PNG too:
+ *   what you see is what you export.
+ *
+ * Painting only. Picking does not read this: the stored `hidden` is already
+ * skipped by `grid.search`, the local hide by `getElementByPoint`, and
+ * `display` is deliberately still clickable.
+ */
+export declare function isPainted<T extends {
+    display?: boolean;
+    hidden?: boolean;
+}>(element: T, visibility?: {
+    isHidden(element: NoInfer<T>): boolean;
+}): boolean;

package/dist/_pkgs/affine-block-surface/renderer/paint-predicate.js

@@ -0,0 +1,29 @@
+/**
+ * The one question every renderer site asks before it paints an element:
+ * "is this painted?".
+ *
+ * Four sites asked it inline, with the same expression copied four times — the
+ * canvas renderer's layer bound and its bound pass, the DOM renderer's full
+ * and incremental passes. ADR 0031 adds two more visibilities beside the two
+ * this reads (a viewer's local hide, a stored "hide for everyone"), and a
+ * fifth copy of a three-term conjunction is how one site ends up painting
+ * what the others skip. So the expression lives here, once.
+ *
+ * - `display` is the text editor's session flag (`edgeless-text-editor.ts`
+ *   sets it to `false` while it edits); `undefined` means painted.
+ * - `hidden` is stored, and owned by mindmap collapse alone (ADR 0031 §1).
+ * - `visibility` is what this viewer does not see (`gfx.localVisibility`, ADR
+ *   0031 §8): their own local hide, and the stored "hide for everyone" that
+ *   `GfxController` registers into the same hook (§7). The exports paint
+ *   through the same renderer, so both are left out of an SVG or PNG too:
+ *   what you see is what you export.
+ *
+ * Painting only. Picking does not read this: the stored `hidden` is already
+ * skipped by `grid.search`, the local hide by `getElementByPoint`, and
+ * `display` is deliberately still clickable.
+ */
+export function isPainted(element, visibility) {
+    return ((element.display ?? true) &&
+        !element.hidden &&
+        !(visibility?.isHidden(element) ?? false));
+}

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

@@ -108,6 +108,12 @@ let SurfaceBlockComponent = (() => {
       z-index: 0;
     }
 
+    /* ADR 0031 §11: off removes the grid here too (CanvasGrid.visible$). */
+    affine-edgeless-root[data-grid-hidden]
+      .affine-block-children-container.edgeless {
+      background-image: none;
+    }
+
     .affine-edgeless-block-child {
       position: absolute;
       transform-origin: center;

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

@@ -9,6 +9,11 @@ export const SurfaceBlockSchema = defineBlockSchema({
     flavour: 'affine:surface',
     props: (internalPrimitives) => ({
         elements: internalPrimitives.Boxed(new Y.Map()),
+        // ADR 0031 §2: optional, `undefined` default, so the load pass writes
+        // nothing and the schema version stays 5.
+        showGrid: undefined,
+        // ADR 0031 §2: user layers, absent until the first one is created.
+        layers: undefined,
     }),
     metadata: {
         version: 5,