@matter/model 0.16.0-alpha.0-20251018-dd1ea6a8a → 0.16.0-alpha.0-20251020-3f6e46245

package/dist/cjs/decoration/semantics/ClassSemantics.js

@@ -0,0 +1,266 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var ClassSemantics_exports = {};
+__export(ClassSemantics_exports, {
+  ClassSemantics: () => ClassSemantics
+});
+module.exports = __toCommonJS(ClassSemantics_exports);
+var import_models = require("#models/index.js");
+var import_general = require("#general");
+var import_Scope = require("#logic/Scope.js");
+var import_models2 = require("#standard/elements/models.js");
+var import_errors = require("../errors.js");
+var import_FieldSemantics = require("./FieldSemantics.js");
+var import_Semantics = require("./Semantics.js");
+/**
+ * @license
+ * Copyright 2022-2025 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+const matter = Symbol("matter");
+class ClassSemantics extends import_Semantics.Semantics {
+  #new;
+  #definedFields;
+  /**
+   * The model that represents the semantics for this class.
+   *
+   * This may be {@link localModel} or {@link prototypeBaseModel}
+   */
+  get semanticModel() {
+    if (this.localModel) {
+      return this.localModel;
+    }
+    if (this.#definedFields) {
+      return this.mutableModel;
+    }
+    return this.prototypeBaseModel;
+  }
+  /**
+   * Get the class constructor
+   */
+  get new() {
+    return this.#new;
+  }
+  /**
+   * Assign the constructor for the class.
+   */
+  set new(fn) {
+    if (this.#new === fn) {
+      return;
+    }
+    if (this.isFinal) {
+      throw new import_errors.MetadataConflictError(
+        `Cannot install semantic constructor ${fn.name} because semantics are final`
+      );
+    }
+    this.#new = fn;
+    if (this.localModel && !this.localModel.isFinal && this.localModel.name !== this.#new?.name) {
+      this.localModel.name = this.#new?.name;
+    }
+    if (this.localModel) {
+      this.#applyBaseSemantics();
+    } else {
+      const base = this.prototypeBaseModel;
+      if (base !== void 0) {
+        this.mutableModel = base;
+      }
+    }
+  }
+  /**
+   * The class {@link Model} inherited from {@link new}'s prototype chain, if any.
+   */
+  get prototypeBaseModel() {
+    let current = this.#new?.prototype;
+    let base;
+    while (current) {
+      current = Object.getPrototypeOf(current);
+      if (typeof current !== "object" || current === null) {
+        return;
+      }
+      const constructor = current.constructor;
+      if (constructor === Object) {
+        return;
+      }
+      base = ClassSemantics.maybeOf(constructor);
+      if (base?.localModel) {
+        base.finalize();
+        return base.localModel;
+      }
+    }
+  }
+  /**
+   * Obtain a {@link FieldSemantics} for the named field.
+   */
+  fieldFor(name) {
+    if (typeof name !== "string") {
+      throw new import_errors.InvalidMetadataError(`Cannot decorate symbolic function ${String(name)}`);
+    }
+    if (this.#definedFields === void 0) {
+      this.#definedFields = /* @__PURE__ */ new Map();
+    }
+    let field = this.#definedFields.get(name);
+    if (field === void 0) {
+      if (this.isFinal) {
+        throw new import_errors.MetadataConflictError(`Cannot install field ${name} because semantics are final`);
+      }
+      this.#definedFields.set(name, field = new import_FieldSemantics.FieldSemantics(this, name));
+    }
+    return field;
+  }
+  /**
+   * Add logical fields for unrecognized members of an object.
+   *
+   * This extends the model with untyped fields for properties that are not otherwise typed.
+   */
+  defineUnknownMembers(instance) {
+    if (instance === void 0 || instance === null) {
+      return;
+    }
+    const known = this.semanticModel ? new Set(
+      (0, import_Scope.Scope)(this.semanticModel).membersOf(this.semanticModel).map((model) => (0, import_general.camelize)(model.name))
+    ) : /* @__PURE__ */ new Set();
+    const descriptors = Object.getOwnPropertyDescriptors(instance);
+    for (const name in descriptors) {
+      if (known.has((0, import_general.camelize)(name))) {
+        continue;
+      }
+      if (typeof name !== "string") {
+        continue;
+      }
+      const descriptor = descriptors[name];
+      if (descriptor.set && !descriptor.get) {
+        continue;
+      }
+      try {
+        if (typeof instance[name] === "function") {
+          continue;
+        }
+      } catch (e) {
+        continue;
+      }
+      const model = this.fieldFor(name).mutableModel;
+      model.operationalBase = import_models2.any;
+      if (!descriptor.writable && !descriptor.set) {
+        model.quality = { ...model.quality, fixed: true };
+      }
+      this.fieldFor(name).mutableModel.operationalBase = import_models2.any;
+    }
+  }
+  /**
+   * Obtain the {@link ClassSemantics} for {@link source}.
+   */
+  static of(source) {
+    if (source instanceof ClassSemantics) {
+      return source;
+    }
+    if (typeof source !== "function") {
+      const metadata2 = source.metadata;
+      if (Object.hasOwn(metadata2, matter)) {
+        return metadata2[matter];
+      }
+      return metadata2[matter] = new ClassSemantics();
+    }
+    let metadata;
+    if (!Object.hasOwn(source, Symbol.metadata)) {
+      metadata = source[Symbol.metadata] = {};
+    } else {
+      metadata = source[Symbol.metadata];
+    }
+    let semantics;
+    if (!Object.hasOwn(metadata, matter)) {
+      semantics = metadata[matter] = new ClassSemantics();
+    } else {
+      semantics = metadata[matter];
+    }
+    if (!semantics.new) {
+      semantics.new = source;
+    }
+    return semantics;
+  }
+  /**
+   * Determine {@link new} has semantic decoration.
+   */
+  static hasOwnSemantics(source) {
+    return Object.hasOwn(source, Symbol.metadata) && Object.hasOwn(source[Symbol.metadata], matter);
+  }
+  /**
+   * Access the {@link ClassSemantics} of {@link new} if it is defined.
+   */
+  static maybeOf(source) {
+    if (this.hasOwnSemantics(source)) {
+      return ClassSemantics.of(source);
+    }
+  }
+  static {
+    import_Semantics.Semantics.classOf = this.of;
+  }
+  finalize() {
+    if (this.isFinal) {
+      return;
+    }
+    this.#new?.[ClassSemantics.extend]?.(this);
+    super.finalize();
+    if (this.#definedFields) {
+      for (const field of this.#definedFields.values()) {
+        field.finalize();
+      }
+    }
+  }
+  #applyBaseSemantics() {
+    const base = this.prototypeBaseModel;
+    if (base === void 0) {
+      return;
+    }
+    const { type, base: currentBase } = this.mutableModel;
+    if (type === void 0 && (currentBase === void 0 || currentBase === import_models2.struct)) {
+      const operationalBase = this.prototypeBaseModel;
+      if (operationalBase) {
+        this.mutableModel.operationalBase = operationalBase;
+      }
+    }
+    if (base && base.tag !== "datatype" && this.mutableModel.tag !== base.tag) {
+      this.modelType = base.constructor;
+    }
+    if (this.mutableModel.id === void 0 && base.id !== void 0) {
+      this.mutableModel.id = base.id;
+    }
+  }
+  integrateModel(model) {
+    if (this.localModel === void 0 || this.localModel.isFinal) {
+      return model;
+    }
+    if (model.isFinal) {
+      this.localModel.operationalBase = model;
+      return this.localModel;
+    }
+    model.children.push(...this.localModel.children);
+    return model;
+  }
+  createModel(type = import_models.DatatypeModel) {
+    let name = this.#new?.name;
+    if (name === void 0 || name === "") {
+      name = "Unnamed";
+    }
+    return new type({ name, operationalBase: import_models2.struct });
+  }
+}
+((ClassSemantics2) => {
+  ClassSemantics2.extend = Symbol("extend");
+})(ClassSemantics || (ClassSemantics = {}));
+//# sourceMappingURL=ClassSemantics.js.map

package/dist/cjs/decoration/semantics/ClassSemantics.js.map

@@ -0,0 +1,6 @@
+{
+  "version": 3,
+  "sources": ["../../../../src/decoration/semantics/ClassSemantics.ts"],
+  "mappings": "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",
+  "names": ["import_models", "metadata", "ClassSemantics"]
+}

package/dist/cjs/decoration/semantics/FieldSemantics.d.ts

@@ -0,0 +1,21 @@
+/**
+ * @license
+ * Copyright 2022-2025 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { Model } from "#models/Model.js";
+import type { ClassSemantics } from "./ClassSemantics.js";
+import { Semantics } from "./Semantics.js";
+/**
+ * Decorator metadata associated with a specific class field.
+ */
+export declare class FieldSemantics extends Semantics {
+    constructor(owner: ClassSemantics, name: string);
+    protected createModel(): Model;
+    protected integrateModel(model: Model): Model;
+    static of(source: FieldSemantics.Source): FieldSemantics;
+}
+export declare namespace FieldSemantics {
+    type Source = DecoratorContext;
+}
+//# sourceMappingURL=FieldSemantics.d.ts.map

package/dist/cjs/decoration/semantics/FieldSemantics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"FieldSemantics.d.ts","sourceRoot":"","sources":["../../../../src/decoration/semantics/FieldSemantics.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAKH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAC1D,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAE3C;;GAEG;AACH,qBAAa,cAAe,SAAQ,SAAS;gBAC7B,KAAK,EAAE,cAAc,EAAE,IAAI,EAAE,MAAM;cAM5B,WAAW,IAAI,KAAK;cAKpB,cAAc,CAAC,KAAK,EAAE,KAAK,GAAG,KAAK;WAQtC,EAAE,CAAC,MAAM,EAAE,cAAc,CAAC,MAAM;CAQnD;AAED,yBAAiB,cAAc,CAAC;IAC5B,KAAY,MAAM,GAAG,gBAAgB,CAAC;CACzC"}

package/dist/cjs/decoration/semantics/FieldSemantics.js

@@ -0,0 +1,57 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var FieldSemantics_exports = {};
+__export(FieldSemantics_exports, {
+  FieldSemantics: () => FieldSemantics
+});
+module.exports = __toCommonJS(FieldSemantics_exports);
+var import_errors = require("#decoration/errors.js");
+var import_general = require("#general");
+var import_FieldModel = require("#models/FieldModel.js");
+var import_Semantics = require("./Semantics.js");
+/**
+ * @license
+ * Copyright 2022-2025 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+class FieldSemantics extends import_Semantics.Semantics {
+  constructor(owner, name) {
+    super();
+    this.mutableModel = new import_FieldModel.FieldModel({ name, parent: owner.mutableModel });
+  }
+  createModel() {
+    throw new import_general.InternalError("Unexpected FieldSemantics.createModel");
+  }
+  integrateModel(model) {
+    if (this.localModel === void 0) {
+      return model;
+    }
+    this.mutableModel.operationalBase = model;
+    return this.mutableModel;
+  }
+  static of(source) {
+    if (source.kind === "class") {
+      throw new import_errors.InvalidMetadataError(
+        `Cannot retrieve field semantics for class decorator ${source.name ?? "of anonymous class"}`
+      );
+    }
+    return import_Semantics.Semantics.classOf(source).fieldFor(source.name);
+  }
+}
+//# sourceMappingURL=FieldSemantics.js.map

package/dist/cjs/decoration/semantics/FieldSemantics.js.map

@@ -0,0 +1,6 @@
+{
+  "version": 3,
+  "sources": ["../../../../src/decoration/semantics/FieldSemantics.ts"],
+  "mappings": ";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAMA,oBAAqC;AACrC,qBAA8B;AAC9B,wBAA2B;AAG3B,uBAA0B;AAX1B;AAAA;AAAA;AAAA;AAAA;AAgBO,MAAM,uBAAuB,2BAAU;AAAA,EAC1C,YAAY,OAAuB,MAAc;AAC7C,UAAM;AAEN,SAAK,eAAe,IAAI,6BAAW,EAAE,MAAM,QAAQ,MAAM,aAAa,CAAC;AAAA,EAC3E;AAAA,EAEmB,cAAqB;AAEpC,UAAM,IAAI,6BAAc,uCAAuC;AAAA,EACnE;AAAA,EAEmB,eAAe,OAAqB;AACnD,QAAI,KAAK,eAAe,QAAW;AAC/B,aAAO;AAAA,IACX;AACA,SAAK,aAAa,kBAAkB;AACpC,WAAO,KAAK;AAAA,EAChB;AAAA,EAEA,OAAgB,GAAG,QAA+B;AAC9C,QAAI,OAAO,SAAS,SAAS;AACzB,YAAM,IAAI;AAAA,QACN,uDAAuD,OAAO,QAAQ,oBAAoB;AAAA,MAC9F;AAAA,IACJ;AACA,WAAO,2BAAU,QAAQ,MAAM,EAAE,SAAS,OAAO,IAAI;AAAA,EACzD;AACJ;",
+  "names": []
+}

package/dist/cjs/decoration/semantics/Semantics.d.ts

@@ -0,0 +1,68 @@
+/**
+ * @license
+ * Copyright 2022-2025 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { Model } from "#models/Model.js";
+import type { ClassSemantics } from "./ClassSemantics.js";
+/**
+ * Base class for Matter semantics associated with JavaScript classes and properties.
+ *
+ * We model semantics using {@link Model}.  The model may be built declaratively with decorators or programmatically
+ * using this interface directly.
+ */
+export declare abstract class Semantics {
+    #private;
+    /**
+     * Determine whether these semantics are final.
+     *
+     * Once final no further mutation is allowed.
+     */
+    get isFinal(): boolean;
+    /**
+     * Finalize the model.
+     */
+    finalize(): void;
+    /**
+     * The {@link Model} defined by local decoration, if any.
+     */
+    get localModel(): Model<import("../../index.js").BaseElement, Model<import("../../index.js").BaseElement, any>> | undefined;
+    /**
+     * Set the model.
+     *
+     * When "setting" the model we need to merge semantics coming from decorators, the prototype hierarchy, and models
+     * provided programmatically.
+     *
+     * This may set the local model, change it or set its operational base.  We use local state and the finalization
+     * status of the model to determine how to integrate.
+     */
+    set mutableModel(model: Model);
+    /**
+     * Replace the "base" of {@link localModel} and return an updated model.
+     */
+    protected abstract integrateModel(model: Model): Model;
+    /**
+     * Obtain a model unconditionally for mutation purposes.
+     */
+    get mutableModel(): Model;
+    /**
+     * The model's {@link Model.Type}.
+     *
+     * Field decorators operate prior to class decorators, so we may need to transition the model to a new type when the
+     * class is decorated.  This is slightly lossy so type-specific decoration should always occur after assigning kind.
+     */
+    get modelType(): Model.Type | undefined;
+    set modelType(type: Model.ConcreteType);
+    protected abstract createModel(type?: Model.ConcreteType): Model;
+}
+export declare namespace Semantics {
+    /**
+     * Access the {@link Semantics} of a {@link DecoratorContext}.
+     */
+    function of(context: DecoratorContext): import("./FieldSemantics.js").FieldSemantics | ClassSemantics;
+    /**
+     * Access the {@link ClassSemantics} of a constructor or decorator context.
+     */
+    let classOf: (_source: ClassSemantics.Source) => ClassSemantics;
+}
+//# sourceMappingURL=Semantics.d.ts.map

package/dist/cjs/decoration/semantics/Semantics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Semantics.d.ts","sourceRoot":"","sources":["../../../../src/decoration/semantics/Semantics.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAC;AAE9C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAI1D;;;;;GAKG;AACH,8BAAsB,SAAS;;IAI3B;;;;OAIG;IACH,IAAI,OAAO,IAAI,OAAO,CAErB;IAED;;OAEG;IACH,QAAQ;IAUR;;OAEG;IACH,IAAI,UAAU,8GAEb;IAED;;;;;;;;OAQG;IACH,IAAI,YAAY,CAAC,KAAK,EAAE,KAAK,EAgB5B;IAED;;OAEG;IACH,SAAS,CAAC,QAAQ,CAAC,cAAc,CAAC,KAAK,EAAE,KAAK,GAAG,KAAK;IAEtD;;OAEG;IACH,IAAI,YAAY,IA1BQ,KAAK,CAqC5B;IAED;;;;;OAKG;IACH,IAAI,SAAS,IAAI,KAAK,CAAC,IAAI,GAAG,SAAS,CAKtC;IAED,IAAI,SAAS,CAAC,IAAI,EAAE,KAAK,CAAC,YAAY,EA8BrC;IAED,SAAS,CAAC,QAAQ,CAAC,WAAW,CAAC,IAAI,CAAC,EAAE,KAAK,CAAC,YAAY,GAAG,KAAK;CACnE;AAED,yBAAiB,SAAS,CAAC;IACvB;;OAEG;IACH,SAAgB,EAAE,CAAC,OAAO,EAAE,gBAAgB,iEAM3C;IAED;;OAEG;IAEI,IAAI,OAAO,GAAI,SAAS,cAAc,CAAC,MAAM,KAAG,cAGtD,CAAC;CACL"}

package/dist/cjs/decoration/semantics/Semantics.js

@@ -0,0 +1,156 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var Semantics_exports = {};
+__export(Semantics_exports, {
+  Semantics: () => Semantics
+});
+module.exports = __toCommonJS(Semantics_exports);
+var import_errors = require("#decoration/errors.js");
+var import_general = require("#general");
+var models = __toESM(require("#standard/elements/models.js"), 1);
+/**
+ * @license
+ * Copyright 2022-2025 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+const standardModels = new Set(Object.values(models));
+class Semantics {
+  #localModel;
+  #isFinal = false;
+  /**
+   * Determine whether these semantics are final.
+   *
+   * Once final no further mutation is allowed.
+   */
+  get isFinal() {
+    return this.#isFinal;
+  }
+  /**
+   * Finalize the model.
+   */
+  finalize() {
+    if (this.#isFinal) {
+      return;
+    }
+    this.#isFinal = true;
+    Object.freeze(this);
+    this.#localModel?.finalize();
+  }
+  /**
+   * The {@link Model} defined by local decoration, if any.
+   */
+  get localModel() {
+    return this.#localModel;
+  }
+  /**
+   * Set the model.
+   *
+   * When "setting" the model we need to merge semantics coming from decorators, the prototype hierarchy, and models
+   * provided programmatically.
+   *
+   * This may set the local model, change it or set its operational base.  We use local state and the finalization
+   * status of the model to determine how to integrate.
+   */
+  set mutableModel(model) {
+    if (this.#isFinal) {
+      throw new import_errors.MetadataConflictError(`Cannot modify final semantics of ${this.#localModel?.name ?? "(none)"}`);
+    }
+    if (this.#localModel === model) {
+      return;
+    }
+    if (standardModels.has(model)) {
+      model.finalize();
+    }
+    this.#localModel = this.integrateModel(model);
+  }
+  /**
+   * Obtain a model unconditionally for mutation purposes.
+   */
+  get mutableModel() {
+    if (this.#isFinal) {
+      throw new import_errors.MetadataConflictError(`Cannot modify final semantics of ${this.#localModel?.name ?? "(none)"}`);
+    }
+    if (this.#localModel === void 0) {
+      this.#localModel = this.createModel();
+    } else if (this.#localModel.isFinal) {
+      this.#localModel = this.#localModel.extend();
+    }
+    return this.#localModel;
+  }
+  /**
+   * The model's {@link Model.Type}.
+   *
+   * Field decorators operate prior to class decorators, so we may need to transition the model to a new type when the
+   * class is decorated.  This is slightly lossy so type-specific decoration should always occur after assigning kind.
+   */
+  get modelType() {
+    if (this.#localModel === void 0) {
+      return;
+    }
+    return this.mutableModel.constructor;
+  }
+  set modelType(type) {
+    if (this.#localModel === void 0) {
+      this.#localModel = this.createModel(type);
+      return;
+    }
+    if (this.#localModel instanceof type) {
+      return;
+    }
+    const original = this.#localModel;
+    const { parent } = original;
+    original.parent = void 0;
+    const replacement = new type({
+      name: original.name,
+      id: original.id,
+      type: original.type,
+      parent,
+      operationalBase: original.operationalBase,
+      children: original.children
+    });
+    if ("quality" in original && "quality" in replacement) {
+      replacement.quality = original.quality;
+    }
+    this.#localModel = replacement;
+  }
+}
+((Semantics2) => {
+  function of(context) {
+    const classSemantics = (0, Semantics2.classOf)(context);
+    if (context.kind === "class") {
+      return classSemantics;
+    }
+    return classSemantics.fieldFor(context.name);
+  }
+  Semantics2.of = of;
+  Semantics2.classOf = (_source) => {
+    throw new import_general.InternalError(`Class decoration lookup not installed`);
+  };
+})(Semantics || (Semantics = {}));
+//# sourceMappingURL=Semantics.js.map

package/dist/cjs/decoration/semantics/Semantics.js.map

@@ -0,0 +1,6 @@
+{
+  "version": 3,
+  "sources": ["../../../../src/decoration/semantics/Semantics.ts"],
+  "mappings": ";;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAMA,oBAAsC;AACtC,qBAA8B;AAE9B,aAAwB;AATxB;AAAA;AAAA;AAAA;AAAA;AAYA,MAAM,iBAAiB,IAAI,IAAI,OAAO,OAAO,MAAM,CAAY;AAQxD,MAAe,UAAU;AAAA,EAC5B;AAAA,EACA,WAAW;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAOX,IAAI,UAAmB;AACnB,WAAO,KAAK;AAAA,EAChB;AAAA;AAAA;AAAA;AAAA,EAKA,WAAW;AACP,QAAI,KAAK,UAAU;AACf;AAAA,IACJ;AAEA,SAAK,WAAW;AAChB,WAAO,OAAO,IAAI;AAClB,SAAK,aAAa,SAAS;AAAA,EAC/B;AAAA;AAAA;AAAA;AAAA,EAKA,IAAI,aAAa;AACb,WAAO,KAAK;AAAA,EAChB;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAWA,IAAI,aAAa,OAAc;AAC3B,QAAI,KAAK,UAAU;AACf,YAAM,IAAI,oCAAsB,oCAAoC,KAAK,aAAa,QAAQ,QAAQ,EAAE;AAAA,IAC5G;AAEA,QAAI,KAAK,gBAAgB,OAAO;AAC5B;AAAA,IACJ;AAIA,QAAI,eAAe,IAAI,KAAK,GAAG;AAC3B,YAAM,SAAS;AAAA,IACnB;AAEA,SAAK,cAAc,KAAK,eAAe,KAAK;AAAA,EAChD;AAAA;AAAA;AAAA;AAAA,EAUA,IAAI,eAAe;AACf,QAAI,KAAK,UAAU;AACf,YAAM,IAAI,oCAAsB,oCAAoC,KAAK,aAAa,QAAQ,QAAQ,EAAE;AAAA,IAC5G;AAEA,QAAI,KAAK,gBAAgB,QAAW;AAChC,WAAK,cAAc,KAAK,YAAY;AAAA,IACxC,WAAW,KAAK,YAAY,SAAS;AACjC,WAAK,cAAc,KAAK,YAAY,OAAO;AAAA,IAC/C;AACA,WAAO,KAAK;AAAA,EAChB;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAQA,IAAI,YAAoC;AACpC,QAAI,KAAK,gBAAgB,QAAW;AAChC;AAAA,IACJ;AACA,WAAO,KAAK,aAAa;AAAA,EAC7B;AAAA,EAEA,IAAI,UAAU,MAA0B;AACpC,QAAI,KAAK,gBAAgB,QAAW;AAChC,WAAK,cAAc,KAAK,YAAY,IAAI;AACxC;AAAA,IACJ;AAEA,QAAI,KAAK,uBAAuB,MAAM;AAClC;AAAA,IACJ;AAGA,UAAM,WAAW,KAAK;AACtB,UAAM,EAAE,OAAO,IAAI;AACnB,aAAS,SAAS;AAGlB,UAAM,cAAc,IAAI,KAAK;AAAA,MACzB,MAAM,SAAS;AAAA,MACf,IAAI,SAAS;AAAA,MACb,MAAM,SAAS;AAAA,MACf;AAAA,MACA,iBAAiB,SAAS;AAAA,MAC1B,UAAU,SAAS;AAAA,IACvB,CAAC;AAED,QAAI,aAAa,YAAY,aAAa,aAAa;AACnD,kBAAY,UAAU,SAAS;AAAA,IACnC;AAEA,SAAK,cAAc;AAAA,EACvB;AAGJ;AAAA,CAEO,CAAUA,eAAV;AAII,WAAS,GAAG,SAA2B;AAC1C,UAAM,qBAAiBA,WAAA,SAAQ,OAAO;AACtC,QAAI,QAAQ,SAAS,SAAS;AAC1B,aAAO;AAAA,IACX;AACA,WAAO,eAAe,SAAS,QAAQ,IAAI;AAAA,EAC/C;AANO,EAAAA,WAAS;AAYT,EAAIA,WAAA,UAAU,CAAC,YAAmD;AAErE,UAAM,IAAI,6BAAc,uCAAuC;AAAA,EACnE;AAAA,GAnBa;",
+  "names": ["Semantics"]
+}

package/dist/cjs/decoration/semantics/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * @license
+ * Copyright 2022-2025 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+export * from "./ClassSemantics.js";
+export * from "./FieldSemantics.js";
+export * from "./Semantics.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/cjs/decoration/semantics/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/decoration/semantics/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,cAAc,qBAAqB,CAAC;AACpC,cAAc,qBAAqB,CAAC;AACpC,cAAc,gBAAgB,CAAC"}

package/dist/cjs/decoration/semantics/index.js

@@ -0,0 +1,26 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __reExport = (target, mod, secondTarget) => (__copyProps(target, mod, "default"), secondTarget && __copyProps(secondTarget, mod, "default"));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var semantics_exports = {};
+module.exports = __toCommonJS(semantics_exports);
+__reExport(semantics_exports, require("./ClassSemantics.js"), module.exports);
+__reExport(semantics_exports, require("./FieldSemantics.js"), module.exports);
+__reExport(semantics_exports, require("./Semantics.js"), module.exports);
+/**
+ * @license
+ * Copyright 2022-2025 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+//# sourceMappingURL=index.js.map

package/dist/cjs/decoration/semantics/index.js.map

@@ -0,0 +1,6 @@
+{
+  "version": 3,
+  "sources": ["../../../../src/decoration/semantics/index.ts"],
+  "mappings": ";;;;;;;;;;;;;;;AAAA;AAAA;AAMA,8BAAc,gCANd;AAOA,8BAAc,gCAPd;AAQA,8BAAc,2BARd;AAAA;AAAA;AAAA;AAAA;AAAA;",
+  "names": []
+}

package/dist/cjs/index.d.ts

@@ -5,6 +5,7 @@
  */
 export * from "./aspects/index.js";
 export * from "./common/index.js";
+export * from "./decoration/index.js";
 export * from "./elements/index.js";
 export * from "./logic/index.js";
 export * from "./Matter.js";

package/dist/cjs/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,cAAc,oBAAoB,CAAC;AACnC,cAAc,mBAAmB,CAAC;AAClC,cAAc,qBAAqB,CAAC;AACpC,cAAc,kBAAkB,CAAC;AACjC,cAAc,aAAa,CAAC;AAC5B,cAAc,mBAAmB,CAAC;AAClC,cAAc,mBAAmB,CAAC;AAClC,cAAc,+BAA+B,CAAC;AAC9C,cAAc,qBAAqB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,cAAc,oBAAoB,CAAC;AACnC,cAAc,mBAAmB,CAAC;AAClC,cAAc,uBAAuB,CAAC;AACtC,cAAc,qBAAqB,CAAC;AACpC,cAAc,kBAAkB,CAAC;AACjC,cAAc,aAAa,CAAC;AAC5B,cAAc,mBAAmB,CAAC;AAClC,cAAc,mBAAmB,CAAC;AAClC,cAAc,+BAA+B,CAAC;AAC9C,cAAc,qBAAqB,CAAC"}