@formicoidea/labre-core 0.42.0 → 0.45.0

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/element-highlight-overlay.js

@@ -1,4 +1,4 @@
-import { ThemeProvider } from '../../affine-shared/services/index.js';
+import { getChromeAccentColor } from '../../affine-shared/services/index.js';
 import { DisposableGroup } from '../../global/disposable/index.js';
 import { effect } from '@preact/signals-core';
 import { Overlay } from './overlay.js';
@@ -8,8 +8,6 @@ const HIGHLIGHT_STROKE_WIDTH = 2;
 const HIGHLIGHT_GAP = 4;
 /** Ring corner radius, in screen pixels. */
 const HIGHLIGHT_RADIUS = 4;
-/** Used when no theme is provided, matches the legacy frame highlight. */
-const FALLBACK_HIGHLIGHT_COLOR = '#1E96EB';
 /**
  * Draws the transient emphasis ring around the elements held by
  * `gfx.highlight` (`ElementHighlightManager`).
@@ -20,10 +18,7 @@ const FALLBACK_HIGHLIGHT_COLOR = '#1E96EB';
 export class ElementHighlightOverlay extends Overlay {
     static { this.overlayName = 'element-highlight'; }
     get _strokeColor() {
-        return (this.gfx.std
-            .getOptional(ThemeProvider)
-            ?.getCssVariableColor('--affine-primary-color') ??
-            FALLBACK_HIGHLIGHT_COLOR);
+        return getChromeAccentColor(this.gfx.std);
     }
     constructor(gfx) {
         super(gfx);

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,

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

@@ -58,7 +58,11 @@ export class SurfaceBlockTransformer extends BaseBlockTransformer {
             yMap.set(key, element);
         });
         const elements = this._internal.Boxed(yMap);
+        // Every other surface prop (ADR 0031: `layers`, `showGrid`, and any key
+        // a newer client wrote) crosses the snapshot unchanged; only `elements`
+        // needs rebuilding into a Y.Map.
         snapshotRet.props = {
+            ...snapshotRet.props,
             elements,
         };
         return snapshotRet;
@@ -79,6 +83,7 @@ export class SurfaceBlockTransformer extends BaseBlockTransformer {
             });
         }
         snapshot.props = {
+            ...snapshot.props,
             elements: value,
         };
         return snapshot;

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

@@ -78,6 +78,9 @@ export class DefaultTool extends BaseTool {
     static { this.toolName = 'default'; }
     _scrollViewport(delta) {
         this.gfx.viewport.applyDeltaCenter(delta[0], delta[1]);
+        // `viewportMoved` is what an element move listens to in order to keep the
+        // dragged elements under a pointer that stays still while the board pans.
+        this.gfx.viewport.viewportMoved.next(delta);
     }
     /**
      * Get the end position of the dragging area in the model coordinate
@@ -144,7 +147,7 @@ export class DefaultTool extends BaseTool {
             }
         }
     }
-    initializeDragState(dragType, event) {
+    initializeDragState(dragType, event, cloned = false) {
         this.dragType = dragType;
         this._clearDisposable();
         this._disposables = new DisposableGroup();
@@ -161,11 +164,16 @@ export class DefaultTool extends BaseTool {
         }
         if (this.dragType === DefaultModeDragType.ContentMoving) {
             if (this.interactivity) {
-                this.doc.captureSync();
+                // An alt+drag captured BEFORE its clone: a capture here would close
+                // the step between the copy and its move, and the first undo would
+                // only put the copy back on its source (`alt-drag-clone.spec.ts`).
+                if (!cloned)
+                    this.doc.captureSync();
                 this.interactivity.handleElementMove({
                     movingElements: this._toBeMoved,
                     event: event.raw,
                     onDragEnd: () => {
+                        this._stopEdgeScrolling();
                         this.doc.captureSync();
                     },
                 });
@@ -230,6 +238,17 @@ export class DefaultTool extends BaseTool {
                 break;
             }
             case DefaultModeDragType.ContentMoving: {
+                // Only an accepted move pans: `handleElementMove` refuses a readonly
+                // store and an extension may cancel it, and neither leaves an active
+                // interaction behind.
+                const moving = this.interactivity?.activeInteraction$.peek()?.type === 'move';
+                const moveDelta = moving ? calPanDelta(viewport, e) : null;
+                if (moveDelta) {
+                    this._enableEdgeScrolling(moveDelta);
+                }
+                else {
+                    this._stopEdgeScrolling();
+                }
                 break;
             }
             case DefaultModeDragType.NativeEditing: {
@@ -266,12 +285,16 @@ export class DefaultTool extends BaseTool {
             }
         });
         this._toBeMoved = Array.from(toBeMoved);
-        // If alt key is pressed and content is moving, clone the content
-        if (dragType === DefaultModeDragType.ContentMoving && e.keys.alt) {
+        // If alt key is pressed and content is moving, clone the content. One
+        // gesture, one undo step: close what came before, then nothing closes the
+        // step between the clone's writes and the move's end.
+        const cloning = dragType === DefaultModeDragType.ContentMoving && e.keys.alt;
+        if (cloning) {
+            this.doc.captureSync();
             await this._cloneContent();
         }
         // Set up drag state
-        this.initializeDragState(dragType, e);
+        this.initializeDragState(dragType, e, cloning);
     }
     mounted() {
         this.disposable.add(effect(() => {

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

@@ -1,8 +1,9 @@
 import { ViewExtensionProvider, } from '../affine-ext-loader/index.js';
+import { CanvasGrid, CanvasLocalVisibility, } from '../affine-shared/services/index.js';
 import { BlockViewExtension, CommandExtension, FlavourExtension, } from '../std/index.js';
 import { literal } from 'lit/static-html.js';
 import { effects } from './effects.js';
-import { auditCommands, EdgelessCRUDExtension, EdgelessLegacySlotExtension, EditPropsMiddlewareBuilder, exportSvgCommands, exportSvgToolbarExtension, mapQualityCommands, mapQualityWidget, ReadingManager, readingProposalWidget, readingToolbarExtension, SpotlightManager, ValidationManager, validationExceptionToolbarExtension, ValidationOverlay, violationDetailWidget, } from './extensions/index.js';
+import { auditCommands, CanvasActiveLayer, canvasGridCommands, EdgelessCRUDExtension, EdgelessLegacySlotExtension, EditPropsMiddlewareBuilder, exportSvgCommands, exportSvgToolbarExtension, mapQualityCommands, mapQualityWidget, ReadingManager, readingProposalWidget, readingToolbarExtension, selectionPaneCommands, SelectionPaneModel, SpotlightManager, UserLayerMiddlewareBuilder, userLayerCommands, ValidationManager, validationExceptionToolbarExtension, ValidationOverlay, violationDetailWidget, } from './extensions/index.js';
 import { ExportManagerExtension } from './extensions/export-manager/export-manager.js';
 import { BackgroundStackingExtension } from './framework-background/stacking.js';
 import { ElementHighlightOverlay } from './renderer/element-highlight-overlay.js';
@@ -72,6 +73,27 @@ export class SurfaceViewExtension extends ViewExtensionProvider {
             // (`docs/adr/0025`). Nothing is offered until a board is selected.
             context.register(CommandExtension(exportSvgCommands));
             context.register(exportSvgToolbarExtension);
+            // The selection pane's headless half (ADR 0031): the live tree a pane
+            // renders from, and the commands its rows run. Core chrome, never a
+            // framework's, and nothing it lists is gated — a flag gates tooling,
+            // the rows are content. The panel itself is the edgeless toolbar's.
+            context.register(SelectionPaneModel);
+            // This viewer's local hide (ADR 0031 §8): registers into
+            // `gfx.localVisibility` and persists per document, never in it.
+            context.register(CanvasLocalVisibility);
+            context.register(CommandExtension(selectionPaneCommands));
+            // The grid as a setting (ADR 0031 §11): this viewer's override, the
+            // document's `showGrid`, the host default, the library default. Read by
+            // the edgeless root's background, the surface container and the PNG
+            // export; previews follow the document setting alone.
+            context.register(CanvasGrid);
+            context.register(CommandExtension(canvasGridCommands));
+            // User layers (ADR 0031 §2-§6): the viewer's active layer (session
+            // only), the `beforeAdd` middleware that stamps it on what is created,
+            // and the commands the pane's layer rows run. Content, never gated.
+            context.register(CanvasActiveLayer);
+            context.register(UserLayerMiddlewareBuilder);
+            context.register(CommandExtension(userLayerCommands));
         }
         else {
             context.register(BlockViewExtension('affine:surface', literal `affine-surface-void`));

package/dist/_pkgs/affine-block-surface-ref/configs/tooltips.js

@@ -6,8 +6,8 @@ export const EdgelessTooltip = html `<svg width="170" height="106" viewBox="0 0
 <rect width="170" height="106" rx="2" fill="white"/>
 </mask>
 <g mask="url(#mask0_16460_1252)">
-<rect x="100.5" y="42.6565" width="141" height="51" stroke="#1E96EB" stroke-width="3" stroke-dasharray="5 5"/>
-<circle cx="101.5" cy="43.5" r="6" fill="white" stroke="#1E96EB" stroke-width="3"/>
+<rect x="100.5" y="42.6565" width="141" height="51" stroke="var(--affine-primary-color)" stroke-width="3" stroke-dasharray="5 5"/>
+<circle cx="101.5" cy="43.5" r="6" fill="white" stroke="var(--affine-primary-color)" stroke-width="3"/>
 <rect x="105" y="8" width="59" height="26" rx="10" fill="black" fill-opacity="0.1"/>
 <text fill="#121212" xml:space="preserve" style="white-space: pre" font-family="Inter" font-size="12" letter-spacing="0em"><tspan x="117" y="25.3636">Group</tspan></text>
 <mask id="mask1_16460_1252" style="mask-type:alpha" maskUnits="userSpaceOnUse" x="0" y="0" width="98" height="106">

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

@@ -39,7 +39,7 @@ import { Peekable } from '../affine-components/peek/index.js';
 import { ViewExtensionManagerIdentifier } from '../affine-ext-loader/index.js';
 import { RefNodeSlotsProvider } from '../affine-inline-reference/index.js';
 import { FrameBlockModel, } from '../affine-model/index.js';
-import { BlockCommentManager, DocModeProvider, EditPropsStore, ThemeProvider, ToolbarRegistryIdentifier, ViewportElementExtension, } from '../affine-shared/services/index.js';
+import { BlockCommentManager, DocModeProvider, documentShowsGrid, EditPropsStore, ThemeProvider, ToolbarRegistryIdentifier, ViewportElementExtension, } from '../affine-shared/services/index.js';
 import { unsafeCSSVarV2 } from '../affine-shared/theme/index.js';
 import { requestConnectedFrame } from '../affine-shared/utils/index.js';
 import { DisposableGroup } from '../global/disposable/index.js';
@@ -128,6 +128,11 @@ let SurfaceRefBlockComponent = (() => {
       );
     }
 
+    /* ADR 0031 §11: a reference follows the document's showGrid alone. */
+    .ref-content.grid-hidden {
+      background: var(--affine-background-primary-color);
+    }
+
     .ref-viewport {
       max-width: 100%;
       margin: 0 auto;
@@ -351,7 +356,12 @@ let SurfaceRefBlockComponent = (() => {
             const aspectRatio = h !== 0 ? w / h : 1;
             const _previewSpec = this._previewSpec.concat(this._runtimePreviewExt);
             const edgelessTheme = this.std.get(ThemeProvider).edgeless$.value;
-            return html `<div class="ref-content">
+            // A reference is a picture of the referenced document: its saved grid,
+            // never this viewer's override.
+            const showGrid = documentShowsGrid(this._previewDoc ? getSurfaceBlock(this._previewDoc) : null);
+            return html `<div
+      class=${classMap({ 'ref-content': true, 'grid-hidden': !showGrid })}
+    >
       <div
         class="ref-viewport"
         style=${styleMap({

package/dist/_pkgs/affine-components/color-picker/palette-carousel.js

@@ -125,6 +125,11 @@ export const paletteCarouselStyles = css `
     /* Nine pages fit without scrolling; the cap is a seatbelt for a tenth. */
     max-height: 280px;
     overflow-y: auto;
+    /* Same trap as the popup box that holds this list (issue #392, see
+     * toolbar/menu-button.ts): an overflow-y of its own makes the other axis
+     * scrollable too, and this list is one long page name — a translation, or
+     * a tenth page — away from overflowing it. */
+    overflow-x: hidden;
     overscroll-behavior: contain;
     animation: palette-carousel-settle ${springDuration} ${springEasing};
   }

package/dist/_pkgs/affine-components/color-picker/styles.js

@@ -109,7 +109,7 @@ export const COLOR_PICKER_STYLE = css `
   }
   .modes .mode button[active] {
     pointer-events: none;
-    outline: 2px solid var(--affine-brand-color, #1e96eb);
+    outline: 2px solid var(--affine-brand-color);
   }
 
   .content {

package/dist/_pkgs/affine-components/context-menu/button.js

@@ -90,6 +90,20 @@ let MenuButton = (() => {
     .affine-menu-button.delete-item:hover .affine-menu-action-text {
       color: var(--affine-error-color);
     }
+
+    /*
+      An entry whose effect reaches every viewer of the document ("Hide for
+      everyone", ADR 0031): the theme's warning tokens, always on, so it reads
+      differently from its local twin before it is hovered.
+    */
+    .affine-menu-button.warning-item,
+    .affine-menu-button.warning-item .affine-menu-action-text {
+      color: var(--affine-warning-color);
+    }
+
+    .affine-menu-button.warning-item:hover {
+      background-color: var(--affine-background-warning-color);
+    }
   `; }
         connectedCallback() {
             super.connectedCallback();
@@ -264,7 +278,9 @@ export const menuButtonItems = {
         const data = {
             content: () => html `
           ${config.checked.value
-                ? CheckBoxCheckSolidIcon({ style: `color:#1E96EB` })
+                ? CheckBoxCheckSolidIcon({
+                    style: `color:var(--affine-primary-color)`,
+                })
                 : CheckBoxUnIcon()}
           <div class="affine-menu-action-text">
             ${config.label?.() ?? config.name}