@formicoidea/labre-core 0.31.0 → 0.32.0

package/dist/_pkgs/std/gfx/model/surface/surface-model.js

@@ -6,8 +6,9 @@ import { Subject } from 'rxjs';
 import * as Y from 'yjs';
 import { isGfxGroupCompatibleModel, } from '../base.js';
 import { createDecoratorState } from './decorators/common.js';
-import { initializeObservers, initializeWatchers } from './decorators/index.js';
+import { getFieldPropsSet, getLocalPropsSet, initializeObservers, initializeWatchers, } from './decorators/index.js';
 import { GfxGroupLikeElementModel, syncElementFromY, } from './element-model.js';
+import { tagsPropToY } from './tags.js';
 /**
  * Used for text field
  */
@@ -16,7 +17,177 @@ export const SURFACE_TEXT_UNIQ_IDENTIFIER = 'affine:surface:text';
  * Used for field that use Y.Map. E.g. group children field
  */
 export const SURFACE_YMAP_UNIQ_IDENTIFIER = 'affine:surface:ymap';
+/**
+ * Prop keys that are never copied onto an element, whatever the caller sends.
+ *
+ * - `id` / `type` are the element's identity. They are written explicitly when
+ *   the element is created and must not be rewritten through a bulk props
+ *   assignment (a caller doing `updateElement(id, otherElement.serialize())`
+ *   would otherwise stamp a stale identity into the document).
+ * - `__proto__` / `constructor` / `prototype` are the prototype-pollution
+ *   vector: assigning them mutates the class or `Object.prototype` instead of
+ *   the document. They are dropped rather than forwarded to the Y.Map.
+ *
+ * **This list is load-bearing for security, not just hygiene — do not assume
+ * the routing makes it redundant.** `Object.prototype.__proto__` is an
+ * accessor **with a setter**, so it is present on the prototype chain of every
+ * element type and {@link isDeclaredElementProp} would route it to the
+ * instance assignment, i.e. mutate the element's prototype. The only thing
+ * stopping that is this deny-list, which is evaluated first.
+ *
+ * Everything else is either a declared accessor or an unknown key, and both
+ * are handled by {@link SurfaceBlockModel._assignElementProp}.
+ */
+const UNSAFE_ELEMENT_PROP_KEYS = new Set([
+    'id',
+    'type',
+    '__proto__',
+    'constructor',
+    'prototype',
+]);
+/**
+ * Whether the element class DECLARED this prop, i.e. whether the assignment
+ * `element[key] = value` is something the class asked for.
+ *
+ * Three sources, and no more:
+ *
+ * - the `@field()` set and the `@local()` set the decorators maintain per
+ *   prototype — the authoritative table for every decorated accessor;
+ * - a plain accessor **that has a setter**, found by walking the prototype
+ *   chain. The only such prop today is `xywh` on `GfxGroupLikeElementModel`,
+ *   whose value is derived from the children and whose setter is a deliberate
+ *   no-op; since `serialize()` always emits `xywh`, treating it as unknown
+ *   would persist a stale derived value into every duplicated group.
+ *
+ * Explicitly NOT `key in element`, which also matches methods (`serialize`,
+ * `isLocked`, …), getter-only derived props (`x`, `y`, `w`, `h`, `group`,
+ * `elementBound`, …) and internal instance fields (`_local`, `_preserved`).
+ * Assigning to any of those corrupts the model instead of describing it. The
+ * descriptor walk stops at the first prototype that owns the key, so a method
+ * (data descriptor, no setter) and a getter-only accessor both answer `false`.
+ */
+function isDeclaredElementProp(element, key) {
+    if (getFieldPropsSet(element).has(key) || getLocalPropsSet(element).has(key)) {
+        return true;
+    }
+    for (let proto = Object.getPrototypeOf(element); proto !== null; proto = Object.getPrototypeOf(proto)) {
+        const descriptor = Object.getOwnPropertyDescriptor(proto, key);
+        if (descriptor) {
+            return typeof descriptor.set === 'function';
+        }
+    }
+    return false;
+}
+/**
+ * Depth limit for the encodability check below. Element props are flat by
+ * contract; this only exists so a pathologically deep payload cannot turn the
+ * check itself into the stack overflow it is meant to prevent.
+ */
+const MAX_UNKNOWN_PROP_DEPTH = 32;
+/**
+ * Whether a value can be stored in an element's Y.Map without breaking the
+ * document.
+ *
+ * `Y.Map.set` accepts a value it cannot later encode: a cyclic plain object is
+ * stored happily, `serialize()` and `encodeStateVector` keep working, and only
+ * `encodeStateAsUpdate` — i.e. persistence and sync — blows the stack. Nothing
+ * in the app notices, and no user action can remove the key. So an unknown
+ * prop is admitted only if it is provably encodable: a Yjs type (which
+ * `_propsToY` may have built from a `Y.Text` / `Y.Map` wrapper payload), a
+ * binary blob, a primitive, or a plain object / array of those, acyclic and
+ * within the depth limit.
+ *
+ * Anything else (function, symbol, bigint, class instance, cycle) is rejected,
+ * and the key is dropped exactly as it was before unknown props were
+ * forwarded at all.
+ */
+function isEncodableElementValue(value, depth = 0, seen = new Set()) {
+    if (value === null || value === undefined) {
+        return true;
+    }
+    // Already a Yjs type: `_propsToY` builds these for the wrapper payloads, and
+    // Yjs owns their encoding.
+    if (value instanceof Y.AbstractType) {
+        return true;
+    }
+    if (value instanceof Uint8Array) {
+        return true;
+    }
+    const type = typeof value;
+    if (type === 'string' || type === 'number' || type === 'boolean') {
+        return true;
+    }
+    if (type !== 'object') {
+        // function, symbol, bigint
+        return false;
+    }
+    if (depth >= MAX_UNKNOWN_PROP_DEPTH) {
+        return false;
+    }
+    // Cycle detection is per path, so a value shared by two sibling branches
+    // (a DAG) is still accepted.
+    if (seen.has(value)) {
+        return false;
+    }
+    seen.add(value);
+    try {
+        if (Array.isArray(value)) {
+            return value.every(item => isEncodableElementValue(item, depth + 1, seen));
+        }
+        // Only plain objects. A class instance would be silently flattened by the
+        // Yjs encoder, which is never what the caller meant.
+        //
+        // `Object.create(null)` is rejected too, and for a sharper reason: Yjs
+        // dispatches on `value.constructor`, which is `undefined` on a
+        // null-prototype object, so `Y.Map.set` throws `Unexpected content type`
+        // — from inside `store.transact`, which swallows it and takes every
+        // remaining prop of the same payload with it.
+        const proto = Object.getPrototypeOf(value);
+        if (proto !== Object.prototype) {
+            return false;
+        }
+        return Object.values(value).every(item => isEncodableElementValue(item, depth + 1, seen));
+    }
+    finally {
+        seen.delete(value);
+    }
+}
+/**
+ * {@link isEncodableElementValue}, but it never throws.
+ *
+ * The guard is the layer that protects the assignment loop, so it must not be
+ * able to break it. Inspecting a value can raise: `Object.values` invokes
+ * getters, and a getter that throws — or a hostile proxy trap — would escape
+ * into `store.transact`, which swallows the error and silently drops every
+ * prop after this one. That is the very failure mode this change removes, so
+ * an inspection that blows up means "not storable", nothing more.
+ */
+function canStoreUnknownPropValue(value) {
+    try {
+        return isEncodableElementValue(value);
+    }
+    catch {
+        return false;
+    }
+}
 export class SurfaceBlockModel extends BlockModel {
+    /**
+     * The props that are known to move the bound of the containing group, so a
+     * write on one of them refreshes that bound eagerly (and notifies the layer
+     * and the renderer within the same tick).
+     *
+     * It is deliberately NOT the exhaustive list of what a bound can depend on:
+     * a subclass may fold a custom prop into its own `elementBound` (our polygon
+     * shape does it with `vertices`, the connector with `labelXYWH`). Anything
+     * outside this set therefore only *invalidates* the cached bound — the next
+     * read recomputes it — which keeps such elements correct without paying the
+     * eager recomputation on every unrelated prop write.
+     */
+    static { this._groupBoundImpactKeys = new Set([
+        'xywh',
+        'rotate',
+        'hidden',
+    ]); }
     get elementModels() {
         const models = [];
         this._elementModels.forEach(model => models.push(model.model));
@@ -71,12 +242,78 @@ export class SurfaceBlockModel extends BlockModel {
         yMap.set('id', id);
         Object.keys(rest).forEach(key => {
             if (props[key] !== undefined) {
-                // @ts-expect-error ignore
-                elementModel.model[key] = props[key];
+                this._assignElementProp(elementModel.model, key, props[key]);
             }
         });
         return elementModel;
     }
+    /**
+     * Copies one serialized prop onto an element, routing it EXPLICITLY.
+     *
+     * Three outcomes, in order:
+     *
+     * 1. an unsafe key ({@link UNSAFE_ELEMENT_PROP_KEYS}) is dropped;
+     * 2. a key the element class **declared** ({@link isDeclaredElementProp})
+     *    goes through its accessor, exactly as before;
+     * 3. anything else is an unknown key and is written verbatim into the
+     *    element's Y.Map, provided the value is encodable.
+     *
+     * Step 2 deliberately does **not** ask `key in element`. That question is far
+     * wider than "did the class declare this prop": it also matches every method
+     * (`serialize`, `isLocked`, `stash`…), every getter-only derived prop (`x`,
+     * `y`, `w`, `h`, `group`, `elementBound`…) and every internal instance field
+     * (`_local`, `_preserved`…). Routing those to the instance is what used to
+     * corrupt the model — a data key named `serialize` shadowed the method with a
+     * string, and a data key named `x` threw `TypeError: only a getter`, which
+     * `store.transact` swallows, silently losing every prop after it in the same
+     * bulk update. With the declared-prop sets, such a key is simply unknown data:
+     * it lands in the Y.Map, where it shadows nothing (methods and derived getters
+     * live on the prototype and are read from there).
+     *
+     * Step 3 refuses a value it could not encode. `Y.Map.set` accepts a cyclic
+     * object and only fails later, in `encodeStateAsUpdate` — i.e. it breaks
+     * persistence and sync for good, invisibly. Dropping the key restores the
+     * pre-existing behaviour for that one prop and keeps the document sound; the
+     * doc's "values stay flat JSON" claim is now enforced rather than assumed.
+     *
+     * An `undefined` value is never written on the unknown branch either, so
+     * spreading an absent option (`{ ...opts }` with `opts.foo === undefined`)
+     * cannot mint a phantom key that is invisible in `serialize()` yet real for
+     * every peer. Declared fields keep accepting `undefined`, which is how an
+     * optional field is cleared.
+     *
+     * The asymmetry that follows is deliberate: an unknown key already present
+     * in the Y.Map can never be removed through `updateElement`, since
+     * `undefined` is the only way to ask for that and it is ignored here. On a
+     * client that does not declare the field, an unknown key is immortal. That
+     * is the right direction to err for a preservation contract — the client
+     * that understands the field can still clear it through its accessor — but
+     * it does mean this API cannot delete what it does not understand.
+     *
+     * The value is already Y-converted at this point: both call sites run the
+     * whole props object through {@link _propsToY} first, which is key-agnostic.
+     *
+     * See `docs/spikes/us-1-8-unknown-props-preservation.md`.
+     */
+    _assignElementProp(element, key, value) {
+        if (UNSAFE_ELEMENT_PROP_KEYS.has(key)) {
+            return;
+        }
+        if (isDeclaredElementProp(element, key)) {
+            // @ts-expect-error ignore
+            element[key] = value;
+            return;
+        }
+        if (value === undefined) {
+            return;
+        }
+        if (!canStoreUnknownPropValue(value)) {
+            console.warn(`Dropping unknown element prop "${key}": the value cannot be encoded ` +
+                `into the document (expected a Yjs type, or flat JSON without cycles).`);
+            return;
+        }
+        element.yMap.set(key, value);
+    }
     _createElementFromYMap(type, id, yMap, options) {
         const stashed = new Map();
         const Ctor = this._elementCtorMap[type];
@@ -123,6 +360,52 @@ export class SurfaceBlockModel extends BlockModel {
             unmount,
         };
     }
+    /**
+     * The single place an element update leaves the surface: it fans the payload
+     * out to the subscribers and keeps the bound of the containing group in sync.
+     */
+    _emitElementUpdated(model, payload) {
+        this.elementUpdated.next(payload);
+        Object.keys(payload.props).forEach(key => {
+            model.propsUpdated.next({ key });
+        });
+        this._refreshParentGroupBoundsForElement(model, payload);
+    }
+    _invalidateParentGroupBounds(id) {
+        if (this._groupLikeModels.size === 0) {
+            return;
+        }
+        const group = this.getGroup(id);
+        if (group instanceof GfxGroupLikeElementModel) {
+            group.invalidateXYWH();
+        }
+    }
+    _refreshParentGroupBounds(id, local) {
+        if (this._groupLikeModels.size === 0) {
+            return;
+        }
+        const group = this.getGroup(id);
+        if (group instanceof GfxGroupLikeElementModel) {
+            group.refreshXYWH(local);
+        }
+    }
+    _refreshParentGroupBoundsForElement(model, payload) {
+        if (model instanceof GfxGroupLikeElementModel &&
+            ('childIds' in payload.props || 'childIds' in payload.oldValues)) {
+            model.refreshXYWH(payload.local);
+            return;
+        }
+        const affectedKeys = new Set([
+            ...Object.keys(payload.props),
+            ...Object.keys(payload.oldValues),
+        ]);
+        if (Array.from(affectedKeys).some(key => SurfaceBlockModel._groupBoundImpactKeys.has(key))) {
+            this._refreshParentGroupBounds(model.id, payload.local);
+        }
+        else {
+            this._invalidateParentGroupBounds(model.id);
+        }
+    }
     _initElementModels() {
         const elementsYMap = this.elements.getValue();
         const addToType = (type, model) => {
@@ -160,10 +443,7 @@ export class SurfaceBlockModel extends BlockModel {
                                 ? this._elementModels.get(id)
                                 : this._createElementFromYMap(element.get('type'), element.get('id'), element, {
                                     onChange: payload => {
-                                        this.elementUpdated.next(payload);
-                                        Object.keys(payload.props).forEach(key => {
-                                            model.model.propsUpdated.next({ key });
-                                        });
+                                        this._emitElementUpdated(model.model, payload);
                                     },
                                     skipFieldInit: true,
                                 });
@@ -199,10 +479,7 @@ export class SurfaceBlockModel extends BlockModel {
         elementsYMap.forEach((val, key) => {
             const model = this._createElementFromYMap(val.get('type'), val.get('id'), val, {
                 onChange: payload => {
-                    this.elementUpdated.next(payload),
-                        Object.keys(payload.props).forEach(key => {
-                            model.model.propsUpdated.next({ key });
-                        });
+                    this._emitElementUpdated(model.model, payload);
                 },
                 skipFieldInit: true,
             });
@@ -224,6 +501,9 @@ export class SurfaceBlockModel extends BlockModel {
                     if (isGfxGroupCompatibleModel(payload.model)) {
                         this._groupLikeModels.set(payload.id, payload.model);
                     }
+                    if (payload.model instanceof BlockModel) {
+                        this._refreshParentGroupBounds(payload.id, payload.isLocal);
+                    }
                     break;
                 case 'delete':
                     if (isGfxGroupCompatibleModel(payload.model)) {
@@ -237,6 +517,14 @@ export class SurfaceBlockModel extends BlockModel {
                         }
                     }
                     break;
+                case 'update':
+                    // A canvas block folds nothing else into its `elementBound`, so
+                    // unlike a surface element it needs no lazy invalidation here.
+                    if (payload.props.key &&
+                        SurfaceBlockModel._groupBoundImpactKeys.has(payload.props.key)) {
+                        this._refreshParentGroupBounds(payload.id, payload.isLocal);
+                    }
+                    break;
             }
         });
         this.deleted.subscribe(() => {
@@ -266,6 +554,9 @@ export class SurfaceBlockModel extends BlockModel {
                 }
             }
         });
+        // `tags` is declared on the BASE class, so no per-class `propsToY` hook
+        // covers it. Run before the class hook, which may legitimately not exist.
+        tagsPropToY(props);
         // @ts-expect-error ignore
         return ctor.propsToY ? ctor.propsToY(props) : props;
     }
@@ -329,10 +620,7 @@ export class SurfaceBlockModel extends BlockModel {
         props.id = id;
         const elementModel = this._createElementFromProps(props, {
             onChange: payload => {
-                this.elementUpdated.next(payload);
-                Object.keys(payload.props).forEach(key => {
-                    elementModel.model.propsUpdated.next({ key });
-                });
+                this._emitElementUpdated(elementModel.model, payload);
             },
         });
         this._elementModels.set(id, elementModel);
@@ -456,8 +744,7 @@ export class SurfaceBlockModel extends BlockModel {
         this.store.transact(() => {
             props = this._propsToY(elementModel.type, props);
             Object.entries(props).forEach(([key, value]) => {
-                // @ts-expect-error ignore
-                elementModel[key] = value;
+                this._assignElementProp(elementModel, key, value);
             });
         });
     }

package/dist/_pkgs/std/gfx/model/surface/tags.d.ts

@@ -0,0 +1,77 @@
+import type { GfxPrimitiveElementModel } from './element-model.js';
+/** The `@field()` key. Spelled once. */
+export declare const ELEMENT_TAGS_FIELD = "tags";
+/**
+ * A flattened snapshot of an element's qualification: tag def id → value ids.
+ * The transport shape — `OccurrenceMaterialityPatch.tags` is exactly this — and
+ * deliberately NOT the persisted one.
+ */
+export type ElementTags = Record<string, string[]>;
+/**
+ * Every tag on the element, as plain JSON. `{}` when unqualified — absent and
+ * empty are the same fact, and no caller should have to distinguish them.
+ *
+ * Defensive by construction: the map is a document value, so a client of any
+ * vintage may have written something else into it. Both shapes a real client
+ * can produce are read ({@link isDegradedTags}); a malformed entry is skipped,
+ * never thrown on. A board that cannot be read is worse than a tag that is not.
+ */
+export declare function readElementTags(element: GfxPrimitiveElementModel): ElementTags;
+/** The value ids selected for one tag, `[]` when it carries none. */
+export declare function elementTagValues(element: GfxPrimitiveElementModel, tagId: string): string[];
+/** Whether the element carries `valueId` under `tagId`. */
+export declare function hasElementTagValue(element: GfxPrimitiveElementModel, tagId: string, valueId: string): boolean;
+/**
+ * Set (or, with an empty `values`, remove) ONE tag on ONE element. Returns
+ * whether anything was written — a gesture that changes nothing must not cost an
+ * undo step and must not be reported.
+ *
+ * The caller owns `store.captureSync()`, and owes it BEFORE this call: the undo
+ * manager is built with no `captureTimeout`, so a qualification issued within
+ * 500 ms of a drag would otherwise be undone together with the drag — making a
+ * promotion look like it moved geometry, which is exactly what the ladder's
+ * invariants forbid.
+ *
+ * ## The cases, and why the first one is the point
+ *
+ * - **A `Y.Map` already** — the entry is set IN PLACE. Replacing the whole map
+ *   instead would restore whole-blob last-write-wins and silently drop a
+ *   concurrent edit on a different tag, which is the single reason the field is
+ *   a nested map at all. Removing the last entry removes the key with
+ *   `clearField` rather than leaving an empty map behind: an element qualified
+ *   and then un-qualified goes back to costing nothing, like one that never was.
+ * - **Nothing yet** — a map is created and assigned through `updateElement`,
+ *   which is what attaches it to the document and starts the nested observer.
+ * - **The degraded shape** ({@link isDegradedTags}) — the map is created from
+ *   what is ALREADY there, plus the change. This is the one case where
+ *   replacing wholesale is right, because a plain object was never mergeable in
+ *   the first place; what would be wrong, and was, is replacing it with a map
+ *   holding only the new tag. A colleague's qualification, written by a client
+ *   that predates this field, would leave without a word.
+ *
+ * ## Read-only
+ *
+ * A read-only store is a no-op with a warning, not a throw and not a write.
+ * This is exported from `@labre/std/gfx`, so a host can call it directly, and
+ * the three write paths below reach the document three different ways: an
+ * in-place `store.transact` and `clearField` carry no read-only guard of their
+ * own (they would silently succeed), while `updateElement` throws. Three
+ * behaviours for one refusal is not a contract; one guard here is.
+ */
+export declare function setElementTag(element: GfxPrimitiveElementModel, tagId: string, values: readonly string[]): boolean;
+/**
+ * Rebuild `tags` as a `Y.Map` when it arrives as plain JSON.
+ *
+ * Called by `SurfaceBlockModel._propsToY` for EVERY element type, because the
+ * field is declared on the base class and per-class `propsToY` hooks are not.
+ * Without it, paste / duplicate / alt-drag clone would each store the copy's
+ * qualification as one opaque plain object — indistinguishable from a correct
+ * copy until two people edited it and one of them lost their tag.
+ *
+ * `element.serialize()` is `yMap.toJSON()`, so the nested map reaches every one
+ * of those paths as a plain object with no wrapper; the snapshot path arrives
+ * already converted by the `SURFACE_YMAP_UNIQ_IDENTIFIER` branch above the call
+ * and is passed through untouched. An empty (or unusable) value drops the key
+ * entirely rather than writing a tombstone.
+ */
+export declare function tagsPropToY(props: Record<string, unknown>): void;