@formicoidea/labre-core 0.42.0 → 0.45.0

package/dist/_pkgs/affine-block-surface/extensions/svg-sketch.js

@@ -1,6 +1,7 @@
 import { ShapeStyle, ShapeType, StrokeStyle, TextAlign, } from '../../affine-model/index.js';
 import DOMPurify from 'dompurify';
-import { SVG_SKETCH_CURRENT_COLOR, SVG_SKETCH_CURVE, SVG_SKETCH_EMPTY, SVG_SKETCH_EMPTY_BOX, SVG_SKETCH_EMPTY_TEXT, SVG_SKETCH_FLAT_POLYGON, SVG_SKETCH_FONT_UNIT, SVG_SKETCH_HIDDEN_DISPLAY, SVG_SKETCH_HIDDEN_VISIBILITY, SVG_SKETCH_LONE_POINT, SVG_SKETCH_OPACITY, SVG_SKETCH_PAINT_SERVER, SVG_SKETCH_PERCENT_RADIUS, SVG_SKETCH_REMOVED, SVG_SKETCH_REMOVED_ATTRIBUTE, SVG_SKETCH_SKIPPED, SVG_SKETCH_SWITCH, SVG_SKETCH_TRANSFORM, } from './svg-sketch-translations.js';
+import { InterchangeImportError, } from './interchange.js';
+import { SVG_SKETCH_CURRENT_COLOR, SVG_SKETCH_CURVE, SVG_SKETCH_EMPTY, SVG_SKETCH_EMPTY_BOX, SVG_SKETCH_EMPTY_TEXT, SVG_SKETCH_ERROR_MALFORMED_XML, SVG_SKETCH_ERROR_NOT_SVG, SVG_SKETCH_ERROR_SANITIZED_AWAY, SVG_SKETCH_FLAT_POLYGON, SVG_SKETCH_FONT_UNIT, SVG_SKETCH_HIDDEN_DISPLAY, SVG_SKETCH_HIDDEN_VISIBILITY, SVG_SKETCH_LONE_POINT, SVG_SKETCH_OPACITY, SVG_SKETCH_PAINT_SERVER, SVG_SKETCH_PERCENT_RADIUS, SVG_SKETCH_REMOVED, SVG_SKETCH_REMOVED_ATTRIBUTE, SVG_SKETCH_SKIPPED, SVG_SKETCH_SWITCH, SVG_SKETCH_TRANSFORM, } from './svg-sketch-translations.js';
 /**
  * **SVG → a canvas sketch.** The platform's VISUAL-tier importer, shared by
  * every framework that declares it (`docs/adr/0012`, P2).
@@ -11,9 +12,11 @@ import { SVG_SKETCH_CURRENT_COLOR, SVG_SKETCH_CURVE, SVG_SKETCH_EMPTY, SVG_SKETC
  * a one-paragraph statement of its heuristics and its known failure modes" —
  * answered ONCE, here, because every framework that declares `…:svg:import`
  * wraps this one function and therefore owes the same statement. It is
- * referenced by `bpmn:svg:import` and by `wardley:svg:import`; a framework that
- * ever wants a narrower or wider guess writes its own parser and its own
- * paragraph beside it._
+ * referenced by `bpmn:svg:import`; a framework that ever wants a narrower or
+ * wider guess writes its own parser and its own paragraph beside it. Wardley
+ * did (ADR 0032): a framework may CLAIM nodes before the walk below
+ * ({@link sanitizeSvg}, {@link sketchSvgTree}), and then owes its own statement
+ * for what it claims — this one still covers everything it leaves here._
  *
  * **What it guesses.** An SVG carries a rendering, not a model, so this reader
  * recognises GEOMETRY and nothing else: `<rect>` becomes a rectangle,
@@ -164,8 +167,12 @@ function numbers(raw) {
  * Every note is a `warning`. The other four kinds would be lies here:
  * `carried` and `quarantined` describe a payload this tier does not write, and
  * `substituted-id` and `invented-layout` describe promises it does not make.
+ *
+ * Exported so a framework that claims part of a picture first (ADR 0032 §2)
+ * hands the SAME notebook to {@link sanitizeSvg} and {@link sketchSvgTree}: one
+ * file, one de-duplication, one list of remarks.
  */
-class Notebook {
+export class SvgSketchNotebook {
     constructor() {
         this.seen = new Set();
         this.notes = [];
@@ -773,6 +780,8 @@ function walk(parent, frame, inherited, sketch) {
 }
 /** One element and whatever it contains, placed in its parent's frame. */
 function visit(element, frame, inherited, sketch) {
+    if (sketch.skip.has(element))
+        return;
     const name = nameOf(element);
     if (NON_RENDERING.has(name))
         return;
@@ -850,6 +859,68 @@ function emit(element, name, frame, paint, sketch) {
             sketch.notes.once(`skipped:${name}`, `\`<${name}>\` is not recognised and was skipped.`, SVG_SKETCH_SKIPPED, { name }, name);
     }
 }
+/* ── The two passes, opened to a recogniser (ADR 0032 §2) ────────────── */
+/**
+ * The second pass: a sanitised tree as sketch props, minus what a caller
+ * claimed.
+ *
+ * `skip` is the set of nodes a framework's recogniser already turned into its
+ * own artefacts; each one is left alone WITH its subtree, and everything else
+ * is read exactly as {@link parseSvgSketch} reads it. `place` composes a frame
+ * OUTSIDE the file's own viewport — `canvas = place.s · file + place.o` — so
+ * the remainder can land beside a board the recogniser laid out at another
+ * scale. Both default to nothing, which is {@link parseSvgSketch} itself.
+ *
+ * A framework that claims nodes owes its own heuristics statement for what it
+ * claims; this module's statement covers only what reaches this walk.
+ */
+export function sketchSvgTree(root, notes, options = {}) {
+    const sketch = {
+        elements: [],
+        notes,
+        skip: options.skip ?? new Set(),
+    };
+    const place = options.place ?? IDENTITY;
+    const own = viewportFrame(root, IDENTITY);
+    // The root `<svg>` paints like any other element — a `fill` on it is what
+    // every shape under it inherits — and it establishes the outermost viewport.
+    walk(root, {
+        ox: own.ox * place.s + place.ox,
+        oy: own.oy * place.s + place.oy,
+        s: own.s * place.s,
+    }, paintOf(root, INITIAL_PAINT, notes), sketch);
+    return sketch.elements;
+}
+/**
+ * The frame a node's OWN attributes are read in — its `cx`, its `x1`, its
+ * `points` — composed exactly the way the walk composes it: the root's
+ * viewport, then every ancestor's translate and nested viewport, then the
+ * node's own `transform`. So a recogniser that reads a circle's centre through
+ * this lands it on the very point the sketch would have drawn it.
+ *
+ * The transforms the walk ignores are ignored here too, silently: the walk
+ * already says so once per kind when it meets them.
+ */
+export function svgFrameOf(element) {
+    const path = [];
+    for (let at = element; at; at = at.parentElement) {
+        path.unshift(at);
+    }
+    // The outermost `<svg>` on the path is the root the walk starts from: its
+    // viewport is the identity's, and its own `transform` is never read.
+    const rootIndex = path.findIndex(node => nameOf(node) === 'svg');
+    if (rootIndex < 0)
+        return IDENTITY;
+    const quiet = new SvgSketchNotebook();
+    let frame = viewportFrame(path[rootIndex], IDENTITY);
+    for (const node of path.slice(rootIndex + 1)) {
+        frame = translated(node, frame, quiet);
+        if (node !== element && nameOf(node) === 'svg') {
+            frame = viewportFrame(node, frame);
+        }
+    }
+    return frame;
+}
 /* ── The capability's function ────────────────────────────────────────── */
 /**
  * The document, sanitized, or an exception naming what is wrong with it.
@@ -866,8 +937,12 @@ function emit(element, name, frame, paint, sketch) {
  * handler attributes — handed over by whoever sent the file. The same
  * `USE_PROFILES: { svg: true }` guard is what the edgeless clipboard already
  * puts in front of a pasted SVG.
+ *
+ * The first of the two passes {@link parseSvgSketch} is made of, exported so a
+ * framework that recognises part of a picture reads the SAME sanitised tree
+ * the sketch walks (ADR 0032 §2, §7) — never the source.
  */
-function parseSvgRoot(source, notes) {
+export function sanitizeSvg(source, notes) {
     const doc = new DOMParser().parseFromString(source, 'image/svg+xml');
     const error = doc.querySelector('parsererror');
     if (error) {
@@ -879,10 +954,15 @@ function parseSvgRoot(source, notes) {
             .split('\n')
             .map(line => line.trim())
             .filter(line => line.length > 0);
-        throw new Error(`This file is not well-formed XML, so no drawing can be read out of it: ${summary.slice(0, 200)}`);
+        const detail = summary.slice(0, 200);
+        throw new InterchangeImportError(`This file is not well-formed XML, so no drawing can be read out of it: ${detail}`, {
+            messageKey: SVG_SKETCH_ERROR_MALFORMED_XML[0],
+            messageParams: { detail },
+        });
     }
     if (nameOf(doc.documentElement) !== 'svg') {
-        throw new Error(`An SVG opens on <svg>; this one opens on <${doc.documentElement?.localName ?? 'nothing'}>.`);
+        const tag = doc.documentElement?.localName ?? 'nothing';
+        throw new InterchangeImportError(`An SVG opens on <svg>; this one opens on <${tag}>.`, { messageKey: SVG_SKETCH_ERROR_NOT_SVG[0], messageParams: { tag } });
     }
     const clean = DOMPurify.sanitize(source, {
         USE_PROFILES: { svg: true },
@@ -923,7 +1003,9 @@ function parseSvgRoot(source, notes) {
     // overload, which answers an `HTMLElement` — the sanitized body wrapper.
     const root = childElements(clean).find(child => nameOf(child) === 'svg');
     if (!root) {
-        throw new Error('Nothing survived sanitizing this SVG, so there is no drawing to read.');
+        throw new InterchangeImportError(SVG_SKETCH_ERROR_SANITIZED_AWAY[1], {
+            messageKey: SVG_SKETCH_ERROR_SANITIZED_AWAY[0],
+        });
     }
     return root;
 }
@@ -944,25 +1026,22 @@ export function parseSvgSketch(source, context = {}) {
     // A sketch has no document-level name to take: what a board is CALLED is the
     // document's business, not any element's. Same answer the BPMN reader gives.
     void context;
-    const sketch = { elements: [], notes: new Notebook() };
-    const root = parseSvgRoot(source, sketch.notes);
-    // The root `<svg>` paints like any other element — a `fill` on it is what
-    // every shape under it inherits — and it establishes the outermost viewport.
-    walk(root, viewportFrame(root, IDENTITY), paintOf(root, INITIAL_PAINT, sketch.notes), sketch);
-    if (sketch.elements.length === 0) {
-        sketch.notes.once('empty', 'No shape or text was recognised in this SVG, so nothing was drawn.', SVG_SKETCH_EMPTY);
+    const notes = new SvgSketchNotebook();
+    const elements = sketchSvgTree(sanitizeSvg(source, notes), notes);
+    if (elements.length === 0) {
+        notes.once('empty', 'No shape or text was recognised in this SVG, so nothing was drawn.', SVG_SKETCH_EMPTY);
     }
     return {
-        elements: sketch.elements,
+        elements,
         report: {
-            mapped: sketch.elements.length,
+            mapped: elements.length,
             // Always zero, and it is the tier's whole contract rather than an
             // accident of this file: a visual import carries nothing and quarantines
             // nothing, because it writes no `interchange` payload to carry anything
             // IN (ADR 0012, P2). Pinned by an anti-decay test.
             carried: 0,
             quarantined: 0,
-            notes: sketch.notes.notes,
+            notes: notes.notes,
             // …and no `sourceVersion`. An SVG declares a version of the SVG spec, not
             // a version of a vocabulary this reader translates, so claiming one would
             // be a fact about the file dressed up as a fact about the import.

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;
+    }
+}