@matter/general 0.16.0-alpha.0-20250912-0d12bf718 → 0.16.0-alpha.0-20250916-d577beb1d

package/dist/cjs/environment/Environmental.d.ts

@@ -28,14 +28,19 @@ export declare namespace Environmental {
         [Diagnostic.value]?: unknown;
     }
     /**
-     * A factory for a {@link Service}.  Any constructor may be a service factory.
+     * A factory for a {@link Service}.
+     *
+     * A "factory" is just a class with a static {@link create} method that performs instantiation.
      */
-    interface Factory<T extends Service> {
+    interface Factory<T extends Service = Service> {
         new (...args: any[]): T;
         /**
-         * The environment will create the service automatically if the factory supports {@link create}.
+         * Method the environment uses to instantiate the service.
+         *
+         * We use this rather than invoking the constructor directly so the service can perform configuration via
+         * {@link Environment} regardless of the arguments its constructor takes.
          */
-        [create]?: (environment: Environment) => T;
+        [create]: (environment: Environment) => T;
     }
     /**
      * Events related to service lifecycle.

package/dist/cjs/environment/Environmental.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Environmental.d.ts","sourceRoot":"","sources":["../../../src/environment/Environmental.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAClD,OAAO,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AACnD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAEpD,yBAAiB,aAAa,CAAC;IACpB,MAAM,MAAM,eAAmB,CAAC;IAEvC;;;;OAIG;IACH,UAAiB,OAAO;QACpB;;WAEG;QACH,YAAY,CAAC,EAAE,OAAO,CAAC,GAAG,CAAC,CAAC;QAE5B;;WAEG;QACH,CAAC,UAAU,CAAC,YAAY,CAAC,CAAC,EAAE,UAAU,CAAC,YAAY,CAAC;QAEpD;;WAEG;QACH,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC,EAAE,OAAO,CAAC;KAChC;IAED;;OAEG;IACH,UAAiB,OAAO,CAAC,CAAC,SAAS,OAAO;QACtC,KAAK,GAAG,IAAI,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC;QAExB;;WAEG;QACH,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,WAAW,EAAE,WAAW,KAAK,CAAC,CAAC;KAC9C;IAED;;OAEG;IACH,UAAiB,aAAa,CAAC,CAAC,SAAS,QAAQ,MAAM,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,CAAC;QACvE,KAAK,EAAE,UAAU,CAAC,CAAC,QAAQ,EAAE,YAAY,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QAC/C,OAAO,EAAE,UAAU,CAAC,CAAC,QAAQ,EAAE,YAAY,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;KACpD;CACJ"}
+{"version":3,"file":"Environmental.d.ts","sourceRoot":"","sources":["../../../src/environment/Environmental.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAClD,OAAO,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AACnD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAEpD,yBAAiB,aAAa,CAAC;IACpB,MAAM,MAAM,eAAmB,CAAC;IAEvC;;;;OAIG;IACH,UAAiB,OAAO;QACpB;;WAEG;QACH,YAAY,CAAC,EAAE,OAAO,CAAC,GAAG,CAAC,CAAC;QAE5B;;WAEG;QACH,CAAC,UAAU,CAAC,YAAY,CAAC,CAAC,EAAE,UAAU,CAAC,YAAY,CAAC;QAEpD;;WAEG;QACH,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC,EAAE,OAAO,CAAC;KAChC;IAED;;;;OAIG;IACH,UAAiB,OAAO,CAAC,CAAC,SAAS,OAAO,GAAG,OAAO;QAChD,KAAK,GAAG,IAAI,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC;QAExB;;;;;WAKG;QACH,CAAC,MAAM,CAAC,EAAE,CAAC,WAAW,EAAE,WAAW,KAAK,CAAC,CAAC;KAC7C;IAED;;OAEG;IACH,UAAiB,aAAa,CAAC,CAAC,SAAS,QAAQ,MAAM,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,CAAC;QACvE,KAAK,EAAE,UAAU,CAAC,CAAC,QAAQ,EAAE,YAAY,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QAC/C,OAAO,EAAE,UAAU,CAAC,CAAC,QAAQ,EAAE,YAAY,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;KACpD;CACJ"}

package/dist/cjs/environment/ServiceBundle.d.ts

@@ -0,0 +1,37 @@
+/**
+ * @license
+ * Copyright 2022-2025 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { BasicSet } from "#util/Set.js";
+import { Environment } from "./Environment.js";
+/**
+ * A bundle of services that may be added to an {@link Environment} as a unit.
+ *
+ * This serves as an extension mechanism for matter.js.  Plugins may register for deployment into environments by adding
+ * a factory to {@link default}.
+ */
+export declare class ServiceBundle extends BasicSet<ServiceBundle.Factory> {
+    #private;
+    constructor();
+    /**
+     * A default bundle for services that should generally deploy in all environments.
+     */
+    static get default(): ServiceBundle;
+    /**
+     * Install the bundle into an {@link Environment}.
+     *
+     * This installs any services that currently comprise the bundle and will install any services added in the future
+     * as well.
+     */
+    deploy(env: Environment): void;
+}
+export declare namespace ServiceBundle {
+    /**
+     * A factory function invoked when a bundle is deployed.
+     */
+    interface Factory {
+        (env: Environment): void;
+    }
+}
+//# sourceMappingURL=ServiceBundle.d.ts.map

package/dist/cjs/environment/ServiceBundle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ServiceBundle.d.ts","sourceRoot":"","sources":["../../../src/environment/ServiceBundle.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AACxC,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAI/C;;;;;GAKG;AACH,qBAAa,aAAc,SAAQ,QAAQ,CAAC,aAAa,CAAC,OAAO,CAAC;;;IAmC9D;;OAEG;IACH,MAAM,KAAK,OAAO,kBAEjB;IAED;;;;;OAKG;IACH,MAAM,CAAC,GAAG,EAAE,WAAW;CAkB1B;AAED,yBAAiB,aAAa,CAAC;IAC3B;;OAEG;IACH,UAAiB,OAAO;QACpB,CAAC,GAAG,EAAE,WAAW,GAAG,IAAI,CAAC;KAC5B;CACJ"}

package/dist/cjs/environment/ServiceBundle.js

@@ -0,0 +1,89 @@
+"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 ServiceBundle_exports = {};
+__export(ServiceBundle_exports, {
+  ServiceBundle: () => ServiceBundle
+});
+module.exports = __toCommonJS(ServiceBundle_exports);
+var import_Logger = require("#log/Logger.js");
+var import_Set = require("#util/Set.js");
+/**
+ * @license
+ * Copyright 2022-2025 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+const logger = new import_Logger.Logger("ServiceBundle");
+class ServiceBundle extends import_Set.BasicSet {
+  static #default = new ServiceBundle();
+  #factories = /* @__PURE__ */ new Set();
+  #environments = /* @__PURE__ */ new Set();
+  constructor() {
+    super();
+    this.added.on((factory) => {
+      let toRemove;
+      for (const ref of this.#environments) {
+        const env = ref.deref();
+        if (env) {
+          this.#deployFactory(factory, env);
+        }
+        if (env === void 0) {
+          if (toRemove === void 0) {
+            toRemove = /* @__PURE__ */ new Set();
+          }
+          toRemove.add(ref);
+        }
+      }
+      if (toRemove) {
+        for (const expiredRef of toRemove) {
+          this.#environments.delete(expiredRef);
+        }
+      }
+    });
+  }
+  /**
+   * A default bundle for services that should generally deploy in all environments.
+   */
+  static get default() {
+    return this.#default;
+  }
+  /**
+   * Install the bundle into an {@link Environment}.
+   *
+   * This installs any services that currently comprise the bundle and will install any services added in the future
+   * as well.
+   */
+  deploy(env) {
+    for (const factory of this.#factories) {
+      this.#deployFactory(factory, env);
+    }
+    this.#environments.add(new WeakRef(env));
+  }
+  #deployFactory(factory, env) {
+    try {
+      factory(env);
+    } catch (e) {
+      let name = "factory";
+      if (factory.name) {
+        name = `${name} ${factory.name}`;
+      }
+      logger.error(`Error deploying services for ${name}:`, e);
+    }
+  }
+}
+//# sourceMappingURL=ServiceBundle.js.map

package/dist/cjs/environment/ServiceBundle.js.map

@@ -0,0 +1,6 @@
+{
+  "version": 3,
+  "sources": ["../../../src/environment/ServiceBundle.ts"],
+  "mappings": ";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAMA,oBAAuB;AACvB,iBAAyB;AAPzB;AAAA;AAAA;AAAA;AAAA;AAUA,MAAM,SAAS,IAAI,qBAAO,eAAe;AAQlC,MAAM,sBAAsB,oBAAgC;AAAA,EAC/D,OAAO,WAAW,IAAI,cAAc;AAAA,EACpC,aAAa,oBAAI,IAAgC;AAAA,EACjD,gBAAgB,oBAAI,IAA0B;AAAA,EAE9C,cAAc;AACV,UAAM;AAEN,SAAK,MAAM,GAAG,aAAW;AACrB,UAAI;AAEJ,iBAAW,OAAO,KAAK,eAAe;AAClC,cAAM,MAAM,IAAI,MAAM;AAEtB,YAAI,KAAK;AACL,eAAK,eAAe,SAAS,GAAG;AAAA,QACpC;AAGA,YAAI,QAAQ,QAAW;AACnB,cAAI,aAAa,QAAW;AACxB,uBAAW,oBAAI,IAAI;AAAA,UACvB;AACA,mBAAS,IAAI,GAAG;AAAA,QACpB;AAAA,MACJ;AAEA,UAAI,UAAU;AACV,mBAAW,cAAc,UAAU;AAC/B,eAAK,cAAc,OAAO,UAAU;AAAA,QACxC;AAAA,MACJ;AAAA,IACJ,CAAC;AAAA,EACL;AAAA;AAAA;AAAA;AAAA,EAKA,WAAW,UAAU;AACjB,WAAO,KAAK;AAAA,EAChB;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAQA,OAAO,KAAkB;AACrB,eAAW,WAAW,KAAK,YAAY;AACnC,WAAK,eAAe,SAAS,GAAG;AAAA,IACpC;AACA,SAAK,cAAc,IAAI,IAAI,QAAQ,GAAG,CAAC;AAAA,EAC3C;AAAA,EAEA,eAAe,SAAgC,KAAkB;AAC7D,QAAI;AACA,cAAQ,GAAG;AAAA,IACf,SAAS,GAAG;AACR,UAAI,OAAO;AACX,UAAI,QAAQ,MAAM;AACd,eAAO,GAAG,IAAI,IAAI,QAAQ,IAAI;AAAA,MAClC;AACA,aAAO,MAAM,gCAAgC,IAAI,KAAK,CAAC;AAAA,IAC3D;AAAA,EACJ;AACJ;",
+  "names": []
+}

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

@@ -6,5 +6,6 @@
 export * from "./Environment.js";
 export * from "./Environmental.js";
 export * from "./RuntimeService.js";
+export * from "./ServiceBundle.js";
 export * from "./VariableService.js";
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/environment/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,cAAc,kBAAkB,CAAC;AACjC,cAAc,oBAAoB,CAAC;AACnC,cAAc,qBAAqB,CAAC;AACpC,cAAc,sBAAsB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/environment/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,cAAc,kBAAkB,CAAC;AACjC,cAAc,oBAAoB,CAAC;AACnC,cAAc,qBAAqB,CAAC;AACpC,cAAc,oBAAoB,CAAC;AACnC,cAAc,sBAAsB,CAAC"}

package/dist/cjs/environment/index.js

@@ -18,6 +18,7 @@ module.exports = __toCommonJS(environment_exports);
 __reExport(environment_exports, require("./Environment.js"), module.exports);
 __reExport(environment_exports, require("./Environmental.js"), module.exports);
 __reExport(environment_exports, require("./RuntimeService.js"), module.exports);
+__reExport(environment_exports, require("./ServiceBundle.js"), module.exports);
 __reExport(environment_exports, require("./VariableService.js"), module.exports);
 /**
  * @license

package/dist/cjs/environment/index.js.map

@@ -1,6 +1,6 @@
 {
   "version": 3,
   "sources": ["../../../src/environment/index.ts"],
-  "mappings": ";;;;;;;;;;;;;;;AAAA;AAAA;AAMA,gCAAc,6BANd;AAOA,gCAAc,+BAPd;AAQA,gCAAc,gCARd;AASA,gCAAc,iCATd;AAAA;AAAA;AAAA;AAAA;AAAA;",
+  "mappings": ";;;;;;;;;;;;;;;AAAA;AAAA;AAMA,gCAAc,6BANd;AAOA,gCAAc,+BAPd;AAQA,gCAAc,gCARd;AASA,gCAAc,+BATd;AAUA,gCAAc,iCAVd;AAAA;AAAA;AAAA;AAAA;AAAA;",
   "names": []
 }

package/dist/esm/environment/Environmental.d.ts

@@ -28,14 +28,19 @@ export declare namespace Environmental {
         [Diagnostic.value]?: unknown;
     }
     /**
-     * A factory for a {@link Service}.  Any constructor may be a service factory.
+     * A factory for a {@link Service}.
+     *
+     * A "factory" is just a class with a static {@link create} method that performs instantiation.
      */
-    interface Factory<T extends Service> {
+    interface Factory<T extends Service = Service> {
         new (...args: any[]): T;
         /**
-         * The environment will create the service automatically if the factory supports {@link create}.
+         * Method the environment uses to instantiate the service.
+         *
+         * We use this rather than invoking the constructor directly so the service can perform configuration via
+         * {@link Environment} regardless of the arguments its constructor takes.
          */
-        [create]?: (environment: Environment) => T;
+        [create]: (environment: Environment) => T;
     }
     /**
      * Events related to service lifecycle.

package/dist/esm/environment/Environmental.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Environmental.d.ts","sourceRoot":"","sources":["../../../src/environment/Environmental.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAClD,OAAO,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AACnD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAEpD,yBAAiB,aAAa,CAAC;IACpB,MAAM,MAAM,eAAmB,CAAC;IAEvC;;;;OAIG;IACH,UAAiB,OAAO;QACpB;;WAEG;QACH,YAAY,CAAC,EAAE,OAAO,CAAC,GAAG,CAAC,CAAC;QAE5B;;WAEG;QACH,CAAC,UAAU,CAAC,YAAY,CAAC,CAAC,EAAE,UAAU,CAAC,YAAY,CAAC;QAEpD;;WAEG;QACH,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC,EAAE,OAAO,CAAC;KAChC;IAED;;OAEG;IACH,UAAiB,OAAO,CAAC,CAAC,SAAS,OAAO;QACtC,KAAK,GAAG,IAAI,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC;QAExB;;WAEG;QACH,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,WAAW,EAAE,WAAW,KAAK,CAAC,CAAC;KAC9C;IAED;;OAEG;IACH,UAAiB,aAAa,CAAC,CAAC,SAAS,QAAQ,MAAM,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,CAAC;QACvE,KAAK,EAAE,UAAU,CAAC,CAAC,QAAQ,EAAE,YAAY,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QAC/C,OAAO,EAAE,UAAU,CAAC,CAAC,QAAQ,EAAE,YAAY,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;KACpD;CACJ"}
+{"version":3,"file":"Environmental.d.ts","sourceRoot":"","sources":["../../../src/environment/Environmental.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAClD,OAAO,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AACnD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAEpD,yBAAiB,aAAa,CAAC;IACpB,MAAM,MAAM,eAAmB,CAAC;IAEvC;;;;OAIG;IACH,UAAiB,OAAO;QACpB;;WAEG;QACH,YAAY,CAAC,EAAE,OAAO,CAAC,GAAG,CAAC,CAAC;QAE5B;;WAEG;QACH,CAAC,UAAU,CAAC,YAAY,CAAC,CAAC,EAAE,UAAU,CAAC,YAAY,CAAC;QAEpD;;WAEG;QACH,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC,EAAE,OAAO,CAAC;KAChC;IAED;;;;OAIG;IACH,UAAiB,OAAO,CAAC,CAAC,SAAS,OAAO,GAAG,OAAO;QAChD,KAAK,GAAG,IAAI,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC;QAExB;;;;;WAKG;QACH,CAAC,MAAM,CAAC,EAAE,CAAC,WAAW,EAAE,WAAW,KAAK,CAAC,CAAC;KAC7C;IAED;;OAEG;IACH,UAAiB,aAAa,CAAC,CAAC,SAAS,QAAQ,MAAM,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,CAAC;QACvE,KAAK,EAAE,UAAU,CAAC,CAAC,QAAQ,EAAE,YAAY,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QAC/C,OAAO,EAAE,UAAU,CAAC,CAAC,QAAQ,EAAE,YAAY,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;KACpD;CACJ"}

package/dist/esm/environment/ServiceBundle.d.ts

@@ -0,0 +1,37 @@
+/**
+ * @license
+ * Copyright 2022-2025 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { BasicSet } from "#util/Set.js";
+import { Environment } from "./Environment.js";
+/**
+ * A bundle of services that may be added to an {@link Environment} as a unit.
+ *
+ * This serves as an extension mechanism for matter.js.  Plugins may register for deployment into environments by adding
+ * a factory to {@link default}.
+ */
+export declare class ServiceBundle extends BasicSet<ServiceBundle.Factory> {
+    #private;
+    constructor();
+    /**
+     * A default bundle for services that should generally deploy in all environments.
+     */
+    static get default(): ServiceBundle;
+    /**
+     * Install the bundle into an {@link Environment}.
+     *
+     * This installs any services that currently comprise the bundle and will install any services added in the future
+     * as well.
+     */
+    deploy(env: Environment): void;
+}
+export declare namespace ServiceBundle {
+    /**
+     * A factory function invoked when a bundle is deployed.
+     */
+    interface Factory {
+        (env: Environment): void;
+    }
+}
+//# sourceMappingURL=ServiceBundle.d.ts.map

package/dist/esm/environment/ServiceBundle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ServiceBundle.d.ts","sourceRoot":"","sources":["../../../src/environment/ServiceBundle.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AACxC,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAI/C;;;;;GAKG;AACH,qBAAa,aAAc,SAAQ,QAAQ,CAAC,aAAa,CAAC,OAAO,CAAC;;;IAmC9D;;OAEG;IACH,MAAM,KAAK,OAAO,kBAEjB;IAED;;;;;OAKG;IACH,MAAM,CAAC,GAAG,EAAE,WAAW;CAkB1B;AAED,yBAAiB,aAAa,CAAC;IAC3B;;OAEG;IACH,UAAiB,OAAO;QACpB,CAAC,GAAG,EAAE,WAAW,GAAG,IAAI,CAAC;KAC5B;CACJ"}

package/dist/esm/environment/ServiceBundle.js

@@ -0,0 +1,69 @@
+/**
+ * @license
+ * Copyright 2022-2025 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { Logger } from "#log/Logger.js";
+import { BasicSet } from "#util/Set.js";
+const logger = new Logger("ServiceBundle");
+class ServiceBundle extends BasicSet {
+  static #default = new ServiceBundle();
+  #factories = /* @__PURE__ */ new Set();
+  #environments = /* @__PURE__ */ new Set();
+  constructor() {
+    super();
+    this.added.on((factory) => {
+      let toRemove;
+      for (const ref of this.#environments) {
+        const env = ref.deref();
+        if (env) {
+          this.#deployFactory(factory, env);
+        }
+        if (env === void 0) {
+          if (toRemove === void 0) {
+            toRemove = /* @__PURE__ */ new Set();
+          }
+          toRemove.add(ref);
+        }
+      }
+      if (toRemove) {
+        for (const expiredRef of toRemove) {
+          this.#environments.delete(expiredRef);
+        }
+      }
+    });
+  }
+  /**
+   * A default bundle for services that should generally deploy in all environments.
+   */
+  static get default() {
+    return this.#default;
+  }
+  /**
+   * Install the bundle into an {@link Environment}.
+   *
+   * This installs any services that currently comprise the bundle and will install any services added in the future
+   * as well.
+   */
+  deploy(env) {
+    for (const factory of this.#factories) {
+      this.#deployFactory(factory, env);
+    }
+    this.#environments.add(new WeakRef(env));
+  }
+  #deployFactory(factory, env) {
+    try {
+      factory(env);
+    } catch (e) {
+      let name = "factory";
+      if (factory.name) {
+        name = `${name} ${factory.name}`;
+      }
+      logger.error(`Error deploying services for ${name}:`, e);
+    }
+  }
+}
+export {
+  ServiceBundle
+};
+//# sourceMappingURL=ServiceBundle.js.map

package/dist/esm/environment/ServiceBundle.js.map

@@ -0,0 +1,6 @@
+{
+  "version": 3,
+  "sources": ["../../../src/environment/ServiceBundle.ts"],
+  "mappings": "AAAA;AAAA;AAAA;AAAA;AAAA;AAMA,SAAS,cAAc;AACvB,SAAS,gBAAgB;AAGzB,MAAM,SAAS,IAAI,OAAO,eAAe;AAQlC,MAAM,sBAAsB,SAAgC;AAAA,EAC/D,OAAO,WAAW,IAAI,cAAc;AAAA,EACpC,aAAa,oBAAI,IAAgC;AAAA,EACjD,gBAAgB,oBAAI,IAA0B;AAAA,EAE9C,cAAc;AACV,UAAM;AAEN,SAAK,MAAM,GAAG,aAAW;AACrB,UAAI;AAEJ,iBAAW,OAAO,KAAK,eAAe;AAClC,cAAM,MAAM,IAAI,MAAM;AAEtB,YAAI,KAAK;AACL,eAAK,eAAe,SAAS,GAAG;AAAA,QACpC;AAGA,YAAI,QAAQ,QAAW;AACnB,cAAI,aAAa,QAAW;AACxB,uBAAW,oBAAI,IAAI;AAAA,UACvB;AACA,mBAAS,IAAI,GAAG;AAAA,QACpB;AAAA,MACJ;AAEA,UAAI,UAAU;AACV,mBAAW,cAAc,UAAU;AAC/B,eAAK,cAAc,OAAO,UAAU;AAAA,QACxC;AAAA,MACJ;AAAA,IACJ,CAAC;AAAA,EACL;AAAA;AAAA;AAAA;AAAA,EAKA,WAAW,UAAU;AACjB,WAAO,KAAK;AAAA,EAChB;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAQA,OAAO,KAAkB;AACrB,eAAW,WAAW,KAAK,YAAY;AACnC,WAAK,eAAe,SAAS,GAAG;AAAA,IACpC;AACA,SAAK,cAAc,IAAI,IAAI,QAAQ,GAAG,CAAC;AAAA,EAC3C;AAAA,EAEA,eAAe,SAAgC,KAAkB;AAC7D,QAAI;AACA,cAAQ,GAAG;AAAA,IACf,SAAS,GAAG;AACR,UAAI,OAAO;AACX,UAAI,QAAQ,MAAM;AACd,eAAO,GAAG,IAAI,IAAI,QAAQ,IAAI;AAAA,MAClC;AACA,aAAO,MAAM,gCAAgC,IAAI,KAAK,CAAC;AAAA,IAC3D;AAAA,EACJ;AACJ;",
+  "names": []
+}

package/dist/esm/environment/index.d.ts

@@ -6,5 +6,6 @@
 export * from "./Environment.js";
 export * from "./Environmental.js";
 export * from "./RuntimeService.js";
+export * from "./ServiceBundle.js";
 export * from "./VariableService.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/esm/environment/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/environment/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,cAAc,kBAAkB,CAAC;AACjC,cAAc,oBAAoB,CAAC;AACnC,cAAc,qBAAqB,CAAC;AACpC,cAAc,sBAAsB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/environment/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,cAAc,kBAAkB,CAAC;AACjC,cAAc,oBAAoB,CAAC;AACnC,cAAc,qBAAqB,CAAC;AACpC,cAAc,oBAAoB,CAAC;AACnC,cAAc,sBAAsB,CAAC"}

package/dist/esm/environment/index.js

@@ -6,5 +6,6 @@
 export * from "./Environment.js";
 export * from "./Environmental.js";
 export * from "./RuntimeService.js";
+export * from "./ServiceBundle.js";
 export * from "./VariableService.js";
 //# sourceMappingURL=index.js.map

package/dist/esm/environment/index.js.map

@@ -1,6 +1,6 @@
 {
   "version": 3,
   "sources": ["../../../src/environment/index.ts"],
-  "mappings": "AAAA;AAAA;AAAA;AAAA;AAAA;AAMA,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;",
+  "mappings": "AAAA;AAAA;AAAA;AAAA;AAAA;AAMA,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;",
   "names": []
 }

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@matter/general",
-    "version": "0.16.0-alpha.0-20250912-0d12bf718",
+    "version": "0.16.0-alpha.0-20250916-d577beb1d",
     "description": "Non-Matter support for Matter.js",
     "keywords": [
         "iot",
@@ -36,7 +36,7 @@
         "@noble/curves": "^2.0.0"
     },
     "devDependencies": {
-        "@matter/testing": "0.16.0-alpha.0-20250912-0d12bf718"
+        "@matter/testing": "0.16.0-alpha.0-20250916-d577beb1d"
     },
     "files": [
         "dist/**/*",

package/src/environment/Environmental.ts

@@ -34,15 +34,20 @@ export namespace Environmental {
     }
 
     /**
-     * A factory for a {@link Service}.  Any constructor may be a service factory.
+     * A factory for a {@link Service}.
+     *
+     * A "factory" is just a class with a static {@link create} method that performs instantiation.
      */
-    export interface Factory<T extends Service> {
+    export interface Factory<T extends Service = Service> {
         new (...args: any[]): T;
 
         /**
-         * The environment will create the service automatically if the factory supports {@link create}.
+         * Method the environment uses to instantiate the service.
+         *
+         * We use this rather than invoking the constructor directly so the service can perform configuration via
+         * {@link Environment} regardless of the arguments its constructor takes.
          */
-        [create]?: (environment: Environment) => T;
+        [create]: (environment: Environment) => T;
     }
 
     /**

package/src/environment/ServiceBundle.ts

@@ -0,0 +1,94 @@
+/**
+ * @license
+ * Copyright 2022-2025 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { Logger } from "#log/Logger.js";
+import { BasicSet } from "#util/Set.js";
+import { Environment } from "./Environment.js";
+
+const logger = new Logger("ServiceBundle");
+
+/**
+ * A bundle of services that may be added to an {@link Environment} as a unit.
+ *
+ * This serves as an extension mechanism for matter.js.  Plugins may register for deployment into environments by adding
+ * a factory to {@link default}.
+ */
+export class ServiceBundle extends BasicSet<ServiceBundle.Factory> {
+    static #default = new ServiceBundle();
+    #factories = new Set<(env: Environment) => void>();
+    #environments = new Set<WeakRef<Environment>>();
+
+    constructor() {
+        super();
+
+        this.added.on(factory => {
+            let toRemove: undefined | Set<WeakRef<Environment>>;
+
+            for (const ref of this.#environments) {
+                const env = ref.deref();
+
+                if (env) {
+                    this.#deployFactory(factory, env);
+                }
+
+                // Clean up expired ref
+                if (env === undefined) {
+                    if (toRemove === undefined) {
+                        toRemove = new Set();
+                    }
+                    toRemove.add(ref);
+                }
+            }
+
+            if (toRemove) {
+                for (const expiredRef of toRemove) {
+                    this.#environments.delete(expiredRef);
+                }
+            }
+        });
+    }
+
+    /**
+     * A default bundle for services that should generally deploy in all environments.
+     */
+    static get default() {
+        return this.#default;
+    }
+
+    /**
+     * Install the bundle into an {@link Environment}.
+     *
+     * This installs any services that currently comprise the bundle and will install any services added in the future
+     * as well.
+     */
+    deploy(env: Environment) {
+        for (const factory of this.#factories) {
+            this.#deployFactory(factory, env);
+        }
+        this.#environments.add(new WeakRef(env));
+    }
+
+    #deployFactory(factory: ServiceBundle.Factory, env: Environment) {
+        try {
+            factory(env);
+        } catch (e) {
+            let name = "factory";
+            if (factory.name) {
+                name = `${name} ${factory.name}`;
+            }
+            logger.error(`Error deploying services for ${name}:`, e);
+        }
+    }
+}
+
+export namespace ServiceBundle {
+    /**
+     * A factory function invoked when a bundle is deployed.
+     */
+    export interface Factory {
+        (env: Environment): void;
+    }
+}

package/src/environment/index.ts

@@ -7,4 +7,5 @@
 export * from "./Environment.js";
 export * from "./Environmental.js";
 export * from "./RuntimeService.js";
+export * from "./ServiceBundle.js";
 export * from "./VariableService.js";