@formicoidea/labre-core 0.43.1 → 0.45.0

package/dist/_pkgs/affine-block-surface/extensions/reading.d.ts

@@ -1,4 +1,4 @@
-import { type TagDef } from '../../affine-shared/services/index.js';
+import { type ChromeWording, type TagDef } from '../../affine-shared/services/index.js';
 import { LifeCycleWatcher, type BlockStdScope, type FrameworkId } from '../../std/index.js';
 import type { RoleDefs, RoleId } from '../../std/gfx/index.js';
 import { GfxPrimitiveElementModel } from '../../std/gfx/index.js';
@@ -92,6 +92,14 @@ export interface ReadingRelationSideLabel {
     /** The framework's own English wording, for a host that ships no catalogue. */
     labelFallback: string;
 }
+/**
+ * One wording a framework declares for the frame field of the panel: key plus
+ * its own English, so a host with no catalogue still reads a real phrase.
+ */
+export interface ReadingFrameWording {
+    labelKey: string;
+    labelFallback: string;
+}
 /**
  * The typed edge a reading walks, and the two words the framework reads it
  * with.
@@ -185,13 +193,41 @@ export interface ReadingProfile {
      * reads them in, so the first is the question the artefact answers first.
      */
     alsoRelations?: readonly ReadingRelationDef[];
-    /** The frame the phase is read from. */
+    /**
+     * The frame the subject's ZONE is read from — Wardley's evolution phase, a
+     * Core Domain Chart's quadrant, a BPMN pool's lane.
+     */
     frame?: {
         backgroundRole: RoleId;
         /** The declaration itself, carried as data exactly like `roles` is. */
         background: FrameworkBackgroundDef;
-        /** Which plot axis the zones are laid along. */
-        axis: 'x' | 'y';
+        /**
+         * The plot axis the zones are laid ALONG, for a frame read in one
+         * dimension: Wardley's phases are columns of the evolution axis, so only
+         * the `x` position matters and a component in the top or bottom margin of
+         * the plot still has a phase.
+         *
+         * Absent, the frame is read in TWO dimensions: the subject is in the zone
+         * whose rectangle holds its centre — a quadrant, a lane — and nowhere when
+         * none does. A 2D frame has no transition band.
+         */
+        axis?: 'x' | 'y';
+        /**
+         * The panel's heading for the field — "Evolution phase", "Zone", "Lane".
+         * The framework's own word, like a relation's sides: the panel used to
+         * hard-code Wardley's, which a chart or a pool would have worn too.
+         *
+         * Optional because a 0.43 profile has no such field and a minor release
+         * never breaks a host: absent, the panel reads
+         * {@link READING_FRAME_DEFAULT_WORDING}, which is what 0.43 showed for
+         * every frame (`readingFrameWording`).
+         */
+        label?: ReadingFrameWording;
+        /**
+         * What the field says when the subject sits in no zone of any frame.
+         * Optional for the reason {@link label} is, with the same default.
+         */
+        none?: ReadingFrameWording;
     };
     /**
      * Which properties of the PIVOT RECORD the reading may compare itself
@@ -207,6 +243,21 @@ export interface ReadingProfile {
         phase?: string;
     };
 }
+/** The default frame wording, as the rows the key manifest walks. */
+export declare const READING_FRAME_WORDINGS: readonly ChromeWording[];
+/** The default frame wording, as a profile's `frame.label` / `frame.none`. */
+export declare const READING_FRAME_DEFAULT_WORDING: Readonly<{
+    label: ReadingFrameWording;
+    none: ReadingFrameWording;
+}>;
+/**
+ * The two wordings the panel reads a frame with: the framework's own where it
+ * declares them, {@link READING_FRAME_DEFAULT_WORDING} where it does not.
+ */
+export declare function readingFrameWording(frame: NonNullable<ReadingProfile['frame']>): {
+    label: ReadingFrameWording;
+    none: ReadingFrameWording;
+};
 /** Where the other end of a typed edge sits, relative to the subject. */
 export type ReadingRelationSide = 'consumer' | 'supplier';
 /**
@@ -271,12 +322,24 @@ export interface ReadingRelation {
      */
     contradictsGeometry: boolean;
 }
-/** Where the subject sits along the frame's phase axis. */
+/**
+ * The zone of the frame the subject sits in: a phase along an axis, or a
+ * region of the plane (see `ReadingProfile.frame.axis`).
+ */
 export interface ReadingPhase {
-    /** The declared zone id, e.g. `product`. */
+    /** The zone id, e.g. `product`, or `lane:<id>` for an instance zone. */
     zoneId: string;
+    /** The declared zone's vocabulary, absent on a zone the board never names. */
     labelKey?: string;
     labelFallback?: string;
+    /**
+     * The words the USER wrote for this zone, which is what the board paints in
+     * place of the vocabulary: a renamed zone label stored on the frame (the
+     * declaration's `label.prop`), or a lane's name. Wins over
+     * {@link labelKey} exactly as it does on the canvas (`backgroundLabelText`),
+     * so the panel and the board never name one zone two ways.
+     */
+    name?: string;
     /**
      * The subject sits in the band around a zone transition — Wardley's zone of
      * punctuated equilibrium, declared by the background as
@@ -331,6 +394,19 @@ export interface ElementReading {
     /** `undefined` with no nature, no convention for it, or no name to judge. */
     naming: ReadingNaming | undefined;
 }
+/**
+ * The subject's NAME.
+ *
+ * Its own text first, then — because a framework artefact on this canvas is a
+ * composite — the text of the sibling carrying the profile's label role. That
+ * is the same fact `tags-toolbar.ts` works around from the other direction: one
+ * click selects the group, the role lives on the circle, and the name lives on
+ * a free text beside it.
+ *
+ * Exported for the selection pane, which names its rows the same way (ADR 0031
+ * §12): one rule for "what is this element called", not two.
+ */
+export declare function readName(element: GfxPrimitiveElementModel, profile: Pick<ReadingProfile, 'labelRole' | 'roles'>): string;
 /** What the reading needs to know that is not in the document. */
 export interface ReadingOptions {
     /**

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

@@ -8,7 +8,49 @@ import { effect, signal } from '@preact/signals-core';
 // reading is a one-way read of pure declaration data that must never pull a
 // canvas in.
 import { backgroundPlot, } from '../framework-background/def.js';
-import { backgroundTransitionBands, containingFrame, } from '../framework-background/facts.js';
+import { backgroundPlotRatios, backgroundTransitionBands, backgroundZoneAt, backgroundZones, containingFrame, } from '../framework-background/facts.js';
+/**
+ * The frame wording of a profile that declares none — the heading and the
+ * empty state 0.43 showed for every frame, before a framework could name its
+ * own.
+ *
+ * Owned by the ENGINE rather than by Wardley, whose words they also are,
+ * because a host profile written against 0.43 reads with them too: declared in
+ * a framework bundle, they would vanish from a host that does not install it.
+ * Wardley's profile declares no wording and inherits these.
+ *
+ * Spelled as `[key, English]` rows, the form the key manifest walks and its
+ * drift check pairs with this declaration, then read as a profile's wording.
+ */
+const READING_FRAME_DEFAULT_LABEL = [
+    'com.labre.reading.field.phase',
+    'Evolution phase',
+];
+const READING_FRAME_DEFAULT_NONE = [
+    'com.labre.reading.phase.none',
+    'Not on a framework background — no phase to read.',
+];
+/** The default frame wording, as the rows the key manifest walks. */
+export const READING_FRAME_WORDINGS = [
+    READING_FRAME_DEFAULT_LABEL,
+    READING_FRAME_DEFAULT_NONE,
+];
+const asFrameWording = ([labelKey, labelFallback,]) => ({ labelKey, labelFallback });
+/** The default frame wording, as a profile's `frame.label` / `frame.none`. */
+export const READING_FRAME_DEFAULT_WORDING = {
+    label: asFrameWording(READING_FRAME_DEFAULT_LABEL),
+    none: asFrameWording(READING_FRAME_DEFAULT_NONE),
+};
+/**
+ * The two wordings the panel reads a frame with: the framework's own where it
+ * declares them, {@link READING_FRAME_DEFAULT_WORDING} where it does not.
+ */
+export function readingFrameWording(frame) {
+    return {
+        label: frame.label ?? READING_FRAME_DEFAULT_WORDING.label,
+        none: frame.none ?? READING_FRAME_DEFAULT_WORDING.none,
+    };
+}
 /**
  * Every relation table a profile declares, in reading order.
  *
@@ -102,8 +144,11 @@ function groupMembers(element) {
  * is the same fact `tags-toolbar.ts` works around from the other direction: one
  * click selects the group, the role lives on the circle, and the name lives on
  * a free text beside it.
+ *
+ * Exported for the selection pane, which names its rows the same way (ADR 0031
+ * §12): one rule for "what is this element called", not two.
  */
-function readName(element, profile) {
+export function readName(element, profile) {
     const own = ownText(element);
     if (own)
         return own;
@@ -168,13 +213,37 @@ function frameOf(element, elements, profile) {
         roleIsA(candidate.role, frame.backgroundRole, profile.roles)), candidate => candidate.elementBound);
 }
 /**
- * The phase, read from the position and the frame's DECLARED zones.
+ * How a zone is named, as the BOARD names it: the user's own words first — a
+ * renamed label stored on the frame, a lane's name — then the vocabulary.
  *
- * Two facts, both taken from the declaration and never from a number in this
- * file: which zone the subject's centre falls in, and whether it is inside the
- * band around a transition. The second is the "zone of punctuated equilibrium"
- * — the frontier is a region, not a coordinate — and a component sitting in one
- * is a different statement from a component sitting in a phase.
+ * The same precedence `backgroundLabelText` paints with, minus the translation:
+ * the reading carries the key and the panel resolves it, so the record and the
+ * drift comparison keep working on the vocabulary.
+ */
+function zoneWording(zone, model) {
+    const label = zone.label;
+    const stored = label?.prop !== undefined ? model[label.prop] : undefined;
+    const name = stored !== undefined && stored !== null ? String(stored) : zone.name;
+    return {
+        ...(label?.labelKey !== undefined ? { labelKey: label.labelKey } : {}),
+        ...(label?.fallback !== undefined ? { labelFallback: label.fallback } : {}),
+        ...(name !== undefined ? { name } : {}),
+    };
+}
+/**
+ * The zone, read from the position and the zones the frame INSTANCE has
+ * ({@link backgroundZones}: the framework's in the instance's variant, then the
+ * instance's own).
+ *
+ * Along an axis (Wardley), two facts, both taken from the declaration and never
+ * from a number in this file: which zone the subject's centre falls in, and
+ * whether it is inside the band around a transition. The second is the "zone of
+ * punctuated equilibrium" — the frontier is a region, not a coordinate — and a
+ * component sitting in one is a different statement from a component sitting in
+ * a phase.
+ *
+ * In the plane (no `axis`: a Core Domain Chart, a BPMN pool), the zone whose
+ * rectangle holds the centre, through the helper the audit uses, and no band.
  */
 function readPhase(element, elements, profile) {
     const frame = profile.frame;
@@ -185,11 +254,25 @@ function readPhase(element, elements, profile) {
         return undefined;
     const def = frame.background;
     const bound = background.elementBound;
+    const model = background;
+    const zones = backgroundZones(def, model);
+    const axis = frame.axis;
+    if (axis === undefined) {
+        const at = backgroundPlotRatios(def, bound, element.elementBound);
+        const zone = at === null ? undefined : backgroundZoneAt(zones, at);
+        if (!zone)
+            return undefined;
+        return {
+            zoneId: zone.id,
+            ...zoneWording(zone, model),
+            inTransitionBand: false,
+        };
+    }
     const plot = backgroundPlot(def, bound.w, bound.h);
     const [cx, cy] = centreOf(element.elementBound);
-    const along = frame.axis === 'x' ? cx : cy;
-    const origin = frame.axis === 'x' ? bound.x + plot.x0 : bound.y + plot.y0;
-    const span = frame.axis === 'x' ? plot.width : plot.height;
+    const along = axis === 'x' ? cx : cy;
+    const origin = axis === 'x' ? bound.x + plot.x0 : bound.y + plot.y0;
+    const span = axis === 'x' ? plot.width : plot.height;
     if (!(span > 0))
         return undefined;
     const ratio = (along - origin) / span;
@@ -198,25 +281,20 @@ function readPhase(element, elements, profile) {
     // phase it is visibly not in.
     if (ratio < 0 || ratio > 1)
         return undefined;
-    const zone = (def.zones ?? []).find(({ rect }) => {
-        const start = frame.axis === 'x' ? rect.x : rect.y;
-        const size = frame.axis === 'x' ? rect.w : rect.h;
+    const zone = zones.find(({ rect }) => {
+        const start = axis === 'x' ? rect.x : rect.y;
+        const size = axis === 'x' ? rect.w : rect.h;
         // Half-open, so a component exactly on a divider reads as the phase it is
         // entering — the same side the band below reports as the frontier.
         return ratio >= start && (ratio < start + size || start + size >= 1);
     });
     if (!zone)
         return undefined;
-    const bands = backgroundTransitionBands(def, bound)[frame.axis];
+    const bands = backgroundTransitionBands(def, bound)[axis];
     const band = bands.find(({ min, max }) => along >= min && along <= max);
     return {
         zoneId: zone.id,
-        ...(zone.label?.labelKey !== undefined
-            ? { labelKey: zone.label.labelKey }
-            : {}),
-        ...(zone.label?.fallback !== undefined
-            ? { labelFallback: zone.label.fallback }
-            : {}),
+        ...zoneWording(zone, model),
         inTransitionBand: band !== undefined,
         ...(band !== undefined ? { bandId: band.id } : {}),
     };

package/dist/_pkgs/affine-block-surface/extensions/selection-pane/actions.d.ts

@@ -0,0 +1,80 @@
+import type { BlockStdScope } from '../../../std/index.js';
+import type { SelectionPaneNode } from './tree.js';
+/**
+ * Move `id` so it sits directly ABOVE `above` in the stack — `null` puts it at
+ * the bottom of its stack. Answers whether anything was written.
+ *
+ * The drop target of a drag in a top-first list: dropping a row just over row
+ * X means "directly above X". The new `index` is a key between the two
+ * neighbours (the same `fractional-indexing` keys `LayerManager` generates), so
+ * one field of one model is written and nothing else moves.
+ *
+ * Refused, with nothing written: a read-only document; a mindmap node (it has
+ * no index of its own — the whole mindmap moves as one, as the toolbar's
+ * reorder already says); an `above` that is not stacked with `id`; and a
+ * target that is where the model already is.
+ */
+export declare function reorderPaneElement(std: BlockStdScope, id: string, above: string | null): boolean;
+/**
+ * Lock or unlock each model ON ITS OWN. Answers whether anything was written.
+ *
+ * Deliberately not the contextual toolbar's lock: that one, given several
+ * elements, wraps them into a new group and locks the group — a structural
+ * edit a row's padlock must never make. Here each row keeps its place in the
+ * tree; only `lockedBySelf` changes, and only where it differs.
+ */
+export declare function setPaneElementsLocked(std: BlockStdScope, ids: readonly string[], locked: boolean): boolean;
+/**
+ * Hide models for EVERYONE, or show them again (ADR 0031 §7). Answers how
+ * many models were written.
+ *
+ * Writes the stored `hiddenForEveryone` — never `hidden`, which mindmap
+ * collapse owns. Hiding writes `true`; showing REMOVES the key (`clearField`
+ * on an element, the props proxy's delete on a block), never stores `false`,
+ * so an unhidden document is byte-identical to one never hidden. Models
+ * already in the asked state are skipped, so a gesture that changes nothing
+ * writes nothing and pushes no undo step; the rest go in one transaction
+ * after one `captureSync()`.
+ */
+export declare function setPaneElementsHiddenForEveryone(std: BlockStdScope, ids: readonly string[], hidden: boolean): number;
+/**
+ * Rename a group through its existing stored `title`. Answers whether
+ * anything was written. An empty or unchanged title writes nothing.
+ */
+export declare function renamePaneGroup(std: BlockStdScope, id: string, title: string): boolean;
+/**
+ * Rename a frame through its existing stored `title`, edited in place — the
+ * `Text` the frame's own title editor binds to, never a replaced one, so an
+ * open title editor keeps its binding. Answers whether anything was written.
+ * An empty or unchanged title writes nothing.
+ */
+export declare function renamePaneFrame(std: BlockStdScope, id: string, title: string): boolean;
+/** Something the pane can be filtered by: a frame, and only a frame. */
+export interface SelectionPaneFilterTarget {
+    id: string;
+    /**
+     * Always `'frame'`. A framework board was offered too until the product
+     * owner's review narrowed the filter to frames (ADR 0031, amendments); the
+     * field stays so a host reading it has nothing to change.
+     */
+    kind: 'frame';
+}
+/** The frames on the canvas, top first — what the pane's filter offers. */
+export declare function selectionPaneFilterTargets(std: BlockStdScope): SelectionPaneFilterTarget[];
+/**
+ * The ids a frame filter keeps: the frame itself — a row like any other, so
+ * the list keeps showing what it is filtered by (ADR 0031, amendments) — its
+ * `childElementIds` and their descendants. `null` for an id that is not a
+ * frame.
+ */
+export declare function selectionPaneFilterMembers(std: BlockStdScope, targetId: string): Set<string> | null;
+/**
+ * The tree narrowed to `members`: a row is kept when it is a member or holds
+ * one, so a group reaching into a frame stays as the path to its member.
+ *
+ * A LAYER row is always kept, its children narrowed (ADR 0031, amendments): a
+ * layer is where new elements land and where a drop goes, not something a
+ * frame holds, and a layer created under a filter that hid it read as a
+ * "New layer" button doing nothing.
+ */
+export declare function filterSelectionPaneTree(nodes: readonly SelectionPaneNode[], members: ReadonlySet<string>): SelectionPaneNode[];

package/dist/_pkgs/affine-block-surface/extensions/selection-pane/actions.js

@@ -0,0 +1,248 @@
+import { FrameBlockModel, GroupElementModel, MindmapElementModel, } from '../../../affine-model/index.js';
+import { compareLayer, GfxBlockElementModel, GfxControllerIdentifier, GfxPrimitiveElementModel, isStoredHiddenForEveryone, } from '../../../std/gfx/index.js';
+import { generateKeyBetween } from 'fractional-indexing';
+import * as Y from 'yjs';
+/**
+ * The selection pane's writes (ADR 0031, stage 2). Every one of them:
+ *
+ * - refuses on a read-only document before reading anything else;
+ * - writes nothing when nothing would change — an unchanged write is an empty
+ *   undo step, and an undo that "does nothing" reads as a broken undo;
+ * - takes ONE `captureSync()` first, so one gesture in the pane is one undo
+ *   step, whatever it touched;
+ * - writes through `gfx.updateElement`, which is `surface.updateElement` for an
+ *   element and `store.updateBlock` for a block — never a `Y.Map` directly.
+ *
+ * They are reached through the `canvas.element.*` / `canvas.group.rename`
+ * commands, so a host's own pane gets the same guards by calling `runCommand`.
+ */
+function gfxModel(std, id) {
+    const model = std.get(GfxControllerIdentifier).getElementById(id);
+    return model instanceof GfxPrimitiveElementModel ||
+        model instanceof GfxBlockElementModel
+        ? model
+        : null;
+}
+/**
+ * The models a reorder compares against: those sharing the moved model's RAW
+ * `group` — a group, a mindmap, a frame, or none.
+ *
+ * Raw and not the pane's container on purpose: an `index` only orders a model
+ * among the models its group-like ancestor stacks together (`compare` puts a
+ * frame's members right above the frame), so a key computed against a wider
+ * list could be written and still not move the row.
+ */
+function stackSiblings(std, model) {
+    const group = model.group;
+    const gfx = std.get(GfxControllerIdentifier);
+    // With user layers a model is restacked within its layer (ADR 0031 §4):
+    // a key computed against another layer's neighbours would not move it.
+    const userLayers = gfx.surface?.userLayers;
+    const layer = userLayers?.ranks ? userLayers.effectiveLayerOf(model) : null;
+    return gfx.gfxElements
+        .filter(other => other.group === group &&
+        (layer === null || userLayers.effectiveLayerOf(other) === layer))
+        .sort(compareLayer);
+}
+/**
+ * Move `id` so it sits directly ABOVE `above` in the stack — `null` puts it at
+ * the bottom of its stack. Answers whether anything was written.
+ *
+ * The drop target of a drag in a top-first list: dropping a row just over row
+ * X means "directly above X". The new `index` is a key between the two
+ * neighbours (the same `fractional-indexing` keys `LayerManager` generates), so
+ * one field of one model is written and nothing else moves.
+ *
+ * Refused, with nothing written: a read-only document; a mindmap node (it has
+ * no index of its own — the whole mindmap moves as one, as the toolbar's
+ * reorder already says); an `above` that is not stacked with `id`; and a
+ * target that is where the model already is.
+ */
+export function reorderPaneElement(std, id, above) {
+    if (std.store.readonly)
+        return false;
+    const model = gfxModel(std, id);
+    if (!model || id === above)
+        return false;
+    if (model.group instanceof MindmapElementModel)
+        return false;
+    const siblings = stackSiblings(std, model);
+    const others = siblings.filter(other => other !== model);
+    let position = 0;
+    if (above !== null) {
+        const target = others.findIndex(other => other.id === above);
+        if (target === -1)
+            return false;
+        position = target + 1;
+    }
+    // Already there: the model's current lower neighbour is the target.
+    const current = siblings.indexOf(model);
+    const lowerNow = current > 0 ? siblings[current - 1] : null;
+    if ((lowerNow?.id ?? null) === above)
+        return false;
+    const lower = others[position - 1]?.index ?? null;
+    const upper = others[position]?.index ?? null;
+    // Two equal keys cannot be split. `generateIndex` never produces them, so
+    // this only guards a hand-made document; refusing beats throwing in a drop.
+    if (lower !== null && upper !== null && lower >= upper)
+        return false;
+    const index = generateKeyBetween(lower, upper);
+    std.store.captureSync();
+    std.get(GfxControllerIdentifier).updateElement(model, { index });
+    return true;
+}
+/**
+ * Lock or unlock each model ON ITS OWN. Answers whether anything was written.
+ *
+ * Deliberately not the contextual toolbar's lock: that one, given several
+ * elements, wraps them into a new group and locks the group — a structural
+ * edit a row's padlock must never make. Here each row keeps its place in the
+ * tree; only `lockedBySelf` changes, and only where it differs.
+ */
+export function setPaneElementsLocked(std, ids, locked) {
+    if (std.store.readonly)
+        return false;
+    const targets = ids
+        .map(id => gfxModel(std, id))
+        .filter((model) => model !== null && (model.lockedBySelf === true) !== locked);
+    if (!targets.length)
+        return false;
+    const gfx = std.get(GfxControllerIdentifier);
+    std.store.captureSync();
+    std.store.transact(() => {
+        for (const model of targets) {
+            gfx.updateElement(model, { lockedBySelf: locked });
+        }
+    });
+    return true;
+}
+/**
+ * Hide models for EVERYONE, or show them again (ADR 0031 §7). Answers how
+ * many models were written.
+ *
+ * Writes the stored `hiddenForEveryone` — never `hidden`, which mindmap
+ * collapse owns. Hiding writes `true`; showing REMOVES the key (`clearField`
+ * on an element, the props proxy's delete on a block), never stores `false`,
+ * so an unhidden document is byte-identical to one never hidden. Models
+ * already in the asked state are skipped, so a gesture that changes nothing
+ * writes nothing and pushes no undo step; the rest go in one transaction
+ * after one `captureSync()`.
+ */
+export function setPaneElementsHiddenForEveryone(std, ids, hidden) {
+    if (std.store.readonly)
+        return 0;
+    const targets = ids
+        .map(id => gfxModel(std, id))
+        .filter((model) => model !== null && isStoredHiddenForEveryone(model) !== hidden);
+    if (!targets.length)
+        return 0;
+    const gfx = std.get(GfxControllerIdentifier);
+    std.store.captureSync();
+    std.store.transact(() => {
+        for (const model of targets) {
+            if (hidden) {
+                gfx.updateElement(model, { hiddenForEveryone: true });
+            }
+            else if (model instanceof GfxPrimitiveElementModel) {
+                model.clearField('hiddenForEveryone');
+            }
+            else {
+                // The props proxy deletes the `prop:` key (ADR 0031 §7).
+                delete model.props.hiddenForEveryone;
+            }
+        }
+    });
+    return targets.length;
+}
+/**
+ * Rename a group through its existing stored `title`. Answers whether
+ * anything was written. An empty or unchanged title writes nothing.
+ */
+export function renamePaneGroup(std, id, title) {
+    if (std.store.readonly)
+        return false;
+    const model = gfxModel(std, id);
+    if (!(model instanceof GroupElementModel))
+        return false;
+    const next = title.trim();
+    if (!next || next === model.title.toString())
+        return false;
+    std.store.captureSync();
+    std
+        .get(GfxControllerIdentifier)
+        .updateElement(model, { title: new Y.Text(next) });
+    return true;
+}
+/**
+ * Rename a frame through its existing stored `title`, edited in place — the
+ * `Text` the frame's own title editor binds to, never a replaced one, so an
+ * open title editor keeps its binding. Answers whether anything was written.
+ * An empty or unchanged title writes nothing.
+ */
+export function renamePaneFrame(std, id, title) {
+    if (std.store.readonly)
+        return false;
+    const model = gfxModel(std, id);
+    if (!(model instanceof FrameBlockModel))
+        return false;
+    const next = title.trim();
+    const text = model.props.title;
+    if (!next || next === text.toString())
+        return false;
+    std.store.captureSync();
+    text.replace(0, text.length, next);
+    return true;
+}
+/** The frames on the canvas, top first — what the pane's filter offers. */
+export function selectionPaneFilterTargets(std) {
+    return std
+        .get(GfxControllerIdentifier)
+        .gfxElements.filter(model => model instanceof FrameBlockModel)
+        .sort((a, b) => compareLayer(b, a))
+        .map(model => ({ id: model.id, kind: 'frame' }));
+}
+/**
+ * The ids a frame filter keeps: the frame itself — a row like any other, so
+ * the list keeps showing what it is filtered by (ADR 0031, amendments) — its
+ * `childElementIds` and their descendants. `null` for an id that is not a
+ * frame.
+ */
+export function selectionPaneFilterMembers(std, targetId) {
+    const target = std.get(GfxControllerIdentifier).getElementById(targetId);
+    if (!(target instanceof FrameBlockModel))
+        return null;
+    const ids = new Set([target.id]);
+    for (const child of target.childElements) {
+        ids.add(child.id);
+        if ('descendantElements' in child) {
+            for (const descendant of child
+                .descendantElements) {
+                ids.add(descendant.id);
+            }
+        }
+    }
+    return ids;
+}
+/**
+ * The tree narrowed to `members`: a row is kept when it is a member or holds
+ * one, so a group reaching into a frame stays as the path to its member.
+ *
+ * A LAYER row is always kept, its children narrowed (ADR 0031, amendments): a
+ * layer is where new elements land and where a drop goes, not something a
+ * frame holds, and a layer created under a filter that hid it read as a
+ * "New layer" button doing nothing.
+ */
+export function filterSelectionPaneTree(nodes, members) {
+    const kept = [];
+    for (const node of nodes) {
+        const children = node.children
+            ? filterSelectionPaneTree(node.children, members)
+            : undefined;
+        if (node.kind === 'layer' ||
+            members.has(node.id) ||
+            (children && children.length)) {
+            kept.push(children ? { ...node, children } : node);
+        }
+    }
+    return kept;
+}