@formicoidea/labre-core 0.43.1 → 0.45.0

package/dist/_pkgs/affine-shared/services/canvas-grid.js

@@ -0,0 +1,109 @@
+import { LifeCycleWatcher } from '../../std/index.js';
+import { GfxControllerIdentifier, } from '../../std/gfx/index.js';
+import { computed, signal } from '@preact/signals-core';
+import { EditPropsStore } from './edit-props-store.js';
+import { EditorSettingProvider } from './editor-setting-service.js';
+/**
+ * The four levels of ADR 0031 §11, nearest decision first: the viewer's own
+ * override, the document's "saved for everyone" setting, the host's default
+ * (`edgelessShowGrid`), and the library default — on. `undefined` at a level
+ * means "nobody decided here".
+ */
+export function resolveCanvasGrid(levels) {
+    if (levels.local !== undefined) {
+        return { visible: levels.local, source: 'local' };
+    }
+    if (levels.document !== undefined) {
+        return { visible: levels.document, source: 'document' };
+    }
+    if (levels.host !== undefined) {
+        return { visible: levels.host, source: 'host' };
+    }
+    return { visible: true, source: 'library' };
+}
+/**
+ * What a surface stored for everyone, read reactively. Previews (the
+ * read-only edgeless preview, a surface-ref) follow THIS and the library
+ * default only: they are a picture of the document, not a viewer's session,
+ * so neither a viewer override nor a host default reaches them.
+ */
+export function documentShowsGrid(surface) {
+    return surface?.props.showGrid$.value !== false;
+}
+/**
+ * The canvas grid as THIS viewer sees it (ADR 0031 §11).
+ *
+ * - **The toggle is local**: it writes the viewer's override, an
+ *   `EditPropsStore` `localStorage` prop keyed by document id like the
+ *   viewport, so it survives a reload and produces no Yjs update — a reader
+ *   may toggle it too.
+ * - **"Save for everyone"** writes the current state into the surface's
+ *   `showGrid` and clears the saver's override, so they see what everyone
+ *   sees. Refused on a read-only store; writes nothing when the document
+ *   already says the same.
+ *
+ * Both containers that paint the grid (the edgeless root's background and
+ * the surface container) and the PNG export read `visible$`.
+ */
+export class CanvasGrid extends LifeCycleWatcher {
+    constructor() {
+        super(...arguments);
+        this._local$ = signal(undefined);
+        this._resolved$ = computed(() => resolveCanvasGrid({
+            local: this._local$.value,
+            document: this._surface()?.props.showGrid$.value,
+            host: this.std.getOptional(EditorSettingProvider)?.setting$.value
+                .edgelessShowGrid,
+        }));
+        /** Whether this viewer sees the grid. */
+        this.visible$ = computed(() => this._resolved$.value.visible);
+        /** Which level decided `visible$`. */
+        this.source$ = computed(() => this._resolved$.value.source);
+    }
+    static { this.key = 'canvas-grid'; }
+    _surface() {
+        return this.std.get(GfxControllerIdentifier).surface$.value;
+    }
+    /**
+     * Flip the grid for this viewer only. Answers the new visibility.
+     */
+    toggle() {
+        const visible = !this.visible$.peek();
+        this._local$.value = visible;
+        this.std.getOptional(EditPropsStore)?.setStorage('localShowGrid', visible);
+        return visible;
+    }
+    /**
+     * Store what this viewer sees as the document's setting, and drop their
+     * override. Answers the saved value, or `null` when nothing was written
+     * (read-only store, no surface, or the document already said so).
+     */
+    saveForEveryone() {
+        const surface = this._surface();
+        if (!surface || this.std.store.readonly)
+            return null;
+        const visible = this.visible$.peek();
+        this._clearLocal();
+        if (surface.props.showGrid === visible)
+            return null;
+        this.std.store.captureSync();
+        this.std.store.transact(() => {
+            surface.props.showGrid = visible;
+        });
+        this.std.store.captureSync();
+        return visible;
+    }
+    _clearLocal() {
+        if (this._local$.peek() === undefined)
+            return;
+        this._local$.value = undefined;
+        this.std.getOptional(EditPropsStore)?.removeStorage('localShowGrid');
+    }
+    mounted() {
+        super.mounted();
+        const stored = this.std
+            .getOptional(EditPropsStore)
+            ?.getStorage('localShowGrid');
+        this._local$.value = stored ?? undefined;
+    }
+}

package/dist/_pkgs/affine-shared/services/canvas-local-visibility.d.ts

@@ -0,0 +1,64 @@
+import { LifeCycleWatcher } from '../../std/index.js';
+import { type ReadonlySignal } from '@preact/signals-core';
+/**
+ * Hide is LOCAL by default (ADR 0031 §1, §8): what this viewer hid on this
+ * document's canvas, and nothing anybody else can see.
+ *
+ * - **Never written to the document.** The ids live in a signal and persist
+ *   through `EditPropsStore`'s `localHiddenElements`, a `localStorage` prop
+ *   keyed by document id exactly like the viewport — so a reload keeps them
+ *   (open point 7, resolved at acceptance) and no Yjs update is ever produced.
+ * - **Pruned on load**: ids the document no longer has are dropped the first
+ *   time the surface is there to ask, so the list does not grow forever.
+ * - **Not `display`**: the canvas text editor owns that flag and closing it on
+ *   a locally hidden text would unhide it.
+ *
+ * The signal is registered into `gfx.localVisibility`, the per-editor hook the
+ * renderers, the DOM block views, pointer picking and the marquee read. It is
+ * never read by `grid.search`: rules, legends and semantic exports count a
+ * hidden element, because hiding is not deleting.
+ *
+ * Not gated by `store.readonly`: hiding is a way of LOOKING at a document, so
+ * a reader may do it — nothing they do here reaches the document.
+ *
+ * Whole user layers hide the same way (stage 7): a second set of ids, kept
+ * and persisted beside the first (`localHiddenLayers`), registered with
+ * `gfx.localVisibility.registerLayers` — every model whose effective layer
+ * is in it is hidden for this viewer.
+ */
+export declare class CanvasLocalVisibility extends LifeCycleWatcher {
+    static key: string;
+    private readonly _hiddenIds$;
+    private readonly _hiddenLayerIds$;
+    private _disposers;
+    /** The ids this viewer hid. */
+    get hiddenIds$(): ReadonlySignal<ReadonlySet<string>>;
+    /** The user layers this viewer hid. */
+    get hiddenLayerIds$(): ReadonlySignal<ReadonlySet<string>>;
+    isHidden(id: string): boolean;
+    /** Hide whole user layers for this viewer. Answers how many changed. */
+    hideLayers(ids: Iterable<string>): number;
+    /** Show user layers again. Answers how many were hidden. */
+    showLayers(ids: Iterable<string>): number;
+    /** Hide `ids`. Answers how many were not hidden yet. */
+    hide(ids: Iterable<string>): number;
+    /** Show `ids` again. Answers how many were hidden. */
+    show(ids: Iterable<string>): number;
+    /**
+     * Show every element this viewer hid. Answers how many were hidden.
+     * Hidden layers are {@link showAllLayers}'s, so each count reports one
+     * target.
+     */
+    showAll(): number;
+    /** Show every layer this viewer hid. Answers how many were hidden. */
+    showAllLayers(): number;
+    private _commitLayers;
+    private _commit;
+    mounted(): void;
+    /**
+     * Restore the hidden layers, pruned of layers the surface no longer has —
+     * the first time the surface is there to ask.
+     */
+    private _restoreLayers;
+    unmounted(): void;
+}

package/dist/_pkgs/affine-shared/services/canvas-local-visibility.js

@@ -0,0 +1,192 @@
+import { LifeCycleWatcher } from '../../std/index.js';
+import { DEFAULT_LAYER_ID, GfxControllerIdentifier } from '../../std/gfx/index.js';
+import { effect, signal } from '@preact/signals-core';
+import { EditPropsStore } from './edit-props-store.js';
+/**
+ * Hide is LOCAL by default (ADR 0031 §1, §8): what this viewer hid on this
+ * document's canvas, and nothing anybody else can see.
+ *
+ * - **Never written to the document.** The ids live in a signal and persist
+ *   through `EditPropsStore`'s `localHiddenElements`, a `localStorage` prop
+ *   keyed by document id exactly like the viewport — so a reload keeps them
+ *   (open point 7, resolved at acceptance) and no Yjs update is ever produced.
+ * - **Pruned on load**: ids the document no longer has are dropped the first
+ *   time the surface is there to ask, so the list does not grow forever.
+ * - **Not `display`**: the canvas text editor owns that flag and closing it on
+ *   a locally hidden text would unhide it.
+ *
+ * The signal is registered into `gfx.localVisibility`, the per-editor hook the
+ * renderers, the DOM block views, pointer picking and the marquee read. It is
+ * never read by `grid.search`: rules, legends and semantic exports count a
+ * hidden element, because hiding is not deleting.
+ *
+ * Not gated by `store.readonly`: hiding is a way of LOOKING at a document, so
+ * a reader may do it — nothing they do here reaches the document.
+ *
+ * Whole user layers hide the same way (stage 7): a second set of ids, kept
+ * and persisted beside the first (`localHiddenLayers`), registered with
+ * `gfx.localVisibility.registerLayers` — every model whose effective layer
+ * is in it is hidden for this viewer.
+ */
+export class CanvasLocalVisibility extends LifeCycleWatcher {
+    constructor() {
+        super(...arguments);
+        this._hiddenIds$ = signal(new Set());
+        this._hiddenLayerIds$ = signal(new Set());
+        this._disposers = [];
+    }
+    static { this.key = 'canvas-local-visibility'; }
+    /** The ids this viewer hid. */
+    get hiddenIds$() {
+        return this._hiddenIds$;
+    }
+    /** The user layers this viewer hid. */
+    get hiddenLayerIds$() {
+        return this._hiddenLayerIds$;
+    }
+    isHidden(id) {
+        return this._hiddenIds$.value.has(id);
+    }
+    /** Hide whole user layers for this viewer. Answers how many changed. */
+    hideLayers(ids) {
+        const next = new Set(this._hiddenLayerIds$.peek());
+        let changed = 0;
+        for (const id of ids) {
+            if (next.has(id))
+                continue;
+            next.add(id);
+            changed++;
+        }
+        if (changed)
+            this._commitLayers(next);
+        return changed;
+    }
+    /** Show user layers again. Answers how many were hidden. */
+    showLayers(ids) {
+        const next = new Set(this._hiddenLayerIds$.peek());
+        let changed = 0;
+        for (const id of ids) {
+            if (next.delete(id))
+                changed++;
+        }
+        if (changed)
+            this._commitLayers(next);
+        return changed;
+    }
+    /** Hide `ids`. Answers how many were not hidden yet. */
+    hide(ids) {
+        const next = new Set(this._hiddenIds$.peek());
+        let changed = 0;
+        for (const id of ids) {
+            if (next.has(id))
+                continue;
+            next.add(id);
+            changed++;
+        }
+        if (changed)
+            this._commit(next);
+        return changed;
+    }
+    /** Show `ids` again. Answers how many were hidden. */
+    show(ids) {
+        const next = new Set(this._hiddenIds$.peek());
+        let changed = 0;
+        for (const id of ids) {
+            if (next.delete(id))
+                changed++;
+        }
+        if (changed)
+            this._commit(next);
+        return changed;
+    }
+    /**
+     * Show every element this viewer hid. Answers how many were hidden.
+     * Hidden layers are {@link showAllLayers}'s, so each count reports one
+     * target.
+     */
+    showAll() {
+        const count = this._hiddenIds$.peek().size;
+        if (count)
+            this._commit(new Set());
+        return count;
+    }
+    /** Show every layer this viewer hid. Answers how many were hidden. */
+    showAllLayers() {
+        const count = this._hiddenLayerIds$.peek().size;
+        if (count)
+            this._commitLayers(new Set());
+        return count;
+    }
+    _commitLayers(next) {
+        this._hiddenLayerIds$.value = next;
+        this.std
+            .getOptional(EditPropsStore)
+            ?.setStorage('localHiddenLayers', [...next]);
+    }
+    _commit(next) {
+        this._hiddenIds$.value = next;
+        this.std
+            .getOptional(EditPropsStore)
+            ?.setStorage('localHiddenElements', [...next]);
+    }
+    mounted() {
+        super.mounted();
+        const gfx = this.std.get(GfxControllerIdentifier);
+        this._disposers.push(gfx.localVisibility.register(this._hiddenIds$));
+        this._disposers.push(gfx.localVisibility.registerLayers(this._hiddenLayerIds$));
+        this._restoreLayers();
+        const stored = this.std.getOptional(EditPropsStore)?.getStorage('localHiddenElements') ??
+            [];
+        if (!stored.length)
+            return;
+        // The surface may arrive after mount; prune the first time it is there.
+        let pruned = false;
+        const stop = effect(() => {
+            if (pruned || !gfx.surface$.value)
+                return;
+            pruned = true;
+            const kept = stored.filter(id => gfx.getElementById(id) !== null);
+            if (kept.length === stored.length) {
+                this._hiddenIds$.value = new Set(kept);
+            }
+            else {
+                this._commit(new Set(kept));
+            }
+        });
+        this._disposers.push(stop);
+    }
+    /**
+     * Restore the hidden layers, pruned of layers the surface no longer has —
+     * the first time the surface is there to ask.
+     */
+    _restoreLayers() {
+        const gfx = this.std.get(GfxControllerIdentifier);
+        const stored = this.std.getOptional(EditPropsStore)?.getStorage('localHiddenLayers') ??
+            [];
+        if (!stored.length)
+            return;
+        let pruned = false;
+        const stop = effect(() => {
+            const surface = gfx.surface$.value;
+            if (pruned || !surface)
+                return;
+            pruned = true;
+            const layers = surface.props.layers ?? {};
+            // The default layer exists with or without its record (ADR 0031
+            // amendments): a hide of it is never a layer the document lost.
+            const kept = stored.filter(id => id === DEFAULT_LAYER_ID || id in layers);
+            if (kept.length === stored.length) {
+                this._hiddenLayerIds$.value = new Set(kept);
+            }
+            else {
+                this._commitLayers(new Set(kept));
+            }
+        });
+        this._disposers.push(stop);
+    }
+    unmounted() {
+        this._disposers.forEach(dispose => dispose());
+        this._disposers = [];
+        super.unmounted();
+    }
+}

package/dist/_pkgs/affine-shared/services/edit-props-store.d.ts

@@ -47,6 +47,25 @@ declare const LocalPropsSchema: z.ZodObject<{
     presentNoFrameToastShown: z.ZodBoolean;
     autoHideEmbedHTMLFullScreenToolbar: z.ZodBoolean;
     connectorCenterAnchor: z.ZodDefault<z.ZodBoolean>;
+    /**
+     * The ids this viewer hid on this document's canvas (ADR 0031 §8). Per
+     * viewer and per document, like the viewport; never written to the
+     * document. Owned by `CanvasLocalVisibility`.
+     */
+    localHiddenElements: z.ZodArray<z.ZodString, "many">;
+    /**
+     * The user layers this viewer hid on this document's canvas (ADR 0031 §8,
+     * stage 7). Same owner, same key scheme, same lifetime as
+     * `localHiddenElements`; a separate key so the element list keeps the shape
+     * it already has in viewers' storage.
+     */
+    localHiddenLayers: z.ZodArray<z.ZodString, "many">;
+    /**
+     * This viewer's grid override on this document's canvas (ADR 0031 §11),
+     * keyed like the viewport. Absent = the document, the host or the library
+     * decides. Owned by `CanvasGrid`.
+     */
+    localShowGrid: z.ZodBoolean;
 }, "strip", z.ZodTypeAny, {
     viewport: {
         centerX: number;
@@ -62,6 +81,9 @@ declare const LocalPropsSchema: z.ZodObject<{
     presentNoFrameToastShown: boolean;
     autoHideEmbedHTMLFullScreenToolbar: boolean;
     connectorCenterAnchor: boolean;
+    localHiddenElements: string[];
+    localHiddenLayers: string[];
+    localShowGrid: boolean;
 }, {
     viewport: {
         centerX: number;
@@ -76,6 +98,9 @@ declare const LocalPropsSchema: z.ZodObject<{
     presentHideToolbar: boolean;
     presentNoFrameToastShown: boolean;
     autoHideEmbedHTMLFullScreenToolbar: boolean;
+    localHiddenElements: string[];
+    localHiddenLayers: string[];
+    localShowGrid: boolean;
     connectorCenterAnchor?: boolean | undefined;
 }>;
 type SessionProps = z.infer<typeof SessionPropsSchema>;
@@ -416,6 +441,8 @@ export declare class EditPropsStore extends LifeCycleWatcher {
      * session that turns read-only before unmounting stops writing too.
      */
     saveViewport(viewport: StorageProps['viewport']): void;
+    /** Forget a stored prop, so the next `getStorage` answers `null`. */
+    removeStorage(key: StoragePropsKey): void;
     setStorage<T extends StoragePropsKey>(key: T, value: StorageProps[T]): void;
     unmounted(): void;
 }

package/dist/_pkgs/affine-shared/services/edit-props-store.js

@@ -37,6 +37,25 @@ const LocalPropsSchema = z.object({
     presentNoFrameToastShown: z.boolean(),
     autoHideEmbedHTMLFullScreenToolbar: z.boolean(),
     connectorCenterAnchor: z.boolean().default(false),
+    /**
+     * The ids this viewer hid on this document's canvas (ADR 0031 §8). Per
+     * viewer and per document, like the viewport; never written to the
+     * document. Owned by `CanvasLocalVisibility`.
+     */
+    localHiddenElements: z.array(z.string()),
+    /**
+     * The user layers this viewer hid on this document's canvas (ADR 0031 §8,
+     * stage 7). Same owner, same key scheme, same lifetime as
+     * `localHiddenElements`; a separate key so the element list keeps the shape
+     * it already has in viewers' storage.
+     */
+    localHiddenLayers: z.array(z.string()),
+    /**
+     * This viewer's grid override on this document's canvas (ADR 0031 §11),
+     * keyed like the viewport. Absent = the document, the host or the library
+     * decides. Owned by `CanvasGrid`.
+     */
+    localShowGrid: z.boolean(),
 });
 function isLocalProp(key) {
     return key in LocalPropsSchema.shape;
@@ -45,6 +64,11 @@ function isSessionProp(key) {
     return key in SessionPropsSchema.shape;
 }
 function customizer(_target, source) {
+    // `mergeWith` assigns a primitive source as-is whatever the customizer says,
+    // so only an object can need one; skipping the schema parse for the rest is
+    // what keeps a paste of N elements from parsing every prop of every one.
+    if (source === null || typeof source !== 'object')
+        return;
     if (ColorSchema.safeParse(source).success ||
         source instanceof Y.Text ||
         source instanceof Y.Array ||
@@ -107,6 +131,12 @@ export class EditPropsStore extends LifeCycleWatcher {
                 return 'blocksuite:embedHTML:autoHideFullScreenToolbar';
             case 'connectorCenterAnchor':
                 return 'blocksuite:connector:centerAnchor';
+            case 'localHiddenElements':
+                return 'blocksuite:' + id + ':localHiddenElements';
+            case 'localHiddenLayers':
+                return 'blocksuite:' + id + ':localHiddenLayers';
+            case 'localShowGrid':
+                return 'blocksuite:' + id + ':localShowGrid';
             default:
                 return key;
         }
@@ -171,6 +201,10 @@ export class EditPropsStore extends LifeCycleWatcher {
             return;
         this.setStorage('viewport', viewport);
     }
+    /** Forget a stored prop, so the next `getStorage` answers `null`. */
+    removeStorage(key) {
+        this._getStorage(key).removeItem(this._getStorageKey(key));
+    }
     setStorage(key, value) {
         const oldValue = this.getStorage(key);
         this._getStorage(key).setItem(this._getStorageKey(key), JSON.stringify(value));

package/dist/_pkgs/affine-shared/services/editor-setting-service.d.ts

@@ -5,6 +5,7 @@ import { z } from 'zod';
 export declare const GeneralSettingSchema: z.ZodObject<{
     edgelessScrollZoom: z.ZodDefault<z.ZodBoolean>;
     edgelessDisableScheduleUpdate: z.ZodDefault<z.ZodBoolean>;
+    edgelessShowGrid: z.ZodOptional<z.ZodBoolean>;
     docCanvasPreferView: z.ZodDefault<z.ZodEnum<["affine:embed-linked-doc", "affine:embed-synced-doc"]>>;
 } & {
     connector: z.ZodDefault<z.ZodObject<{
@@ -1479,6 +1480,7 @@ export declare const GeneralSettingSchema: z.ZodObject<{
         textHorizontalAlign?: import("../../affine-model/index.js").TextAlign | undefined;
         textVerticalAlign?: import("../../affine-model/index.js").TextVerticalAlign | undefined;
     };
+    edgelessShowGrid?: boolean | undefined;
 }, {
     text?: {
         color: string | {
@@ -1512,6 +1514,7 @@ export declare const GeneralSettingSchema: z.ZodObject<{
     } | undefined;
     edgelessScrollZoom?: boolean | undefined;
     edgelessDisableScheduleUpdate?: boolean | undefined;
+    edgelessShowGrid?: boolean | undefined;
     docCanvasPreferView?: "affine:embed-linked-doc" | "affine:embed-synced-doc" | undefined;
     connector?: {
         mode: import("../../affine-model/index.js").ConnectorMode;

package/dist/_pkgs/affine-shared/services/editor-setting-service.js

@@ -5,6 +5,13 @@ export const GeneralSettingSchema = z
     .object({
     edgelessScrollZoom: z.boolean().default(false),
     edgelessDisableScheduleUpdate: z.boolean().default(false),
+    // The host's (or the user's) default for the canvas grid (ADR 0031 §11,
+    // level 3). No default on purpose: absent means the host did not decide,
+    // and the library default — on — applies. A viewer's own toggle and a
+    // document saved "for everyone" both win over it.
+    // A line comment, not JSDoc: see the guard in
+    // `affine/all/src/__tests__/zod-schema-jsdoc.unit.spec.ts`.
+    edgelessShowGrid: z.boolean().optional(),
     docCanvasPreferView: z
         .enum(['affine:embed-linked-doc', 'affine:embed-synced-doc'])
         .default('affine:embed-synced-doc'),

package/dist/_pkgs/affine-shared/services/feature-flag-service.d.ts

@@ -14,6 +14,10 @@ export interface BlockSuiteFlags {
     enable_mobile_keyboard_toolbar: boolean;
     enable_mobile_linked_doc_menu: boolean;
     enable_block_meta: boolean;
+    /**
+     * @deprecated No longer read: the Callout entries follow the `callout` key
+     * of `OPTIONAL_BLOCKS` alone, so `{ callout: false }` is the switch.
+     */
     enable_callout: boolean;
     enable_edgeless_scribbled_style: boolean;
     enable_table_virtual_scroll: boolean;

package/dist/_pkgs/affine-shared/services/index.d.ts

@@ -2,6 +2,8 @@ export * from './artefact-catalogue-service.js';
 export * from './audit-service.js';
 export * from './auto-clear-selection-service.js';
 export * from './block-meta-service.js';
+export * from './canvas-grid.js';
+export * from './canvas-local-visibility.js';
 export * from './citation-service/index.js';
 export * from './command-usage-service.js';
 export * from './comment-service/index.js';
@@ -28,6 +30,7 @@ export * from './parse-url-service.js';
 export * from './pivot-materiality-publisher.js';
 export * from './pivot-properties-service.js';
 export * from './quick-search-service.js';
+export * from './selection-pane-service.js';
 export * from './sidebar-service.js';
 export * from './telemetry-service/index.js';
 export * from './theme-service.js';

package/dist/_pkgs/affine-shared/services/index.js

@@ -2,6 +2,8 @@ export * from './artefact-catalogue-service.js';
 export * from './audit-service.js';
 export * from './auto-clear-selection-service.js';
 export * from './block-meta-service.js';
+export * from './canvas-grid.js';
+export * from './canvas-local-visibility.js';
 export * from './citation-service/index.js';
 export * from './command-usage-service.js';
 export * from './comment-service/index.js';
@@ -28,6 +30,7 @@ export * from './parse-url-service.js';
 export * from './pivot-materiality-publisher.js';
 export * from './pivot-properties-service.js';
 export * from './quick-search-service.js';
+export * from './selection-pane-service.js';
 export * from './sidebar-service.js';
 export * from './telemetry-service/index.js';
 export * from './theme-service.js';

package/dist/_pkgs/affine-shared/services/selection-pane-service.d.ts

@@ -0,0 +1,44 @@
+import type { ExtensionType } from '../../store/index.js';
+/**
+ * The selection pane (ADR 0031 §12): a list of the canvas elements by z-order,
+ * top first, with groups, lock, a filter by frame, and
+ * drag-to-reorder — PowerPoint's pane, on a Labre canvas.
+ *
+ * The seam is shaped exactly like `ArtefactCatalogueService`, and was
+ * challenged against it first: the catalogue's `open(owner)` is scoped to a
+ * framework, and stretching it to a second panel would have changed the
+ * signature of a shipped seam. So one more seam, two verbs, nothing else.
+ *
+ * Everything a pane draws is enumerable from the library without this seam:
+ * the rows from `selectionPaneTree(std)` (ids only, z-order, top first), the
+ * wordings from the element and the translation seam, and every action from
+ * the command registry (`canvas.element.reorder`, `canvas.element.lock`,
+ * `canvas.element.unlock`, `canvas.group.rename`), run through `runCommand`
+ * so the read-only check and the telemetry happen once whoever draws the
+ * pixels.
+ */
+export interface SelectionPaneService {
+    /** Show the pane. */
+    open(): void;
+    /** Put it away. Writes nothing. */
+    close(): void;
+}
+export declare const SelectionPaneProvider: import("../../global/di/types.js").ServiceIdentifier<SelectionPaneService> & (<U extends SelectionPaneService = SelectionPaneService>(variant: import("../../global/di/types.js").ServiceVariant) => import("../../global/di/types.js").ServiceIdentifier<U>);
+/**
+ * Host override seam: replace the library's pane with the host's own — or
+ * switch it off entirely.
+ *
+ * **Replace** — a host with its own sidebar registers this extension; its
+ * implementation answers {@link SelectionPaneProvider}, the edgeless toolbar's
+ * button and the `canvas.selectionPane.toggle` command then call it, and the
+ * library's panel is never asked to open.
+ *
+ * **Disable** — pass `null`. The provider answers nothing: the toolbar button
+ * is not rendered and the toggle command is unavailable, because a control
+ * that opens nothing is a lie. A cold-assembly switch, decided when the editor
+ * is put together (ADR 0031 §13: no flag key for it).
+ *
+ * `di.override`, like `ArtefactCatalogueExtension`, so a host registering
+ * after the library's own default always wins.
+ */
+export declare function SelectionPaneExtension(service: SelectionPaneService | null): ExtensionType;

package/dist/_pkgs/affine-shared/services/selection-pane-service.js

@@ -0,0 +1,28 @@
+import { createIdentifier } from '../../global/di/index.js';
+export const SelectionPaneProvider = createIdentifier('AffineSelectionPane');
+/**
+ * Host override seam: replace the library's pane with the host's own — or
+ * switch it off entirely.
+ *
+ * **Replace** — a host with its own sidebar registers this extension; its
+ * implementation answers {@link SelectionPaneProvider}, the edgeless toolbar's
+ * button and the `canvas.selectionPane.toggle` command then call it, and the
+ * library's panel is never asked to open.
+ *
+ * **Disable** — pass `null`. The provider answers nothing: the toolbar button
+ * is not rendered and the toggle command is unavailable, because a control
+ * that opens nothing is a lie. A cold-assembly switch, decided when the editor
+ * is put together (ADR 0031 §13: no flag key for it).
+ *
+ * `di.override`, like `ArtefactCatalogueExtension`, so a host registering
+ * after the library's own default always wins.
+ */
+export function SelectionPaneExtension(service) {
+    return {
+        setup: di => {
+            // `null` rides through the factory on purpose: `getOptional` then
+            // reports the pane as absent, which is the whole disable story.
+            di.override(SelectionPaneProvider, () => service);
+        },
+    };
+}