@wirestate/lit 0.6.1 → 0.7.0-experimental.2

package/index.d.ts

@@ -1,29 +1,29 @@
 import { ReactiveElement, ReactiveControllerHost, ReactiveController } from '@lit/reactive-element';
-import { ServiceIdentifier, CommandType, CommandHandler, Event, EventType, EventHandler, QueryType, QueryHandler, Container, Newable, InjectableDescriptor, SeedEntries } from '@wirestate/core';
+import { ServiceIdentifier, Container as Container$1, WireScope, CommandType, CommandHandler, Event, EventType, EventHandler, QueryType, QueryHandler, CreateContainerOptions, Newable, InjectableDescriptor, SeedEntries } from '@wirestate/core';
 import { ContextProvider, ContextConsumer } from '@lit/context';
 
 /**
- * Represents any object with string or symbol keys.
+ * Type that can be null.
  *
- * @group types
+ * @group Types
  */
-type AnyObject = Record<string | symbol, any>;
+type Optional<T> = T | null;
 /**
- * Represents a type that can be null.
+ * Value or a promise of that value.
  *
- * @group types
+ * @group Types
  */
-type Optional<T> = T | null;
+type MaybePromise<T> = T | Promise<T>;
 /**
- * Represents a type that can be a value or a promise of that value.
+ * Value that can be null or undefined.
  *
- * @group types
+ * @group Types
  */
-type MaybePromise<T> = T | Promise<T>;
+type Maybe<T> = T | null | undefined;
 /**
  * Helper to extract the interface of a type.
  *
- * @group types
+ * @group Types
  */
 type Interface<T> = {
     [K in keyof T]: T[K];
@@ -31,13 +31,13 @@ type Interface<T> = {
 /**
  * Return type for decorators.
  *
- * @group types
+ * @group Types
  */
 type DecoratorReturn = void | any;
 /**
- * Type helper to ensure that a decorated field matches the type being provided.
+ * Ensures that a decorated field matches the type being provided.
  *
- * @group types
+ * @group Types
  */
 type FieldMustMatchProvidedType<Obj, Key extends PropertyKey, ProvidedType> = Obj extends Record<Key, infer ConsumingType> ? [ProvidedType] extends [ConsumingType] ? DecoratorReturn : {
     message: "provided type not assignable to consuming field";
@@ -50,39 +50,43 @@ type FieldMustMatchProvidedType<Obj, Key extends PropertyKey, ProvidedType> = Ob
 } : DecoratorReturn;
 
 /**
- * Type definition for the injection decorator.
+ * Represents definition of the injection decorator.
+ *
+ * @remarks
+ * Supports both TC39 and legacy experimental decorators.
  *
- * @group consumption
+ * @group Consumption
  */
 interface InjectionDecorator<T> {
     <C extends Interface<Omit<ReactiveElement, "renderRoot">>, V extends T>(value: ClassAccessorDecoratorTarget<C, V>, context: ClassAccessorDecoratorContext<C, V>): void;
     <K extends PropertyKey, Proto extends Interface<Omit<ReactiveElement, "renderRoot">>>(protoOrDescriptor: Proto, name?: K): FieldMustMatchProvidedType<Proto, K, T>;
 }
 /**
- * Options for the {@link injection} decorator.
+ * Represents options for the {@link injection} decorator.
  *
- * @group consumption
+ * @group Consumption
  */
 interface InjectionOptions<T> {
     /**
-     * The service identifier to inject from the IoC container.
+     * The service identifier to inject.
      */
     injectionId: ServiceIdentifier<T>;
     /**
-     * Whether to subscribe to changes in the context.
+     * Whether to subscribe to container changes.
      *
+     * @remarks
      * If true, the property will be updated if the container in the context changes.
-     * False by default.
+     * Defaults to false.
      */
     once?: boolean;
 }
 /**
  * Decorator to inject a service from the IoC container into a Lit element property.
  *
- * @group consumption
+ * @group Consumption
  *
- * @param optionsOrInjectionId - injection options including the service identifier or the service identifier itself
- * @returns injection decorator instance
+ * @param optionsOrInjectionId - Injection options or service identifier.
+ * @returns An instance of {@link InjectionDecorator}.
  *
  * @example
  * ```typescript
@@ -111,18 +115,56 @@ interface InjectionOptions<T> {
 declare function injection<T>(optionsOrInjectionId: InjectionOptions<T> | ServiceIdentifier<T>): InjectionDecorator<T>;
 
 /**
- * Options for the {@link useInjection} hook.
+ * Represents result of the {@link useContainer} hook.
+ *
+ * @group Consumption
+ */
+interface UseContainerValue {
+    /**
+     * The active container from the nearest parent context.
+     */
+    value: Container$1;
+}
+/**
+ * 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>`;
+ *   }
+ * }
+ * ```
+ */
+declare function useContainer<E extends ReactiveControllerHost & HTMLElement>(host: E): UseContainerValue;
+
+/**
+ * Represents options for the {@link useInjection} hook.
  *
- * @group consumption
+ * @group Consumption
  */
 interface UseInjectionOptions<T> {
     /**
+     * Whether to subscribe to container changes.
+     *
+     * @remarks
      * If true, the service will be fetched only once when the controller is created.
-     * If false (default), it will update if the container in the context changes.
+     * Defaults to false.
      */
     once?: boolean;
     /**
-     * Initial value for the injection before it's fetched from the container.
+     * Initial value before the service is fetched.
      */
     value?: Optional<T>;
     /**
@@ -131,9 +173,9 @@ interface UseInjectionOptions<T> {
     injectionId: ServiceIdentifier<T>;
 }
 /**
- * The return value of the {@link useInjection} hook, containing the injected service.
+ * Represents result of the {@link useInjection} hook.
  *
- * @group consumption
+ * @group Consumption
  */
 interface UseInjectionValue<T> {
     /**
@@ -146,13 +188,13 @@ interface UseInjectionValue<T> {
     value: T;
 }
 /**
- * Hook (controller) to inject a service from the IoC container in a Lit component.
+ * Hook (controller) to inject a service from the IoC container.
  *
- * @group consumption
+ * @group Consumption
  *
- * @param host - the host element
- * @param optionsOrInjectionId - injection options including the service identifier or the service identifier itself
- * @returns injection descriptor object
+ * @param host - The host element.
+ * @param optionsOrInjectionId - Injection options or service identifier.
+ * @returns An instance of {@link UseInjectionValue}.
  *
  * @example
  * ```typescript
@@ -179,31 +221,64 @@ interface UseInjectionValue<T> {
 declare function useInjection<T extends object, E extends ReactiveControllerHost & HTMLElement>(host: E, optionsOrInjectionId: UseInjectionOptions<T> | ServiceIdentifier<T>): UseInjectionValue<T>;
 
 /**
- * Interface for the {@link onCommand} decorator.
+ * Represents result of the {@link useScope} hook.
+ *
+ * @group Consumption
+ */
+type UseScopeValue = UseInjectionValue<WireScope>;
+/**
+ * Hook (consumer) to access the active {@link WireScope} from the nearest parent context.
+ *
+ * @remarks
+ * The returned value updates when the nearest provided container changes.
  *
- * Supports both standard (TC39) and legacy experimental decorators.
+ * @group Consumption
  *
- * @group commands
+ * @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");
+ *   }
+ * }
+ * ```
+ */
+declare function useScope<E extends ReactiveControllerHost & HTMLElement>(host: E): UseScopeValue;
+
+/**
+ * Represents interface for the {@link onCommand} decorator.
+ *
+ * @remarks
+ * Supports both TC39 and legacy experimental decorators.
+ *
+ * @group Commands
  */
 interface OnCommandDecorator<D = unknown, R = unknown> {
     <This extends Interface<Omit<ReactiveElement, "renderRoot">>>(value: (this: This, data: D) => MaybePromise<R>, context: ClassMethodDecoratorContext<This>): void;
     (target: object, propertyKey: string | symbol, descriptor: PropertyDescriptor): void;
 }
 /**
- * Decorator that registers a Lit element method as a command handler for the given type.
+ * Decorator for Lit element methods that handle a specific command.
  *
- * The handler is registered when the host element connects to the DOM and unregistered when it disconnects.
+ * @remarks
+ * The handler is registered when the host connects and unregistered when it disconnects.
  *
- * @group commands
+ * @group Commands
  *
- * @param type - the command type to handle
- * @returns the decorator function.
+ * @param type - Unique identifier of the command to handle.
+ * @returns A method decorator function.
  *
  * @example
  * ```typescript
  * class MyElement extends LitElement {
  *   @onCommand("SAVE")
- *   private handleSave(data: SomeData): void {
+ *   private onSave(data: SomeData): void {
  *     // handle command
  *   }
  * }
@@ -212,12 +287,13 @@ interface OnCommandDecorator<D = unknown, R = unknown> {
 declare function onCommand<D = unknown, R = unknown>(type: CommandType): OnCommandDecorator<D, R>;
 
 /**
- * Reactive controller that registers a command handler on the {@link CommandBus} for the host element's lifetime.
+ * Controller that registers a command handler for the host element's lifetime.
  *
+ * @remarks
  * The handler is registered when the host connects and unregistered when it disconnects.
- * When the IoC context is updated (container revision change), the handler is re-registered automatically.
+ * It automatically re-registers if the IoC container is updated.
  *
- * @group commands
+ * @group Commands
  */
 declare class OnCommandController<D = unknown, R = unknown> implements ReactiveController {
     private bus;
@@ -226,7 +302,7 @@ declare class OnCommandController<D = unknown, R = unknown> implements ReactiveC
     private readonly handler;
     /**
      * @param host - The host element.
-     * @param type - The command type to handle.
+     * @param type - Unique identifier of the command to handle.
      * @param handler - The command handler function.
      */
     constructor(host: ReactiveElement, type: CommandType, handler: CommandHandler<D, R>);
@@ -237,9 +313,9 @@ declare class OnCommandController<D = unknown, R = unknown> implements ReactiveC
 }
 
 /**
- * Options for the {@link useOnCommand} hook.
+ * Represents options for the {@link useOnCommand} hook.
  *
- * @group commands
+ * @group Commands
  */
 interface UseOnCommandOptions<D = unknown, R = unknown> {
     /**
@@ -252,15 +328,15 @@ interface UseOnCommandOptions<D = unknown, R = unknown> {
     handler: CommandHandler<D, R>;
 }
 /**
- * Registers a command handler on the CommandBus for the host element's lifetime.
+ * Hook that registers a command handler for the host element's lifetime.
  *
- * @group commands
+ * @group Commands
  *
- * @param host - the host element
- * @param options - command handling options
- * @param options.type - the command type to listen for
- * @param options.handler - the command handler function
- * @returns the command controller instance
+ * @param host - The host element.
+ * @param options - Command handling options.
+ * @param options.type - The command type to listen for.
+ * @param options.handler - The command handler function.
+ * @returns The command controller instance.
  *
  * @example
  * ```typescript
@@ -275,28 +351,34 @@ interface UseOnCommandOptions<D = unknown, R = unknown> {
 declare function useOnCommand<D = unknown, R = unknown>(host: ReactiveElement, { type, handler }: UseOnCommandOptions<D, R>): OnCommandController<D, R>;
 
 /**
- * Type definition for the on-event decorator.
+ * Represents type definition for the on-event decorator.
+ *
+ * @remarks
+ * Supports both TC39 and legacy experimental decorators.
  *
- * @group events
+ * @group Events
  */
 interface OnEventDecorator<E extends Event = Event> {
     <This extends Interface<Omit<ReactiveElement, "renderRoot">>>(value: (this: This, event: E) => void, context: ClassMethodDecoratorContext<This>): void;
     (target: object, propertyKey: string | symbol, descriptor: PropertyDescriptor): void;
 }
 /**
- * Decorator to handle events from the event bus.
+ * Decorator for Lit element methods that handle events from the event bus.
  *
- * @group events
+ * @remarks
+ * The handler is registered when the host connects and unregistered when it disconnects.
+ *
+ * @group Events
  *
  * @param types - Event types to listen for. If omitted, all events will be handled.
- * @returns The decorator function.
+ * @returns A method decorator function.
  *
  * @example
  * ```typescript
  * class MyElement extends LitElement {
  *   @onEvent()
  *   private onMyEvent(event: Event) {
- *     console.log('Event received:', event);
+ *     console.log("Event received:", event);
  *   }
  * }
  * ```
@@ -304,9 +386,9 @@ interface OnEventDecorator<E extends Event = Event> {
  * @example
  * ```typescript
  * class MyElement extends LitElement {
- *   @onEvent('MY_EVENT_TYPE')
+ *   @onEvent("MY_EVENT_TYPE")
  *   private onMyEvent(event: MyEvent) {
- *     console.log('Event received:', event);
+ *     console.log("Event received:", event);
  *   }
  * }
  * ```
@@ -314,9 +396,9 @@ interface OnEventDecorator<E extends Event = Event> {
  * @example
  * ```typescript
  * class MyElement extends LitElement {
- *   @onEvent(['MY_EVENT_TYPE_1', 'MY_EVENT_TYPE_2'])
+ *   @onEvent(["MY_EVENT_TYPE_1", "MY_EVENT_TYPE_2"])
  *   private onMyEvent(event: Event) {
- *     console.log('Event received:', event);
+ *     console.log("Event received:", event);
  *   }
  * }
  * ```
@@ -324,11 +406,13 @@ interface OnEventDecorator<E extends Event = Event> {
 declare function onEvent<E extends Event = Event>(types?: EventType | ReadonlyArray<EventType>): OnEventDecorator<E>;
 
 /**
- * Controller that subscribes to events from the event bus.
+ * Controller that subscribes to events for the host element's lifetime.
  *
- * It automatically handles subscription and unsubscription based on the host element's lifecycle.
+ * @remarks
+ * The handler is registered when the host connects and unregistered when it disconnects.
+ * It automatically re-subscribes if the IoC container is updated.
  *
- * @group events
+ * @group Events
  */
 declare class OnEventController<E extends Event = Event> implements ReactiveController {
     private bus;
@@ -336,9 +420,9 @@ declare class OnEventController<E extends Event = Event> implements ReactiveCont
     private readonly types;
     private readonly handler;
     /**
-     * @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
+     * @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.
      */
     constructor(host: ReactiveElement, types: Optional<ReadonlyArray<EventType>>, handler: EventHandler<E>);
     hostConnected(): void;
@@ -348,13 +432,13 @@ declare class OnEventController<E extends Event = Event> implements ReactiveCont
 }
 
 /**
- * Options for the {@link useOnEvents} hook.
+ * Represents options for the {@link useOnEvents} hook.
  *
- * @group events
+ * @group Events
  */
 interface UseOnEventsOptions<E extends Event = Event> {
     /**
-     * Event handler function.
+     * The event handler function.
      */
     handler: EventHandler<E>;
     /**
@@ -363,15 +447,15 @@ interface UseOnEventsOptions<E extends Event = Event> {
     types?: Optional<EventType | ReadonlyArray<EventType>>;
 }
 /**
- * Hook (controller) to handle events from the event bus.
+ * Hook that subscribes to events for the host element's lifetime.
  *
- * @group events
+ * @group Events
  *
- * @param host - the host element
- * @param options - event handling options
- * @param options.handler - event handler function
- * @param options.types - event types to listen for, if null or undefined, all events will be handled
- * @returns events subscription controller
+ * @param host - The host element.
+ * @param options - Event handling options.
+ * @param options.handler - Event handler function.
+ * @param options.types - Event types to listen for, if null or undefined, all events will be handled.
+ * @returns An instance of {@link OnEventController}.
  *
  * @example
  * ```typescript
@@ -386,7 +470,7 @@ interface UseOnEventsOptions<E extends Event = Event> {
  * ```typescript
  * class MyElement extends LitElement {
  *   private eventHandler = useOnEvents(this, {
- *     types: [MyEvent],
+ *     types: ["MY_EVENT"],
  *     handler: (event) => console.log(event),
  *   });
  * }
@@ -395,31 +479,33 @@ interface UseOnEventsOptions<E extends Event = Event> {
 declare function useOnEvents<E extends Event = Event>(host: ReactiveElement, { types, handler }: UseOnEventsOptions): OnEventController<E>;
 
 /**
- * Interface for the {@link onQuery} decorator.
+ * Represents interface for the {@link onQuery} decorator.
  *
- * Supports both standard (TC39) and legacy experimental decorators.
+ * @remarks
+ * Supports both TC39 and legacy experimental decorators.
  *
- * @group queries
+ * @group Queries
  */
 interface OnQueryDecorator<D = unknown, R = unknown> {
     <This extends Interface<Omit<ReactiveElement, "renderRoot">>>(value: (this: This, data: D) => MaybePromise<R>, context: ClassMethodDecoratorContext<This>): void;
     (target: object, propertyKey: string | symbol, descriptor: PropertyDescriptor): void;
 }
 /**
- * Decorator that registers a Lit element method as a query handler for the given type.
+ * Decorator for Lit element methods that handle a specific query.
  *
- * The handler is registered when the host element connects to the DOM and unregistered when it disconnects.
+ * @remarks
+ * The handler is registered when the host connects and unregistered when it disconnects.
  *
- * @group queries
+ * @group Queries
  *
- * @param type - the query type to handle
- * @returns the decorator function
+ * @param type - Unique identifier of the query to handle.
+ * @returns A method decorator function.
  *
  * @example
  * ```typescript
  * class MyElement extends LitElement {
  *   @onQuery("GET_USER_NAME")
- *   public onGetUserName(data: QueryData) {
+ *   private onGetUserName(data: QueryData) {
  *     return "Alice";
  *   }
  * }
@@ -430,10 +516,11 @@ declare function onQuery<D = unknown, R = unknown>(type: QueryType): OnQueryDeco
 /**
  * Reactive controller that registers a query handler on the {@link QueryBus} for the host element's lifetime.
  *
+ * @remarks
  * The handler is registered when the host connects and unregistered when it disconnects.
- * When the IoC context is updated (container revision change), the handler is re-registered automatically.
+ * It automatically re-registers if the IoC container is updated.
  *
- * @group queries
+ * @group Queries
  */
 declare class OnQueryController<D = unknown, R = unknown> implements ReactiveController {
     private bus;
@@ -441,9 +528,9 @@ declare class OnQueryController<D = unknown, R = unknown> implements ReactiveCon
     private readonly type;
     private readonly handler;
     /**
-     * @param host - the host element
-     * @param type - the query type to handle
-     * @param handler - the query handler function
+     * @param host - The host element.
+     * @param type - Unique identifier of the query to handle.
+     * @param handler - The query handler function.
      */
     constructor(host: ReactiveElement, type: QueryType, handler: QueryHandler<D, R>);
     hostConnected(): void;
@@ -453,9 +540,9 @@ declare class OnQueryController<D = unknown, R = unknown> implements ReactiveCon
 }
 
 /**
- * Options for the {@link useOnQuery} hook.
+ * Represents options for the {@link useOnQuery} hook.
  *
- * @group queries
+ * @group Queries
  */
 interface UseOnQueryOptions<D = unknown, R = unknown> {
     /**
@@ -468,15 +555,15 @@ interface UseOnQueryOptions<D = unknown, R = unknown> {
     handler: QueryHandler<D, R>;
 }
 /**
- * Registers a query handler on the {@link QueryBus} for the host element's lifetime.
+ * Hook that registers a query handler for the host element's lifetime.
  *
- * @group queries
+ * @group Queries
  *
- * @param host - the host element
- * @param options - query handling options
- * @param options.type - the query type to handle
- * @param options.handler - the query handler function
- * @returns the query controller instance
+ * @param host - The host element.
+ * @param options - Query handling options.
+ * @param options.type - The query type to handle.
+ * @param options.handler - The query handler function.
+ * @returns An instance of {@link OnQueryController}.
  *
  * @example
  * ```typescript
@@ -491,280 +578,315 @@ interface UseOnQueryOptions<D = unknown, R = unknown> {
 declare function useOnQuery<D = unknown, R = unknown>(host: ReactiveElement, { type, handler }: UseOnQueryOptions<D, R>): OnQueryController<D, R>;
 
 /**
- * Interface for the IoC context value.
- *
- * @group context
- */
-interface IocContext {
-    /**
-     * The Inversify IoC container.
-     */
-    readonly container: Container;
-    /**
-     * Revision counter for cache invalidation.
-     */
-    readonly revision: number;
-    /**
-     * Function to force a revision update.
-     */
-    readonly nextRevision: () => number;
-}
-/**
- * Lit context for providing and consuming the IoC container.
+ * Lit context object for providing and consuming the container.
  *
- * @group context
+ * @group Context
  */
 declare const ContainerContext: {
-    __context__: IocContext;
+    __context__: Container;
 };
 
 /**
- * Options for the {@link IocProviderController}.
+ * Represents options for the {@link ContainerProvider}.
  *
- * @group provision
+ * @remarks
+ * Provide either an external `container` or managed creation `options`, but
+ * never both at the same time.
+ *
+ * @group Provision
  */
-interface IocProviderControllerOptions {
+interface ContainerProviderOptions {
     /**
-     * Optional existing container to use. If not provided, a new one will be created.
+     * External container instance to provide as-is.
+     *
+     * @remarks
+     * External containers are never activated, recreated, or disposed by this
+     * provider.
      */
-    container?: Container;
+    readonly container?: Container$1;
     /**
-     * Optional seed data to apply to the container.
+     * Managed container creation options.
+     *
+     * @remarks
+     * The managed container is created during provider construction without
+     * eager activation, activated when the host connects, disposed when it
+     * disconnects, and recreated on the next reconnect.
      */
-    seed?: AnyObject;
+    readonly options?: CreateContainerOptions;
 }
 /**
- * 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
+ * The provider supports two modes:
  *
- * It manages the lifecycle of the container and handles revision updates to notify consumers.
+ * - 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
+ * @group Provision
  */
-declare class IocProviderController<E extends ReactiveControllerHost & HTMLElement = ReactiveControllerHost & HTMLElement> implements ReactiveController {
-    private readonly host;
-    protected readonly provider: ContextProvider<typeof ContainerContext>;
-    protected readonly seed?: AnyObject;
-    protected revision: number;
+declare class ContainerProvider<E extends ReactiveControllerHost & HTMLElement = ReactiveControllerHost & HTMLElement> extends ContextProvider<typeof ContainerContext, E> implements ReactiveController {
+    protected readonly options: Maybe<CreateContainerOptions>;
+    protected destroyed: boolean;
     /**
-     * The managed Inversify IoC container.
-     */
-    container: Container;
-    /**
-     * @returns current {@link IocContext} value served to child consumers
-     */
-    get value(): IocContext;
-    /**
-     * @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 host - The host element.
+     * @param options - Provisioning options.
+     * @param options.container - External container instance to provide.
+     * @param options.options - Managed container creation options.
      */
-    constructor(host: E, { container, seed }?: IocProviderControllerOptions);
+    constructor(host: E, options: ContainerProviderOptions);
     hostConnected(): void;
     hostDisconnected(): void;
-    nextRevision(): number;
 }
 
 /**
- * Type definition for the ioc-provide decorator.
+ * Represents options for the {@link SubContainerProvider}.
  *
- * @group provision
+ * @group Provision
  */
-interface IocProviderDecorator<E extends ReactiveElement = ReactiveElement> {
-    <C extends Interface<Omit<ReactiveElement, "renderRoot">>, V extends IocProviderController<E>>(value: ClassAccessorDecoratorTarget<C, V>, context: ClassAccessorDecoratorContext<C, V>): void;
-    <K extends PropertyKey, Proto extends Interface<Omit<ReactiveElement, "renderRoot">>>(protoOrDescriptor: Proto, name?: K): FieldMustMatchProvidedType<Proto, K, IocProviderController<E>>;
+interface SubContainerProviderOptions {
+    /**
+     * Managed child-container creation options.
+     *
+     * @remarks
+     * The child container is created from the current parent context when the
+     * host connects, destroyed when the host disconnects, and recreated when the
+     * parent context changes or the host reconnects.
+     */
+    readonly options: {
+        /**
+         * List of service entries to bind to the container.
+         */
+        readonly entries: ReadonlyArray<Newable<object> | InjectableDescriptor>;
+        /**
+         * List of service identifiers to activate (get from container) immediately after binding.
+         */
+        readonly activate?: ReadonlyArray<ServiceIdentifier>;
+        /**
+         * Seed data to apply to the container before binding.
+         * Applied before entries are bound so that `@Inject(SEEDS_TOKEN)` works during activation.
+         */
+        readonly seeds?: SeedEntries;
+    };
 }
 /**
- * Decorator to provide an IoC container to child components.
+ * Provider that exposes a managed child container for the host element's lifetime.
  *
- * @group provision
+ * @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.
  *
- * @param options - provisioning options including container and seed data
- * @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 IOC provision controller instance
+ * @group Provision
  *
  * @example
  * ```typescript
- * class MyRootElement extends LitElement {
- *   @iocProvide({ seed: { someData: 'value' } })
- *   private ioc!: IocProviderController;
+ * class MyComponent extends LitElement {
+ *   private container = new SubContainerProvider(this, {
+ *     options: {
+ *       entries: [AuthService, UserService],
+ *       activate: [AuthService],
+ *       seeds: [[AuthService, { role: "admin" }]],
+ *     },
+ *   });
  * }
  * ```
  */
-declare function iocProvide<E extends ReactiveElement>({ container, seed, }?: IocProviderControllerOptions): IocProviderDecorator<E>;
-
-/**
- * @group general-types
- */
-type Callable<T> = () => T;
-
-/**
- * Options for the {@link InjectablesProviderController}.
- *
- * @group provision
- */
-interface InjectablesProviderControllerOptions {
+declare class SubContainerProvider<E extends ReactiveControllerHost & HTMLElement = ReactiveControllerHost & HTMLElement> extends ContextProvider<typeof ContainerContext, E> implements ReactiveController {
+    protected readonly consumer: ContextConsumer<typeof ContainerContext, E>;
+    protected readonly options: SubContainerProviderOptions["options"];
+    protected parent: Maybe<Container$1>;
+    protected destroyed: boolean;
     /**
-     * List of service entries to bind to the container.
-     */
-    entries: ReadonlyArray<Newable<object> | InjectableDescriptor>;
-    /**
-     * Target IoC context to bind injectables into.
-     * If not provided, uses the context from the nearest provider.
-     * Accepts a static {@link IocContext} reference or a resolver function.
+     * @param host - The host element.
+     * @param options - Provisioning options, including child entries, eager activations, and seeds.
      */
-    into?: IocContext | Callable<IocContext>;
+    constructor(host: E, options: SubContainerProviderOptions);
+    hostConnected(): void;
+    hostDisconnected(): void;
     /**
-     * List of service identifiers to activate (get from container) immediately after binding.
+     * Replaces the currently provided child container with a new one derived
+     * from the latest parent context.
      */
-    activate?: ReadonlyArray<ServiceIdentifier>;
+    protected createContainer(): void;
     /**
-     * Seed data to apply to the container before binding.
-     * Applied before entries are bound so that `@Inject(SEEDS_TOKEN)` works during activation.
+     * Destroys the currently provided child container.
      */
-    seeds?: SeedEntries;
+    protected destroyContainer(): void;
 }
+
 /**
- * Controller that binds a set of injectables to an IoC container when the host connects
- * and unbinds them when the host disconnects.
+ * Represents interface for the {@link containerProvide} decorator.
  *
- * When no `into` context is provided, the controller uses the nearest {@link IocProviderController}
- * ancestor via Lit context. Seeds are applied before entries so that `@Inject(SEEDS_TOKEN)`
- * works during service activation.
+ * @remarks
+ * Supports both TC39 and legacy experimental decorators.
  *
- * @group provision
+ * @group Provision
+ */
+interface ContainerProviderDecorator<E extends ReactiveElement = ReactiveElement> {
+    <C extends Interface<Omit<ReactiveElement, "renderRoot">>, V extends ContainerProvider<E>>(value: ClassAccessorDecoratorTarget<C, V>, context: ClassAccessorDecoratorContext<C, V>): void;
+    <K extends PropertyKey, Proto extends Interface<Omit<ReactiveElement, "renderRoot">>>(protoOrDescriptor: Proto, name?: K): FieldMustMatchProvidedType<Proto, K, ContainerProvider<E>>;
+}
+/**
+ * Decorator that provides an IoC container to child components.
+ *
+ * @remarks
+ * 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 - External container instance to provide.
+ * @param options.options - Managed container creation options.
+ * @returns An instance of {@link ContainerProviderDecorator}.
  *
  * @example
  * ```typescript
- * class MyComponent extends LitElement {
- *   private services = new InjectablesProviderController(this, {
- *     entries: [AuthService, UserService],
- *     activate: [AuthService],
- *     seeds: [[AuthService, { role: "admin" }]],
- *   });
+ * class MyRootElement extends LitElement {
+ *   @containerProvide({
+ *     options: {
+ *       seed: { someData: "value" },
+ *       entries: [LoggerService],
+ *     },
+ *   })
+ *   private containerProvider!: ContainerProvider;
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * class MyRootElement extends LitElement {
+ *   @containerProvide({ container: container })
+ *   private containerProvider!: ContainerProvider;
  * }
  * ```
  */
-declare class InjectablesProviderController<E extends ReactiveControllerHost & HTMLElement = ReactiveControllerHost & HTMLElement> implements ReactiveController {
-    private readonly host;
-    protected readonly consumer?: ContextConsumer<typeof ContainerContext, E>;
-    private readonly entries;
-    private readonly activate;
-    private readonly seeds;
-    private readonly into;
-    /**
-     * Tracks the context to which entries are currently bound, for correct cleanup on disconnect.
-     */
-    private boundContext;
-    /**
-     * @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
-     */
-    constructor(host: E, options: InjectablesProviderControllerOptions);
-    hostConnected(): void;
-    hostDisconnected(): void;
-    private bind;
-    private unbind;
-}
+declare function containerProvide<E extends ReactiveElement>(options: ContainerProviderOptions): ContainerProviderDecorator<E>;
 
 /**
- * Type for the {@link injectablesProvide} decorator.
+ * Represents type for the {@link subContainerProvide} decorator.
  *
- * Supports both standard (TC39) and legacy experimental decorators.
+ * @remarks
+ * Supports both TC39 and legacy experimental decorators.
  *
- * @group provision
+ * @group Provision
  */
-interface InjectablesProviderDecorator<T extends ReactiveElement = ReactiveElement> {
-    <C extends Interface<Omit<ReactiveElement, "renderRoot">>, V extends InjectablesProviderController<T>>(value: ClassAccessorDecoratorTarget<C, V>, context: ClassAccessorDecoratorContext<C, V>): void;
-    <K extends PropertyKey, Proto extends Interface<Omit<ReactiveElement, "renderRoot">>>(protoOrDescriptor: Proto, name?: K): FieldMustMatchProvidedType<Proto, K, InjectablesProviderController<T>>;
+interface SubContainerProviderDecorator<T extends ReactiveElement = ReactiveElement> {
+    <C extends Interface<Omit<ReactiveElement, "renderRoot">>, V extends SubContainerProvider<T>>(value: ClassAccessorDecoratorTarget<C, V>, context: ClassAccessorDecoratorContext<C, V>): void;
+    <K extends PropertyKey, Proto extends Interface<Omit<ReactiveElement, "renderRoot">>>(protoOrDescriptor: Proto, name?: K): FieldMustMatchProvidedType<Proto, K, SubContainerProvider<T>>;
 }
 /**
- * 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.
  *
- * Entries are bound when the host connects and unbound when it disconnects.
- * The decorated accessor or property holds the resulting {@link InjectablesProviderController} instance.
+ * @remarks
+ * 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
+ * @group Provision
  *
- * @param options - provisioning options
- * @returns injectables provider decorator instance
+ * @param options - Provisioning options.
+ * @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 services!: InjectablesProviderController<MyComponent>;
+ *   @subContainerProvide({
+ *     options: {
+ *       entries: [AuthService, UserService],
+ *       activate: [AuthService],
+ *     },
+ *   })
+ *   public containerProvider!: SubContainerProvider<MyComponent>;
  * }
  * ```
  */
-declare function injectablesProvide<E extends ReactiveElement = ReactiveElement>(options: InjectablesProviderControllerOptions): InjectablesProviderDecorator<E>;
+declare function subContainerProvide<E extends ReactiveElement = ReactiveElement>(options: SubContainerProviderOptions): SubContainerProviderDecorator<E>;
 
 /**
- * Binds a set of injectables to the nearest IoC container for the host element's lifetime.
+ * Represents options for the {@link useContainerProvision} hook.
+ *
+ * @group Provision
+ */
+type UseContainerProvisionOptions = ContainerProviderOptions;
+/**
+ * Hook that provides a container to the host element and its children.
  *
- * Entries are bound when the host connects and unbound when it disconnects.
+ * @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
+ * @group Provision
  *
- * @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
- * @returns the controller instance
+ * @param host - The host element.
+ * @param options - Provisioning options.
+ * @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 });
+ * }
+ * ```
  */
-declare function useInjectablesProvider<E extends ReactiveControllerHost & HTMLElement>(host: E, options: InjectablesProviderControllerOptions): InjectablesProviderController<E>;
+declare function useContainerProvision<E extends ReactiveControllerHost & HTMLElement>(host: E, options: UseContainerProvisionOptions): ContainerProvider<E>;
 
 /**
- * Options for the {@link useIocProvision} hook.
+ * Hook that provides a managed child container for the host element's lifetime.
  *
- * @group provision
- */
-interface UseIocProvisionOptions {
-    /**
-     * Optional existing container to use.
-     */
-    container?: Container;
-    /**
-     * Optional seed data to apply to the container.
-     */
-    seed?: AnyObject;
-}
-/**
- * Hook (controller) to provide an IoC container to the host element and its children.
+ * @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
+ * @group Provision
  *
- * @param host - the host element
- * @param options - provisioning options
- * @param options.container - optional existing container to use
- * @param options.seed - optional seed data to apply to the container
- * @returns ioc provision controller instance
+ * @param host - The host element.
+ * @param options - Provisioning options.
+ * @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],
+ *     },
+ *   });
  * }
  * ```
  */
-declare function useIocProvision<E extends ReactiveControllerHost & HTMLElement>(host: E, options?: UseIocProvisionOptions): IocProviderController<E>;
+declare function useSubContainerProvider<E extends ReactiveControllerHost & HTMLElement>(host: E, options: SubContainerProviderOptions): SubContainerProvider<E>;
 
-export { ContainerContext, InjectablesProviderController, IocProviderController, OnCommandController, OnEventController, OnQueryController, injectablesProvide, injection, iocProvide, onCommand, onEvent, onQuery, useInjectablesProvider, useInjection, useIocProvision, useOnCommand, useOnEvents, useOnQuery };
-export type { InjectablesProviderControllerOptions, InjectablesProviderDecorator, InjectionDecorator, InjectionOptions, IocProviderControllerOptions, IocProviderDecorator, OnCommandDecorator, OnEventDecorator, OnQueryDecorator, UseInjectionOptions, UseInjectionValue, UseIocProvisionOptions, UseOnCommandOptions, UseOnEventsOptions, UseOnQueryOptions };
+export { ContainerContext, ContainerProvider, OnCommandController, OnEventController, OnQueryController, SubContainerProvider, containerProvide, injection, onCommand, onEvent, onQuery, subContainerProvide, useContainer, useContainerProvision, useInjection, useOnCommand, useOnEvents, useOnQuery, useScope, useSubContainerProvider };
+export type { ContainerProviderDecorator, ContainerProviderOptions, InjectionDecorator, InjectionOptions, OnCommandDecorator, OnEventDecorator, OnQueryDecorator, SubContainerProviderDecorator, SubContainerProviderOptions, UseContainerProvisionOptions, UseContainerValue, UseInjectionOptions, UseInjectionValue, UseOnCommandOptions, UseOnEventsOptions, UseOnQueryOptions, UseScopeValue };