@formicoidea/labre-core 0.43.1 → 0.46.0

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

@@ -0,0 +1,76 @@
+import type { BlockStdScope } from '../../../std/index.js';
+import { type GfxModel, type SurfaceBlockModel, type SurfaceLayerRecord } from '../../../std/gfx/index.js';
+/** The layer records, bottom first. Empty while the surface has none. */
+export declare function userLayersBottomUp(surface: SurfaceBlockModel | null): {
+    id: string;
+    record: SurfaceLayerRecord;
+}[];
+/**
+ * The name a layer row shows: its record's, or — for the default layer while
+ * it has no record — the name the first-layer creation would write ("Layer
+ * 1", ADR 0031 amendments). `null` for an id that is no layer.
+ *
+ * Reading it writes nothing: the default layer is shown from the start and
+ * recorded only by a gesture that needs the record.
+ */
+export declare function userLayerName(std: BlockStdScope, id: string): string | null;
+/**
+ * Create a user layer on top of the others and make it this viewer's active
+ * layer. Answers its id, or `null` when nothing was written.
+ *
+ * The FIRST creation writes two records in one transaction: `'@default'`,
+ * named through the seam ("Layer 1"), and the new one above it. That one
+ * write sets the whole `layers` prop, so two peers doing it at the same
+ * moment keep one record set (ADR 0031 open point 6, accepted for v1): the
+ * other peer's members fall back to the default layer, nothing is dropped.
+ */
+export declare function createUserLayer(std: BlockStdScope, name?: string): string | null;
+/**
+ * Rename a layer: one field of one record. Empty or unchanged writes nothing.
+ *
+ * The default layer with no record yet is renamed by recording it, named
+ * (ADR 0031 amendments): "unchanged" is then against the seed name it shows.
+ */
+export declare function renameUserLayer(std: BlockStdScope, id: string, name: string): boolean;
+/**
+ * Move a layer so it sits directly ABOVE `above` — `null` puts it at the
+ * bottom. One field (`index`) of one record; a reorder racing a peer's
+ * rename of the same layer merges.
+ */
+export declare function reorderUserLayer(std: BlockStdScope, id: string, above: string | null): boolean;
+/**
+ * Hide whole layers for EVERYONE, or show them again (ADR 0031 §7, stage
+ * 7): `hidden: true` on each record — one write per layer, never one per
+ * member — and the key REMOVED on show, never `false`. Answers how many
+ * records were written.
+ *
+ * Hiding the default layer while it has no record records it, hidden, with
+ * its seed name (ADR 0031 amendments); showing it has nothing to write.
+ */
+export declare function setUserLayersHiddenForEveryone(std: BlockStdScope, ids: readonly string[], hidden: boolean): number;
+/**
+ * Delete a user layer WITH its members, in one undo step (ADR 0031 §10).
+ * Answers how many models went with it, or `null` when nothing was written.
+ *
+ * The read-only refusal comes first, then one `captureSync()`, then one
+ * transaction: every top-level model whose effective layer is this one (a
+ * group or a mindmap takes its descendants with it), then the record. A
+ * connector of ANOTHER layer whose ends were here stays, loose, as when its
+ * ends are deleted any other way — the members are removed one by one, not
+ * through the "delete with connectors" path of the toolbar. A frame of this
+ * layer goes; what it holds from other layers stays. `'@default'` cannot be
+ * deleted.
+ */
+export declare function deleteUserLayer(std: BlockStdScope, id: string): number | null;
+/**
+ * Write `layer` on one model — set it, or REMOVE the key for the default
+ * layer (never the string `'@default'`). Inside the caller's transaction.
+ */
+export declare function writeModelLayer(std: BlockStdScope, model: GfxModel, layer: string): void;
+/**
+ * Move models to the layer `layerId`. Answers how many models were written —
+ * a grouped model moves its outermost group, so that may be fewer than asked.
+ * An unknown layer id writes nothing. The default layer always exists, record
+ * or not: moving there removes the `layer` key, a dangling id included.
+ */
+export declare function moveModelsToUserLayer(std: BlockStdScope, ids: readonly string[], layerId: string): number;

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

@@ -0,0 +1,299 @@
+import { translateKey } from '../../../affine-shared/services/index.js';
+import { DEFAULT_LAYER_ID, GfxBlockElementModel, GfxControllerIdentifier, GfxPrimitiveElementModel, layerCarrierOf, ownLayerOf, } from '../../../std/gfx/index.js';
+import { nanoid } from '../../../store/index.js';
+import { generateKeyBetween } from 'fractional-indexing';
+import { CanvasActiveLayer } from './active-layer.js';
+import { LAYER_SEED_NAME } from './translations.js';
+/**
+ * The user layers' writes (ADR 0031 §2, §5, stage 6). Every one of them:
+ *
+ * - refuses on a read-only document before reading anything else;
+ * - writes nothing when nothing would change;
+ * - takes ONE `captureSync()` first, so one gesture is one undo step;
+ * - writes ONE record, or ONE field of a record — never the whole `layers`
+ *   prop, except the very first creation, which has no record to write into.
+ *   That is what lets two peers' edits of two layers merge key by key.
+ *
+ * Reached through the `canvas.layer.*` commands, so a host's own pane gets
+ * the same guards by calling `runCommand`.
+ */
+function surfaceOf(std) {
+    return std.get(GfxControllerIdentifier).surface;
+}
+/** The layer records, bottom first. Empty while the surface has none. */
+export function userLayersBottomUp(surface) {
+    const layers = surface?.props.layers;
+    if (!layers)
+        return [];
+    return Object.entries(layers)
+        .filter(([, record]) => record && typeof record.index === 'string')
+        .map(([id, record]) => ({ id, record }))
+        .sort((a, b) => a.record.index === b.record.index
+        ? a.id < b.id
+            ? -1
+            : 1
+        : a.record.index < b.record.index
+            ? -1
+            : 1);
+}
+/** The seed a new layer is named with, resolved through the seam. */
+function seedName(std, n) {
+    return translateKey(std, ...LAYER_SEED_NAME, { n });
+}
+/**
+ * The name a layer row shows: its record's, or — for the default layer while
+ * it has no record — the name the first-layer creation would write ("Layer
+ * 1", ADR 0031 amendments). `null` for an id that is no layer.
+ *
+ * Reading it writes nothing: the default layer is shown from the start and
+ * recorded only by a gesture that needs the record.
+ */
+export function userLayerName(std, id) {
+    const record = surfaceOf(std)?.props.layers?.[id];
+    if (record)
+        return record.name;
+    return id === DEFAULT_LAYER_ID ? seedName(std, 1) : null;
+}
+/**
+ * Record the default layer, inside the caller's transaction: the whole
+ * `layers` prop while it is absent — as the first creation does — else the
+ * one `'@default'` key, below every other layer. The seed name unless the
+ * gesture says otherwise.
+ */
+function recordDefaultLayer(std, surface, fields = {}) {
+    const bottom = userLayersBottomUp(surface)[0]?.record.index ?? null;
+    const record = {
+        name: seedName(std, 1),
+        index: generateKeyBetween(null, bottom),
+        ...fields,
+    };
+    if (!surface.props.layers) {
+        surface.props.layers = { [DEFAULT_LAYER_ID]: record };
+    }
+    else {
+        surface.props.layers[DEFAULT_LAYER_ID] = record;
+    }
+}
+/**
+ * Create a user layer on top of the others and make it this viewer's active
+ * layer. Answers its id, or `null` when nothing was written.
+ *
+ * The FIRST creation writes two records in one transaction: `'@default'`,
+ * named through the seam ("Layer 1"), and the new one above it. That one
+ * write sets the whole `layers` prop, so two peers doing it at the same
+ * moment keep one record set (ADR 0031 open point 6, accepted for v1): the
+ * other peer's members fall back to the default layer, nothing is dropped.
+ */
+export function createUserLayer(std, name) {
+    if (std.store.readonly)
+        return null;
+    const surface = surfaceOf(std);
+    if (!surface)
+        return null;
+    const existing = userLayersBottomUp(surface);
+    const id = nanoid();
+    const seed = (n) => seedName(std, n);
+    std.store.captureSync();
+    std.store.transact(() => {
+        if (!existing.length) {
+            const bottom = generateKeyBetween(null, null);
+            surface.props.layers = {
+                [DEFAULT_LAYER_ID]: { name: seed(1), index: bottom },
+                [id]: {
+                    name: name?.trim() || seed(2),
+                    index: generateKeyBetween(bottom, null),
+                },
+            };
+            return;
+        }
+        const top = existing[existing.length - 1].record.index;
+        surface.props.layers[id] = {
+            name: name?.trim() || seed(existing.length + 1),
+            index: generateKeyBetween(top, null),
+        };
+    });
+    std.getOptional(CanvasActiveLayer)?.choose(id);
+    return id;
+}
+/**
+ * Rename a layer: one field of one record. Empty or unchanged writes nothing.
+ *
+ * The default layer with no record yet is renamed by recording it, named
+ * (ADR 0031 amendments): "unchanged" is then against the seed name it shows.
+ */
+export function renameUserLayer(std, id, name) {
+    if (std.store.readonly)
+        return false;
+    const surface = surfaceOf(std);
+    const record = surface?.props.layers?.[id];
+    const shown = userLayerName(std, id);
+    const next = name.trim();
+    if (!surface || shown === null || !next || next === shown)
+        return false;
+    std.store.captureSync();
+    // Inside the store's transaction, not the props proxy's own: the proxy
+    // writes with its own origin, which the undo manager does not track.
+    std.store.transact(() => {
+        if (record)
+            record.name = next;
+        else
+            recordDefaultLayer(std, surface, { name: next });
+    });
+    return true;
+}
+/**
+ * Move a layer so it sits directly ABOVE `above` — `null` puts it at the
+ * bottom. One field (`index`) of one record; a reorder racing a peer's
+ * rename of the same layer merges.
+ */
+export function reorderUserLayer(std, id, above) {
+    if (std.store.readonly || id === above)
+        return false;
+    const layers = userLayersBottomUp(surfaceOf(std));
+    const moving = layers.find(layer => layer.id === id);
+    if (!moving)
+        return false;
+    const others = layers.filter(layer => layer.id !== id);
+    let position = 0;
+    if (above !== null) {
+        const target = others.findIndex(layer => layer.id === above);
+        if (target === -1)
+            return false;
+        position = target + 1;
+    }
+    const current = layers.indexOf(moving);
+    if ((layers[current - 1]?.id ?? null) === above)
+        return false;
+    const lower = others[position - 1]?.record.index ?? null;
+    const upper = others[position]?.record.index ?? null;
+    if (lower !== null && upper !== null && lower >= upper)
+        return false;
+    std.store.captureSync();
+    std.store.transact(() => {
+        moving.record.index = generateKeyBetween(lower, upper);
+    });
+    return true;
+}
+/**
+ * Hide whole layers for EVERYONE, or show them again (ADR 0031 §7, stage
+ * 7): `hidden: true` on each record — one write per layer, never one per
+ * member — and the key REMOVED on show, never `false`. Answers how many
+ * records were written.
+ *
+ * Hiding the default layer while it has no record records it, hidden, with
+ * its seed name (ADR 0031 amendments); showing it has nothing to write.
+ */
+export function setUserLayersHiddenForEveryone(std, ids, hidden) {
+    if (std.store.readonly)
+        return 0;
+    const surface = surfaceOf(std);
+    if (!surface)
+        return 0;
+    const layers = surface.props.layers;
+    const targets = ids
+        .map(id => layers?.[id])
+        .filter((record) => !!record && (record.hidden === true) !== hidden);
+    const recordDefault = hidden && ids.includes(DEFAULT_LAYER_ID) && !layers?.[DEFAULT_LAYER_ID];
+    if (!targets.length && !recordDefault)
+        return 0;
+    std.store.captureSync();
+    std.store.transact(() => {
+        for (const record of targets) {
+            if (hidden) {
+                record.hidden = true;
+            }
+            else {
+                delete record.hidden;
+            }
+        }
+        if (recordDefault)
+            recordDefaultLayer(std, surface, { hidden: true });
+    });
+    return targets.length + (recordDefault ? 1 : 0);
+}
+/**
+ * Delete a user layer WITH its members, in one undo step (ADR 0031 §10).
+ * Answers how many models went with it, or `null` when nothing was written.
+ *
+ * The read-only refusal comes first, then one `captureSync()`, then one
+ * transaction: every top-level model whose effective layer is this one (a
+ * group or a mindmap takes its descendants with it), then the record. A
+ * connector of ANOTHER layer whose ends were here stays, loose, as when its
+ * ends are deleted any other way — the members are removed one by one, not
+ * through the "delete with connectors" path of the toolbar. A frame of this
+ * layer goes; what it holds from other layers stays. `'@default'` cannot be
+ * deleted.
+ */
+export function deleteUserLayer(std, id) {
+    if (std.store.readonly)
+        return null;
+    if (id === DEFAULT_LAYER_ID)
+        return null;
+    const surface = surfaceOf(std);
+    const layers = surface?.props.layers;
+    if (!surface || !layers?.[id])
+        return null;
+    const gfx = std.get(GfxControllerIdentifier);
+    const members = gfx.gfxElements.filter(model => surface.userLayers.effectiveLayerOf(model) === id);
+    const carriers = members.filter(model => layerCarrierOf(model) === model);
+    std.store.captureSync();
+    std.store.transact(() => {
+        for (const model of carriers) {
+            if (gfx.getElementById(model.id))
+                gfx.deleteElement(model);
+        }
+        delete layers[id];
+    });
+    std.store.captureSync();
+    return members.length;
+}
+/**
+ * Write `layer` on one model — set it, or REMOVE the key for the default
+ * layer (never the string `'@default'`). Inside the caller's transaction.
+ */
+export function writeModelLayer(std, model, layer) {
+    if (layer === DEFAULT_LAYER_ID) {
+        if (model instanceof GfxPrimitiveElementModel) {
+            model.clearField('layer');
+        }
+        else if (model instanceof GfxBlockElementModel) {
+            delete model.props.layer;
+        }
+        return;
+    }
+    std.get(GfxControllerIdentifier).updateElement(model, { layer });
+}
+/**
+ * Move models to the layer `layerId`. Answers how many models were written —
+ * a grouped model moves its outermost group, so that may be fewer than asked.
+ * An unknown layer id writes nothing. The default layer always exists, record
+ * or not: moving there removes the `layer` key, a dangling id included.
+ */
+export function moveModelsToUserLayer(std, ids, layerId) {
+    if (std.store.readonly)
+        return 0;
+    const surface = surfaceOf(std);
+    if (!surface)
+        return 0;
+    if (layerId !== DEFAULT_LAYER_ID && !surface.props.layers?.[layerId]) {
+        return 0;
+    }
+    const gfx = std.get(GfxControllerIdentifier);
+    const carriers = new Set();
+    for (const id of ids) {
+        const model = gfx.getElementById(id);
+        if (model instanceof GfxPrimitiveElementModel ||
+            model instanceof GfxBlockElementModel) {
+            carriers.add(layerCarrierOf(model));
+        }
+    }
+    const targets = [...carriers].filter(model => (ownLayerOf(model) ?? DEFAULT_LAYER_ID) !== layerId);
+    if (!targets.length)
+        return 0;
+    std.store.captureSync();
+    std.store.transact(() => {
+        for (const model of targets)
+            writeModelLayer(std, model, layerId);
+    });
+    return targets.length;
+}

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

@@ -0,0 +1,20 @@
+import { LifeCycleWatcher } from '../../../std/index.js';
+/**
+ * The layer new elements land in, for THIS viewer (ADR 0031 §6): the one
+ * selected in the selection pane, or the default layer.
+ *
+ * Per viewer and per session — never stored, in the document or anywhere
+ * else: a reload starts on the default layer. A layer deleted or never
+ * created on this surface resolves to the default layer, so a stale choice
+ * cannot send new elements to a dangling id.
+ */
+export declare class CanvasActiveLayer extends LifeCycleWatcher {
+    static key: string;
+    /** The chosen layer id, as chosen; read {@link resolve} for the effective one. */
+    readonly chosen$: import("@preact/signals-core").Signal<string>;
+    private get _surface();
+    /** The layer a new element lands in: the chosen one if it still exists. */
+    resolve(): string;
+    /** Make `id` the active layer for this viewer. */
+    choose(id: string): void;
+}

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

@@ -0,0 +1,34 @@
+import { LifeCycleWatcher } from '../../../std/index.js';
+import { DEFAULT_LAYER_ID, GfxControllerIdentifier, } from '../../../std/gfx/index.js';
+import { signal } from '@preact/signals-core';
+/**
+ * The layer new elements land in, for THIS viewer (ADR 0031 §6): the one
+ * selected in the selection pane, or the default layer.
+ *
+ * Per viewer and per session — never stored, in the document or anywhere
+ * else: a reload starts on the default layer. A layer deleted or never
+ * created on this surface resolves to the default layer, so a stale choice
+ * cannot send new elements to a dangling id.
+ */
+export class CanvasActiveLayer extends LifeCycleWatcher {
+    constructor() {
+        super(...arguments);
+        /** The chosen layer id, as chosen; read {@link resolve} for the effective one. */
+        this.chosen$ = signal(DEFAULT_LAYER_ID);
+    }
+    static { this.key = 'canvas-active-layer'; }
+    get _surface() {
+        return this.std.get(GfxControllerIdentifier).surface;
+    }
+    /** The layer a new element lands in: the chosen one if it still exists. */
+    resolve() {
+        const chosen = this.chosen$.value;
+        if (chosen === DEFAULT_LAYER_ID)
+            return DEFAULT_LAYER_ID;
+        return this._surface?.props.layers?.[chosen] ? chosen : DEFAULT_LAYER_ID;
+    }
+    /** Make `id` the active layer for this viewer. */
+    choose(id) {
+        this.chosen$.value = id;
+    }
+}

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

@@ -0,0 +1,67 @@
+import type { AnyCommandDescriptor, BlockStdScope } from '../../../std/index.js';
+import { z } from 'zod';
+/**
+ * The user layers' commands (ADR 0031 §12), `owner: 'core'`, on the palette
+ * and the agent. The library's pane runs them through `runCommand`, and so
+ * does a host's: the read-only refusal and the undo step live in the
+ * actions, once.
+ *
+ * Each self-emits `CanvasLayerChanged` (see the telemetry README) when it
+ * wrote something — ids and counts only, never a layer name.
+ */
+export type CanvasLayerAction = 'create' | 'rename' | 'reorder' | 'delete' | 'move-elements';
+export declare function reportLayerChange(std: BlockStdScope, action: CanvasLayerAction, memberCount?: number): void;
+export declare const createLayerParams: z.ZodObject<{
+    /** Omitted: the seeded name, "Layer n". */
+    name: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    name?: string | undefined;
+}, {
+    name?: string | undefined;
+}>;
+export type CreateLayerParams = z.infer<typeof createLayerParams>;
+export declare const renameLayerParams: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    name: string;
+    id: string;
+}, {
+    name: string;
+    id: string;
+}>;
+export type RenameLayerParams = z.infer<typeof renameLayerParams>;
+export declare const reorderLayerParams: z.ZodObject<{
+    id: z.ZodString;
+    /** The layer it lands directly ABOVE; `null` puts it at the bottom. */
+    above: z.ZodNullable<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    id: string;
+    above: string | null;
+}, {
+    id: string;
+    above: string | null;
+}>;
+export type ReorderLayerParams = z.infer<typeof reorderLayerParams>;
+export declare const moveElementsToLayerParams: z.ZodObject<{
+    /** Omitted: the current canvas selection. */
+    ids: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    layerId: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    layerId: string;
+    ids?: string[] | undefined;
+}, {
+    layerId: string;
+    ids?: string[] | undefined;
+}>;
+export type MoveElementsToLayerParams = z.infer<typeof moveElementsToLayerParams>;
+export declare const deleteLayerParams: z.ZodObject<{
+    /** The layer to delete; `'@default'` is refused. */
+    id: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    id: string;
+}, {
+    id: string;
+}>;
+export type DeleteLayerParams = z.infer<typeof deleteLayerParams>;
+export declare const userLayerCommands: AnyCommandDescriptor[];

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

@@ -0,0 +1,172 @@
+import { TelemetryProvider } from '../../../affine-shared/services/index.js';
+import { DEFAULT_LAYER_ID, GfxControllerIdentifier } from '../../../std/gfx/index.js';
+import { z } from 'zod';
+import { createUserLayer, deleteUserLayer, moveModelsToUserLayer, renameUserLayer, reorderUserLayer, userLayersBottomUp, } from './actions.js';
+export function reportLayerChange(std, action, memberCount) {
+    const layerCount = userLayersBottomUp(std.get(GfxControllerIdentifier).surface).length;
+    std.getOptional(TelemetryProvider)?.track('CanvasLayerChanged', {
+        page: 'whiteboard editor',
+        action,
+        layerCount,
+        ...(memberCount === undefined ? {} : { memberCount }),
+    });
+}
+export const createLayerParams = z.object({
+    /** Omitted: the seeded name, "Layer n". */
+    name: z.string().optional(),
+});
+const createLayer = {
+    id: 'canvas.layer.create',
+    owner: 'core',
+    kind: 'action',
+    labelKey: 'com.labre.command.canvas.layer.create',
+    labelFallback: 'New layer',
+    descriptionKey: 'com.labre.command.canvas.layer.create.description',
+    descriptionFallback: 'Add a layer on top of the others. New elements go into it until you choose another.',
+    keywords: ['layer', 'calque'],
+    surfaces: ['palette', 'agent'],
+    scope: 'edgeless',
+    defaultKeys: { mac: [], other: [] },
+    availability: 'editable',
+    params: createLayerParams,
+    run: (std, _invocation, params) => {
+        const parsed = createLayerParams.safeParse(params ?? {});
+        if (!parsed.success)
+            return;
+        if (createUserLayer(std, parsed.data.name) === null)
+            return;
+        reportLayerChange(std, 'create');
+    },
+};
+export const renameLayerParams = z.object({
+    id: z.string().min(1),
+    name: z.string(),
+});
+const renameLayer = {
+    id: 'canvas.layer.rename',
+    owner: 'core',
+    kind: 'action',
+    labelKey: 'com.labre.command.canvas.layer.rename',
+    labelFallback: 'Rename layer',
+    descriptionKey: 'com.labre.command.canvas.layer.rename.description',
+    descriptionFallback: 'Give a layer a new name.',
+    surfaces: ['agent'],
+    scope: 'edgeless',
+    defaultKeys: { mac: [], other: [] },
+    availability: 'editable',
+    params: renameLayerParams,
+    run: (std, _invocation, params) => {
+        const parsed = renameLayerParams.safeParse(params);
+        if (!parsed.success) {
+            console.error('canvas.layer.rename: invalid params', parsed.error);
+            return;
+        }
+        if (!renameUserLayer(std, parsed.data.id, parsed.data.name))
+            return;
+        reportLayerChange(std, 'rename');
+    },
+};
+export const reorderLayerParams = z.object({
+    id: z.string().min(1),
+    /** The layer it lands directly ABOVE; `null` puts it at the bottom. */
+    above: z.string().min(1).nullable(),
+});
+const reorderLayer = {
+    id: 'canvas.layer.reorder',
+    owner: 'core',
+    kind: 'action',
+    labelKey: 'com.labre.command.canvas.layer.reorder',
+    labelFallback: 'Move layer',
+    descriptionKey: 'com.labre.command.canvas.layer.reorder.description',
+    descriptionFallback: 'Place a layer directly above another one: everything in it stacks there.',
+    surfaces: ['agent'],
+    scope: 'edgeless',
+    defaultKeys: { mac: [], other: [] },
+    availability: 'editable',
+    params: reorderLayerParams,
+    run: (std, _invocation, params) => {
+        const parsed = reorderLayerParams.safeParse(params);
+        if (!parsed.success) {
+            console.error('canvas.layer.reorder: invalid params', parsed.error);
+            return;
+        }
+        if (!reorderUserLayer(std, parsed.data.id, parsed.data.above))
+            return;
+        reportLayerChange(std, 'reorder');
+    },
+};
+export const moveElementsToLayerParams = z.object({
+    /** Omitted: the current canvas selection. */
+    ids: z.array(z.string()).optional(),
+    layerId: z.string().min(1),
+});
+const moveElementsToLayer = {
+    id: 'canvas.layer.moveElements',
+    owner: 'core',
+    kind: 'action',
+    labelKey: 'com.labre.command.canvas.layer.move-elements',
+    labelFallback: 'Move to layer',
+    descriptionKey: 'com.labre.command.canvas.layer.move-elements.description',
+    descriptionFallback: 'Move the selected elements to another layer. A grouped element moves with its group.',
+    surfaces: ['agent'],
+    scope: 'edgeless',
+    defaultKeys: { mac: [], other: [] },
+    availability: 'editable',
+    params: moveElementsToLayerParams,
+    run: (std, _invocation, params) => {
+        const parsed = moveElementsToLayerParams.safeParse(params);
+        if (!parsed.success) {
+            console.error('canvas.layer.moveElements: invalid params', parsed.error);
+            return;
+        }
+        const ids = parsed.data.ids ?? std.get(GfxControllerIdentifier).selection.selectedIds;
+        const count = moveModelsToUserLayer(std, ids, parsed.data.layerId);
+        if (!count)
+            return;
+        reportLayerChange(std, 'move-elements', count);
+    },
+};
+export const deleteLayerParams = z.object({
+    /** The layer to delete; `'@default'` is refused. */
+    id: z.string().min(1),
+});
+/**
+ * Delete a layer and everything in it, in one undo step (ADR 0031 §10). The
+ * default layer cannot be deleted, which is what keeps a canvas at one layer
+ * at least (ADR 0031 amendments): with the default layer alone — recorded or
+ * not — there is nothing to delete, so `when` withdraws the command rather
+ * than letting it fail.
+ */
+const deleteLayer = {
+    id: 'canvas.layer.delete',
+    owner: 'core',
+    kind: 'action',
+    labelKey: 'com.labre.command.canvas.layer.delete',
+    labelFallback: 'Delete layer',
+    descriptionKey: 'com.labre.command.canvas.layer.delete.description',
+    descriptionFallback: 'Delete a layer and every element in it. One undo brings them all back.',
+    surfaces: ['agent'],
+    scope: 'edgeless',
+    defaultKeys: { mac: [], other: [] },
+    availability: 'editable',
+    when: std => userLayersBottomUp(std.get(GfxControllerIdentifier).surface).some(layer => layer.id !== DEFAULT_LAYER_ID),
+    params: deleteLayerParams,
+    run: (std, _invocation, params) => {
+        const parsed = deleteLayerParams.safeParse(params);
+        if (!parsed.success) {
+            console.error('canvas.layer.delete: invalid params', parsed.error);
+            return;
+        }
+        const removed = deleteUserLayer(std, parsed.data.id);
+        if (removed === null)
+            return;
+        reportLayerChange(std, 'delete', removed);
+    },
+};
+export const userLayerCommands = [
+    createLayer,
+    renameLayer,
+    reorderLayer,
+    moveElementsToLayer,
+    deleteLayer,
+];