@wirestate/lit 0.7.0-experimental.1 → 0.7.0-experimental.3

package/cjs/development/index.js

@@ -2,20 +2,19 @@
 
 var context = require('@lit/context');
 var core = require('@wirestate/core');
-var tslib = require('tslib');
 
 /**
  * Unique symbol used as a key for the IoC context.
  *
  * @group Context
  */
-var IOC_CONTAINER_KEY = Symbol("ContainerContext");
+const CONTAINER_KEY = Symbol("ContainerContext");
 /**
- * Lit context object for providing and consuming the IoC container.
+ * Lit context object for providing and consuming the container.
  *
  * @group Context
  */
-var IocContextObject = context.createContext(IOC_CONTAINER_KEY);
+const ContainerContext = context.createContext(CONTAINER_KEY);
 
 /**
  * Decorator to inject a service from the IoC container into a Lit element property.
@@ -50,31 +49,32 @@ var IocContextObject = context.createContext(IOC_CONTAINER_KEY);
  * ```
  */
 function injection(optionsOrInjectionId) {
-  var options = typeof optionsOrInjectionId === "object" && optionsOrInjectionId !== null && "injectionId" in optionsOrInjectionId ? optionsOrInjectionId : {
+  const options = typeof optionsOrInjectionId === "object" && optionsOrInjectionId !== null && "injectionId" in optionsOrInjectionId ? optionsOrInjectionId : {
     injectionId: optionsOrInjectionId
   };
-  return function (protoOrTarget, nameOrContext) {
-    var injectionId = options.injectionId,
-      once = options.once;
+  return (protoOrTarget, nameOrContext) => {
+    const {
+      injectionId,
+      once
+    } = options;
     // Standard decorators branch.
     if (typeof nameOrContext === "object") {
       nameOrContext.addInitializer(function () {
-        var _this = this;
         new context.ContextConsumer(this, {
-          context: IocContextObject,
-          callback: function (it) {
-            protoOrTarget.set.call(_this, it.container.get(injectionId));
+          context: ContainerContext,
+          callback: container => {
+            protoOrTarget.set.call(this, container.get(injectionId));
           },
           subscribe: !once
         });
       });
     } else {
       // Experimental decorators branch.
-      protoOrTarget.constructor.addInitializer(function (element) {
+      protoOrTarget.constructor.addInitializer(element => {
         new context.ContextConsumer(element, {
-          context: IocContextObject,
-          callback: function (it) {
-            element[nameOrContext] = it.container.get(injectionId);
+          context: ContainerContext,
+          callback: container => {
+            element[nameOrContext] = container.get(injectionId);
           },
           subscribe: !once
         });
@@ -83,6 +83,41 @@ function injection(optionsOrInjectionId) {
   };
 }
 
+/**
+ * Hook (consumer) to access the active container from the nearest parent context.
+ *
+ * @remarks
+ * The returned value updates when the nearest provided container changes.
+ *
+ * @group Consumption
+ *
+ * @param host - The host element.
+ * @returns An instance of {@link UseContainerValue}.
+ *
+ * @example
+ * ```typescript
+ * class MyElement extends LitElement {
+ *   private container: UseContainerValue = useContainer(this);
+ *
+ *   public render() {
+ *     return html`<div>${this.container.value.isBound(MyService)}</div>`;
+ *   }
+ * }
+ * ```
+ */
+function useContainer(host) {
+  const current = {
+    value: null
+  };
+  new context.ContextConsumer(host, {
+    context: ContainerContext,
+    callback: container => {
+      current.value = container;
+    }
+  });
+  return current;
+}
+
 /**
  * Hook (controller) to inject a service from the IoC container.
  *
@@ -115,21 +150,61 @@ function injection(optionsOrInjectionId) {
  * ```
  */
 function useInjection(host, optionsOrInjectionId) {
-  var options = typeof optionsOrInjectionId === "object" && optionsOrInjectionId !== null && "injectionId" in optionsOrInjectionId ? optionsOrInjectionId : {
+  const options = typeof optionsOrInjectionId === "object" && optionsOrInjectionId !== null && "injectionId" in optionsOrInjectionId ? optionsOrInjectionId : {
     injectionId: optionsOrInjectionId
   };
-  var once = options.once,
-    injectionId = options.injectionId,
-    value = options.value;
-  var current = {
+  const {
+    once,
+    injectionId,
+    value
+  } = options;
+  const current = {
     value: value,
-    injectionId: injectionId
+    injectionId
   };
   new context.ContextConsumer(host, {
-    context: IocContextObject,
+    context: ContainerContext,
     subscribe: !once,
-    callback: function (it) {
-      current.value = it.container.get(injectionId);
+    callback: container => {
+      current.value = container.get(injectionId);
+    }
+  });
+  return current;
+}
+
+/**
+ * Hook (consumer) to access the active {@link WireScope} from the nearest parent context.
+ *
+ * @remarks
+ * The returned value updates when the nearest provided container changes.
+ *
+ * @group Consumption
+ *
+ * @param host - The host element.
+ * @returns An instance of {@link UseScopeValue}.
+ *
+ * @example
+ * ```typescript
+ * class MyElement extends LitElement {
+ *   private scope: UseScopeValue = useScope(this);
+ *
+ *   public connectedCallback(): void {
+ *     super.connectedCallback();
+ *     this.scope.value.emitEvent("UI_READY");
+ *   }
+ * }
+ * ```
+ */
+function useScope(host) {
+  const current = {
+    value: undefined,
+    injectionId: core.WireScope
+  };
+  new context.ContextConsumer(host, {
+    context: ContainerContext,
+    subscribe: true,
+    callback: container => {
+      current.value = container.get(core.WireScope);
     }
   });
   return current;
@@ -144,49 +219,46 @@ function useInjection(host, optionsOrInjectionId) {
  *
  * @group Commands
  */
-var OnCommandController = /** @class */function () {
+class OnCommandController {
+  bus = null;
+  unregister = null;
   /**
    * @param host - The host element.
    * @param type - Unique identifier of the command to handle.
    * @param handler - The command handler function.
    */
-  function OnCommandController(host, type, handler) {
-    var _this = this;
-    this.bus = null;
-    this.unregister = null;
+  constructor(host, type, handler) {
     host.addController(this);
     this.type = type;
     this.handler = handler;
     new context.ContextConsumer(host, {
-      context: IocContextObject,
+      context: ContainerContext,
       subscribe: true,
-      callback: function (context) {
-        _this.bus = context.container.get(core.CommandBus);
+      callback: container => {
+        this.bus = container.get(core.CommandBus);
         if (host.isConnected) {
-          _this.reregister();
+          this.reregister();
         }
       }
     });
   }
-  OnCommandController.prototype.hostConnected = function () {
+  hostConnected() {
     this.reregister();
-  };
-  OnCommandController.prototype.hostDisconnected = function () {
+  }
+  hostDisconnected() {
     this.cleanup();
-  };
-  OnCommandController.prototype.reregister = function () {
+  }
+  reregister() {
     this.cleanup();
     if (this.bus) {
       this.unregister = this.bus.register(this.type, this.handler);
     }
-  };
-  OnCommandController.prototype.cleanup = function () {
-    var _a;
-    (_a = this.unregister) === null || _a === void 0 ? void 0 : _a.call(this);
+  }
+  cleanup() {
+    this.unregister?.();
     this.unregister = null;
-  };
-  return OnCommandController;
-}();
+  }
+}
 
 /**
  * Decorator for Lit element methods that handle a specific command.
@@ -210,21 +282,16 @@ var OnCommandController = /** @class */function () {
  * ```
  */
 function onCommand(type) {
-  return function (protoOrTarget, nameOrContext) {
+  return (protoOrTarget, nameOrContext) => {
     if (typeof nameOrContext === "object") {
       // Standard decorators:
       nameOrContext.addInitializer(function () {
-        var _this = this;
-        new OnCommandController(this, type, function (data) {
-          return _this[nameOrContext.name](data);
-        });
+        new OnCommandController(this, type, data => this[nameOrContext.name](data));
       });
     } else {
       // Experimental legacy decorators:
-      protoOrTarget.constructor.addInitializer(function (element) {
-        new OnCommandController(element, type, function (data) {
-          return element[nameOrContext](data);
-        });
+      protoOrTarget.constructor.addInitializer(element => {
+        new OnCommandController(element, type, data => element[nameOrContext](data));
       });
     }
   };
@@ -251,9 +318,10 @@ function onCommand(type) {
  * }
  * ```
  */
-function useOnCommand(host, _a) {
-  var type = _a.type,
-    handler = _a.handler;
+function useOnCommand(host, {
+  type,
+  handler
+}) {
   return new OnCommandController(host, type, handler);
 }
 
@@ -266,58 +334,54 @@ function useOnCommand(host, _a) {
  *
  * @group Events
  */
-var OnEventController = /** @class */function () {
+class OnEventController {
+  bus = null;
+  unsubscriber = null;
   /**
    * @param host - The host element.
    * @param types - Event types to listen for. If null, all events will be handled.
    * @param handler - The event handler function.
    */
-  function OnEventController(host, types, handler) {
-    var _this = this;
-    this.bus = null;
-    this.unsubscriber = null;
+  constructor(host, types, handler) {
     host.addController(this);
     this.types = types;
     this.handler = handler;
     new context.ContextConsumer(host, {
-      context: IocContextObject,
+      context: ContainerContext,
       subscribe: true,
-      callback: function (context) {
-        _this.bus = context.container.get(core.EventBus);
+      callback: container => {
+        this.bus = container.get(core.EventBus);
         if (host.isConnected) {
-          _this.resubscribe();
+          this.resubscribe();
         }
       }
     });
   }
-  OnEventController.prototype.hostConnected = function () {
+  hostConnected() {
     this.resubscribe();
-  };
-  OnEventController.prototype.hostDisconnected = function () {
+  }
+  hostDisconnected() {
     this.cleanup();
-  };
-  OnEventController.prototype.resubscribe = function () {
-    var _this = this;
+  }
+  resubscribe() {
     this.cleanup();
     if (this.bus) {
       if (this.types === null) {
         this.unsubscriber = this.bus.subscribe(this.handler);
       } else {
-        this.unsubscriber = this.bus.subscribe(function (event) {
-          if (_this.types.includes(event.type)) {
-            _this.handler(event);
+        this.unsubscriber = this.bus.subscribe(event => {
+          if (this.types.includes(event.type)) {
+            this.handler(event);
           }
         });
       }
     }
-  };
-  OnEventController.prototype.cleanup = function () {
-    var _a;
-    (_a = this.unsubscriber) === null || _a === void 0 ? void 0 : _a.call(this);
+  }
+  cleanup() {
+    this.unsubscriber?.();
     this.unsubscriber = null;
-  };
-  return OnEventController;
-}();
+  }
+}
 
 /**
  * Decorator for Lit element methods that handle events from the event bus.
@@ -361,22 +425,17 @@ var OnEventController = /** @class */function () {
  * ```
  */
 function onEvent(types) {
-  var normalized = types === undefined ? null : Array.isArray(types) ? tslib.__spreadArray([], types, true) : [types];
-  return function (protoOrTarget, nameOrContext) {
+  const normalized = types === undefined ? null : Array.isArray(types) ? [...types] : [types];
+  return (protoOrTarget, nameOrContext) => {
     if (typeof nameOrContext === "object") {
       // Standard decorators:
       nameOrContext.addInitializer(function () {
-        var _this = this;
-        new OnEventController(this, normalized, function (event) {
-          return _this[nameOrContext.name](event);
-        });
+        new OnEventController(this, normalized, event => this[nameOrContext.name](event));
       });
     } else {
       // Experimental legacy decorators:
-      protoOrTarget.constructor.addInitializer(function (element) {
-        new OnEventController(element, normalized, function (event) {
-          return element[nameOrContext](event);
-        });
+      protoOrTarget.constructor.addInitializer(element => {
+        new OnEventController(element, normalized, event => element[nameOrContext](event));
       });
     }
   };
@@ -412,10 +471,11 @@ function onEvent(types) {
  * }
  * ```
  */
-function useOnEvents(host, _a) {
-  var types = _a.types,
-    handler = _a.handler;
-  var normalized = types ? Array.isArray(types) ? tslib.__spreadArray([], types, true) : [types] : null;
+function useOnEvents(host, {
+  types,
+  handler
+}) {
+  const normalized = types ? Array.isArray(types) ? [...types] : [types] : null;
   return new OnEventController(host, normalized, handler);
 }
 
@@ -428,49 +488,46 @@ function useOnEvents(host, _a) {
  *
  * @group Queries
  */
-var OnQueryController = /** @class */function () {
+class OnQueryController {
+  bus = null;
+  unregister = null;
   /**
    * @param host - The host element.
    * @param type - Unique identifier of the query to handle.
    * @param handler - The query handler function.
    */
-  function OnQueryController(host, type, handler) {
-    var _this = this;
-    this.bus = null;
-    this.unregister = null;
+  constructor(host, type, handler) {
     host.addController(this);
     this.type = type;
     this.handler = handler;
     new context.ContextConsumer(host, {
-      context: IocContextObject,
+      context: ContainerContext,
       subscribe: true,
-      callback: function (context) {
-        _this.bus = context.container.get(core.QueryBus);
+      callback: container => {
+        this.bus = container.get(core.QueryBus);
         if (host.isConnected) {
-          _this.reregister();
+          this.reregister();
         }
       }
     });
   }
-  OnQueryController.prototype.hostConnected = function () {
+  hostConnected() {
     this.reregister();
-  };
-  OnQueryController.prototype.hostDisconnected = function () {
+  }
+  hostDisconnected() {
     this.cleanup();
-  };
-  OnQueryController.prototype.reregister = function () {
+  }
+  reregister() {
     this.cleanup();
     if (this.bus) {
       this.unregister = this.bus.register(this.type, this.handler);
     }
-  };
-  OnQueryController.prototype.cleanup = function () {
-    var _a;
-    (_a = this.unregister) === null || _a === void 0 ? void 0 : _a.call(this);
+  }
+  cleanup() {
+    this.unregister?.();
     this.unregister = null;
-  };
-  return OnQueryController;
-}();
+  }
+}
 
 /**
  * Decorator for Lit element methods that handle a specific query.
@@ -494,21 +551,16 @@ var OnQueryController = /** @class */function () {
  * ```
  */
 function onQuery(type) {
-  return function (protoOrTarget, nameOrContext) {
+  return (protoOrTarget, nameOrContext) => {
     if (typeof nameOrContext === "object") {
       // Standard decorators:
       nameOrContext.addInitializer(function () {
-        var _this = this;
-        new OnQueryController(this, type, function (data) {
-          return _this[nameOrContext.name](data);
-        });
+        new OnQueryController(this, type, data => this[nameOrContext.name](data));
       });
     } else {
       // Experimental legacy decorators:
-      protoOrTarget.constructor.addInitializer(function (element) {
-        new OnQueryController(element, type, function (data) {
-          return element[nameOrContext](data);
-        });
+      protoOrTarget.constructor.addInitializer(element => {
+        new OnQueryController(element, type, data => element[nameOrContext](data));
       });
     }
   };
@@ -535,128 +587,217 @@ function onQuery(type) {
  * }
  * ```
  */
-function useOnQuery(host, _a) {
-  var type = _a.type,
-    handler = _a.handler;
+function useOnQuery(host, {
+  type,
+  handler
+}) {
   return new OnQueryController(host, type, handler);
 }
 
+const ERROR_CODE_INVALID_ARGUMENTS = 2051;
+
 /**
- * Controller that provides an IoC container context to the host element and its children.
+ * Provider that exposes an IoC container context to the host element and its children.
  *
  * @remarks
- * It manages the lifecycle of the container and handles revision updates to notify consumers.
- * The container is created (or used from options) when the controller is instantiated.
- * Seed data is applied when the host connects.
+ * The provider supports two modes:
+ *
+ * - External mode: `container` is an existing {@link Container}. The
+ *   provider passes it through context and does not alter its lifecycle.
+ * - Managed mode: `options` is {@link CreateContainerOptions}. The provider
+ *   creates a container during construction without eager activation,
+ *   activates configured entries when the host connects, disposes the
+ *   container when the host disconnects, and recreates it on reconnect.
  *
  * @group Provision
  */
-var IocProviderController = /** @class */function () {
+class ContainerProvider extends context.ContextProvider {
+  destroyed = false;
   /**
    * @param host - The host element.
    * @param options - Provisioning options.
-   * @param options.container - Optional existing container to use. If not provided, a new one will be created.
-   * @param options.seed - Optional seed data to apply to the container.
+   * @param options.container - External container instance to provide.
+   * @param options.options - Managed container creation options.
    */
-  function IocProviderController(host, _a) {
-    var _b = _a === void 0 ? {} : _a,
-      container = _b.container,
-      seed = _b.seed;
-    var _this = this;
-    this.host = host;
-    this.revision = 1;
-    this.host.addController(this);
-    this.container = container !== null && container !== void 0 ? container : core.createContainer();
-    this.seed = seed;
-    this.provider = new context.ContextProvider(host, {
-      context: IocContextObject,
-      initialValue: {
-        container: this.container,
-        revision: this.revision,
-        nextRevision: function () {
-          return _this.nextRevision();
+  constructor(host, options) {
+    if (!options.container && !options.options) {
+      throw new core.WirestateError(ERROR_CODE_INVALID_ARGUMENTS, "ContainerProvider requires a valid container instance or creation options.");
+    } else if (options.container && options.options) {
+      throw new core.WirestateError(ERROR_CODE_INVALID_ARGUMENTS, "ContainerProvider requires only container or valid options object to be provided.");
+    }
+    super(host, {
+      context: ContainerContext,
+      initialValue: options.container ? options.container : core.createContainer({
+        ...options.options,
+        activate: []
+      })
+    });
+    this.options = options.options;
+  }
+  hostConnected() {
+    if (this.options) {
+      if (this.destroyed) {
+        this.value = core.createContainer(this.options);
+        this.destroyed = false;
+      } else {
+        if (this.options?.activate) {
+          for (const entry of this.options.activate) {
+            this.value.get(entry);
+          }
         }
       }
-    });
+    }
+    super.hostConnected();
   }
-  Object.defineProperty(IocProviderController.prototype, "value", {
-    /**
-     * @returns Current {@link IocContext} value served to child consumers.
-     */
-    get: function () {
-      return this.provider.value;
-    },
-    enumerable: false,
-    configurable: true
-  });
-  IocProviderController.prototype.hostConnected = function () {
-    if (this.seed) {
-      core.applySharedSeed(this.container, this.seed);
+  hostDisconnected() {
+    if (this.options) {
+      this.value.unbindAll();
+      this.destroyed = true;
     }
-  };
-  IocProviderController.prototype.hostDisconnected = function () {};
-  IocProviderController.prototype.nextRevision = function () {
-    var _this = this;
-    this.revision += 1;
-    this.provider.setValue({
-      container: this.container,
-      revision: this.revision,
-      nextRevision: function () {
-        return _this.nextRevision();
+  }
+}
+
+/**
+ * Provider that exposes a managed child container for the host element's lifetime.
+ *
+ * @remarks
+ * The provider always owns a child container derived from the nearest parent
+ * {@link ContainerContext}. When connected, it creates a child container using
+ * the latest parent context, provides it to descendants, destroys it when the
+ * host disconnects, and replaces it whenever the parent container changes.
+ *
+ * @group Provision
+ *
+ * @example
+ * ```typescript
+ * class MyComponent extends LitElement {
+ *   private container = new SubContainerProvider(this, {
+ *     options: {
+ *       entries: [AuthService, UserService],
+ *       activate: [AuthService],
+ *       seeds: [[AuthService, { role: "admin" }]],
+ *     },
+ *   });
+ * }
+ * ```
+ */
+class SubContainerProvider extends context.ContextProvider {
+  parent = null;
+  destroyed = true;
+  /**
+   * @param host - The host element.
+   * @param options - Provisioning options, including child entries, eager activations, and seeds.
+   */
+  constructor(host, options) {
+    super(host, {
+      context: ContainerContext
+    });
+    this.options = options.options;
+    this.consumer = new context.ContextConsumer(host, {
+      context: ContainerContext,
+      subscribe: true,
+      callback: context => {
+        const previousParent = this.parent;
+        this.parent = context;
+        if (host.isConnected) {
+          if (this.destroyed || !this.value || previousParent !== context) {
+            this.destroyContainer();
+            this.createContainer();
+          }
+        }
       }
     });
-    return this.revision;
-  };
-  return IocProviderController;
-}();
+  }
+  hostConnected() {
+    if (this.parent && (this.destroyed || !this.value)) {
+      this.destroyContainer();
+      this.createContainer();
+    }
+    super.hostConnected();
+  }
+  hostDisconnected() {
+    this.destroyContainer();
+  }
+  /**
+   * Replaces the currently provided child container with a new one derived
+   * from the latest parent context.
+   */
+  createContainer() {
+    const container = core.createContainer({
+      ...this.options,
+      parent: this.parent
+    });
+    this.destroyed = false;
+    this.value = container;
+  }
+  /**
+   * Destroys the currently provided child container.
+   */
+  destroyContainer() {
+    if (this.value && !this.destroyed) {
+      this.value.unbindAll();
+      this.destroyed = true;
+    }
+  }
+}
 
 /**
  * Decorator that provides an IoC container to child components.
  *
  * @remarks
- * The container is provided via Lit context. It is created (or used from options) when the host connects.
+ * The container is provided via Lit context.
+ *
+ * - Pass `container` to expose an external container without taking
+ *   ownership.
+ * - Pass `options` to create a managed container during construction,
+ *   activate configured entries on connect, destroy it on disconnect, and
+ *   recreate it on reconnect.
  *
  * @group Provision
  *
  * @param options - Provisioning options.
- * @param options.container - Optional existing container to use, if not provided, a new one will be created.
- * @param options.seed - Optional seed data to apply to the container.
- * @returns An instance of {@link IocProviderDecorator}.
+ * @param options.container - External container instance to provide.
+ * @param options.options - Managed container creation options.
+ * @returns An instance of {@link ContainerProviderDecorator}.
+ *
+ * @example
+ * ```typescript
+ * class MyRootElement extends LitElement {
+ *   @containerProvide({
+ *     options: {
+ *       seed: { someData: "value" },
+ *       entries: [LoggerService],
+ *     },
+ *   })
+ *   private containerProvider!: ContainerProvider;
+ * }
+ * ```
  *
  * @example
  * ```typescript
  * class MyRootElement extends LitElement {
- *   @iocProvide({ seed: { someData: "value" } })
- *   private ioc!: IocProviderController;
+ *   @containerProvide({ container: container })
+ *   private containerProvider!: ContainerProvider;
  * }
  * ```
  */
-function iocProvide(_a) {
-  var _b = _a === void 0 ? {} : _a,
-    container = _b.container,
-    seed = _b.seed;
-  return function (protoOrTarget, nameOrContext) {
+function containerProvide(options) {
+  return (protoOrTarget, nameOrContext) => {
     if (typeof nameOrContext === "object") {
       // Standard decorators:
       nameOrContext.addInitializer(function () {
-        protoOrTarget.set.call(this, new IocProviderController(this, {
-          container: container,
-          seed: seed
-        }));
+        protoOrTarget.set.call(this, new ContainerProvider(this, options));
       });
     } else {
-      var controller_1;
-      protoOrTarget.constructor.addInitializer(function (element) {
-        controller_1 = new IocProviderController(element, {
-          container: container,
-          seed: seed
-        });
+      let controller;
+      protoOrTarget.constructor.addInitializer(element => {
+        controller = new ContainerProvider(element, options);
       });
       return {
-        get: function () {
-          return controller_1;
+        get() {
+          return controller;
         },
-        set: function () {},
+        set() {},
         configurable: true,
         enumerable: true
       };
@@ -664,160 +805,51 @@ function iocProvide(_a) {
   };
 }
 
-var ERROR_CODE_INVALID_ARGUMENTS = 2051;
-
-/**
- * Controller that binds injectables to an IoC container for the host element's lifetime.
- *
- * @remarks
- * Entries are bound when the host connects and unbound when it disconnects.
- * If no `into` context is provided, it uses the nearest {@link IocProviderController}.
- * Seeds are applied before entries are bound.
- *
- * @group Provision
- *
- * @example
- * ```typescript
- * class MyComponent extends LitElement {
- *   private services = new InjectablesProviderController(this, {
- *     entries: [AuthService, UserService],
- *     activate: [AuthService],
- *     seeds: [[AuthService, { role: "admin" }]],
- *   });
- * }
- * ```
- */
-var InjectablesProviderController = /** @class */function () {
-  /**
-   * @param host - The host element.
-   * @param options - Provisioning options.
-   * @param options.entries - List of service entries to bind to the container.
-   * @param options.into - Target IoC context; if omitted, uses the nearest provider context.
-   * @param options.activate - List of service identifiers to activate immediately after binding.
-   * @param options.seeds - Seed data applied before binding.
-   */
-  function InjectablesProviderController(host, options) {
-    var _this = this;
-    var _a, _b, _c;
-    this.host = host;
-    /**
-     * Tracks the context to which entries are currently bound, for correct cleanup on disconnect.
-     */
-    this.boundContext = null;
-    this.host.addController(this);
-    this.entries = options.entries;
-    this.activate = (_a = options.activate) !== null && _a !== void 0 ? _a : null;
-    this.seeds = (_b = options.seeds) !== null && _b !== void 0 ? _b : null;
-    this.into = (_c = options.into) !== null && _c !== void 0 ? _c : null;
-    if (!this.into) {
-      // subscribe: false — binding happens once per connect, not on every revision update.
-      this.consumer = new context.ContextConsumer(host, {
-        context: IocContextObject,
-        subscribe: false,
-        callback: function (context) {
-          if (!host.isConnected) {
-            return;
-          }
-          _this.bind(context);
-        }
-      });
-    }
-  }
-  InjectablesProviderController.prototype.hostConnected = function () {
-    var _a;
-    if (!this.into) {
-      // ContextConsumer with subscribe:false only invokes the user callback once (provided flag stays true
-      // after disconnect). On reconnect we fall back to the cached consumer.value so bind() still fires.
-      if ((_a = this.consumer) === null || _a === void 0 ? void 0 : _a.value) {
-        this.bind(this.consumer.value);
-      }
-      return;
-    }
-    var context = typeof this.into === "function" ? this.into() : this.into;
-    if (!context) {
-      throw new core.WirestateError(ERROR_CODE_INVALID_ARGUMENTS, "InjectablesProviderController: the 'into' option resolved to null or undefined. " + "Ensure the value or resolver function returns a valid IocContext.");
-    }
-    this.bind(context);
-  };
-  InjectablesProviderController.prototype.hostDisconnected = function () {
-    if (!this.boundContext) {
-      return;
-    }
-    this.unbind(this.boundContext);
-  };
-  InjectablesProviderController.prototype.bind = function (context) {
-    if (this.boundContext) {
-      // Re-binding without unbinding first would leave stale entries; unbind the previous context.
-      this.unbind(this.boundContext);
-    }
-    this.boundContext = context;
-    // Seeds must be applied before binding so @Inject(SEEDS_TOKEN) resolves during activation.
-    if (this.seeds) {
-      core.applySeeds(context.container, this.seeds);
-    }
-    for (var _i = 0, _a = this.entries; _i < _a.length; _i++) {
-      var entry = _a[_i];
-      core.bindEntry(context.container, entry);
-    }
-    if (this.activate) {
-      for (var _b = 0, _c = this.activate; _b < _c.length; _b++) {
-        var token = _c[_b];
-        context.container.get(token);
-      }
-    }
-  };
-  InjectablesProviderController.prototype.unbind = function (context) {
-    for (var _i = 0, _a = this.entries; _i < _a.length; _i++) {
-      var entry = _a[_i];
-      var token = core.getEntryToken(entry);
-      if (context.container.isBound(token)) {
-        context.container.unbind(token);
-      }
-    }
-    if (this.seeds) {
-      core.unapplySeeds(context.container, this.seeds);
-    }
-    this.boundContext = null;
-  };
-  return InjectablesProviderController;
-}();
-
 /**
- * Decorator that binds a set of injectables to the nearest IoC container for the host element's lifetime.
+ * Decorator that provides a managed child container derived from the nearest
+ * parent container context.
  *
  * @remarks
- * Entries are bound when the host connects and unbound when it disconnects.
+ * The child container is created from the current parent context when the host
+ * connects, destroyed when it disconnects, and recreated when the parent
+ * container changes.
  *
  * @group Provision
  *
  * @param options - Provisioning options.
- * @returns An instance of {@link InjectablesProviderDecorator}.
+ * @param options.options - Child-container creation options.
+ * @returns An instance of {@link SubContainerProviderDecorator}.
  *
  * @example
  * ```typescript
  * class MyComponent extends LitElement {
- *   @injectablesProvide({ entries: [AuthService, UserService], activate: [AuthService] })
- *   public controller!: InjectablesProviderController<MyComponent>;
+ *   @subContainerProvide({
+ *     options: {
+ *       entries: [AuthService, UserService],
+ *       activate: [AuthService],
+ *     },
+ *   })
+ *   public containerProvider!: SubContainerProvider<MyComponent>;
  * }
  * ```
  */
-function injectablesProvide(options) {
-  return function (protoOrTarget, nameOrContext) {
+function subContainerProvide(options) {
+  return (protoOrTarget, nameOrContext) => {
     if (typeof nameOrContext === "object") {
       // Standard decorators:
       nameOrContext.addInitializer(function () {
-        protoOrTarget.set.call(this, new InjectablesProviderController(this, options));
+        protoOrTarget.set.call(this, new SubContainerProvider(this, options));
       });
     } else {
-      var controller_1;
-      protoOrTarget.constructor.addInitializer(function (element) {
-        controller_1 = new InjectablesProviderController(element, options);
+      let provider;
+      protoOrTarget.constructor.addInitializer(element => {
+        provider = new SubContainerProvider(element, options);
       });
       return {
-        get: function () {
-          return controller_1;
+        get() {
+          return provider;
         },
-        set: function () {},
+        set() {},
         configurable: true,
         enumerable: true
       };
@@ -826,67 +858,93 @@ function injectablesProvide(options) {
 }
 
 /**
- * Hook that binds injectables to the nearest IoC container for the host element's lifetime.
+ * Hook that provides a container to the host element and its children.
+ *
+ * @remarks
+ * Pass `container` to expose an external `Container` without taking
+ * ownership. Pass `options` to create a managed container during
+ * construction, activate configured entries on connect, destroy it on
+ * disconnect, and recreate it on reconnect.
  *
  * @group Provision
  *
  * @param host - The host element.
  * @param options - Provisioning options.
- * @returns An instance of {@link InjectablesProviderController}.
+ * @param options.container - External container instance to provide.
+ * @param options.options - Managed container creation options.
+ * @returns An instance of {@link ContainerProvider}.
  *
  * @example
  * ```typescript
- * class MyComponent extends LitElement {
- *   private services = useInjectablesProvider(this, {
- *     entries: [AuthService, UserService],
- *     activate: [AuthService],
+ * class MyRootElement extends LitElement {
+ *   private containerProvider: ContainerProvider = useContainerProvision(this, {
+ *     options: {
+ *       entries: [LoggerService],
+ *       activate: [LoggerService],
+ *     },
  *   });
  * }
  * ```
+ *
+ * @example
+ * ```typescript
+ * class MyRootElement extends LitElement {
+ *   private containerProvider: ContainerProvider = useContainerProvision(this, { container: container });
+ * }
+ * ```
  */
-function useInjectablesProvider(host, options) {
-  return new InjectablesProviderController(host, options);
+function useContainerProvision(host, options) {
+  return new ContainerProvider(host, options);
 }
 
 /**
- * Hook that provides an IoC container to the host element and its children.
+ * Hook that provides a managed child container for the host element's lifetime.
+ *
+ * @remarks
+ * The child container is derived from the current parent
+ * {@link ContainerContext}, recreated when that parent context changes, and
+ * destroyed when the host disconnects.
  *
  * @group Provision
  *
  * @param host - The host element.
  * @param options - Provisioning options.
- * @returns An instance of {@link IocProviderController}.
+ * @param options.options - Child-container creation options.
+ * @returns An instance of {@link SubContainerProvider}.
  *
  * @example
  * ```typescript
- * class MyRootElement extends LitElement {
- *   private ioc = useIocProvision(this, { seed: { initialData: "..." } });
+ * class MyComponent extends LitElement {
+ *   private containerProvider: SubContainerProvider = useSubContainerProvider(this, {
+ *     options: {
+ *       entries: [AuthService, UserService],
+ *     },
+ *   });
  * }
  * ```
  */
-function useIocProvision(host, options) {
-  if (options === void 0) {
-    options = {};
-  }
-  return new IocProviderController(host, options);
+function useSubContainerProvider(host, options) {
+  return new SubContainerProvider(host, options);
 }
 
-exports.InjectablesProviderController = InjectablesProviderController;
-exports.IocContextObject = IocContextObject;
-exports.IocProviderController = IocProviderController;
+exports.ContainerContext = ContainerContext;
+exports.ContainerProvider = ContainerProvider;
 exports.OnCommandController = OnCommandController;
 exports.OnEventController = OnEventController;
 exports.OnQueryController = OnQueryController;
-exports.injectablesProvide = injectablesProvide;
+exports.SubContainerProvider = SubContainerProvider;
+exports.containerProvide = containerProvide;
 exports.injection = injection;
-exports.iocProvide = iocProvide;
 exports.onCommand = onCommand;
 exports.onEvent = onEvent;
 exports.onQuery = onQuery;
-exports.useInjectablesProvider = useInjectablesProvider;
+exports.subContainerProvide = subContainerProvide;
+exports.useContainer = useContainer;
+exports.useContainerProvision = useContainerProvision;
 exports.useInjection = useInjection;
-exports.useIocProvision = useIocProvision;
 exports.useOnCommand = useOnCommand;
 exports.useOnEvents = useOnEvents;
 exports.useOnQuery = useOnQuery;
+exports.useScope = useScope;
+exports.useSubContainerProvider = useSubContainerProvider;
 //# sourceMappingURL=index.js.map