storion 0.2.3 → 0.4.0

package/dist/types.d.ts

@@ -1,3 +1,15 @@
+export declare const STORION_TYPE: unique symbol;
+/**
+ * Kind identifiers for Storion objects.
+ * Used with STORION_SYMBOL for runtime type discrimination.
+ */
+export type StorionKind = "store.spec" | "store.action" | "container" | "store" | "focus" | "store.context" | "selector.context" | "async.meta";
+/**
+ * Base interface for all Storion objects with runtime type discrimination.
+ */
+export interface StorionObject<K extends StorionKind = StorionKind> {
+    readonly [STORION_TYPE]: K;
+}
 /**
  * Storion - Type-safe reactive state management
  *
@@ -6,16 +18,14 @@
 /**
  * Base constraint for state objects.
  */
-export interface StateBase {
-    [key: string]: unknown;
-}
+export type StateBase = object | Record<string, unknown>;
 /**
  * Base constraint for actions.
  */
 export interface ActionsBase {
     [key: string]: (...args: any[]) => any;
 }
-export type EqualityShorthand = "strict" | "shallow" | "deep";
+export type EqualityShorthand = "strict" | "shallow" | "shallow2" | "shallow3" | "deep";
 /**
  * Equality strategies for change detection.
  */
@@ -26,6 +36,120 @@ export type Equality<T = unknown> = EqualityShorthand | ((a: T, b: T) => boolean
 export type EqualityMap<T> = {
     [K in keyof T]?: Equality<T[K]>;
 };
+/**
+ * Extracts nested object paths as dot-notation strings.
+ * Stops at arrays (no index support).
+ *
+ * @example
+ * type State = { profile: { name: string; address: { city: string } } };
+ * type P = StatePath<State>; // "profile" | "profile.name" | "profile.address" | "profile.address.city"
+ */
+export type StatePath<T, Prefix extends string = ""> = T extends object ? T extends unknown[] ? never : {
+    [K in keyof T & string]: NonNullable<T[K]> extends object ? NonNullable<T[K]> extends unknown[] ? `${Prefix}${K}` : `${Prefix}${K}` | StatePath<NonNullable<T[K]>, `${Prefix}${K}.`> : `${Prefix}${K}`;
+}[keyof T & string] : never;
+/**
+ * Gets the type at a nested path.
+ *
+ * @example
+ * type State = { profile: { address: { city: string } } };
+ * type City = PathValue<State, "profile.address.city">; // string
+ */
+export type PathValue<T, P extends string> = P extends `${infer K}.${infer Rest}` ? K extends keyof T ? PathValue<NonNullable<T[K]>, Rest> : never : P extends keyof T ? T[P] : never;
+/**
+ * Non-nullable type utility.
+ */
+export type NonNullish<TValue, TFlag extends true | false = true> = TFlag extends true ? Exclude<TValue, undefined | null> : TValue;
+/**
+ * Focus change event payload.
+ */
+export interface FocusChangeEvent<T> {
+    next: T;
+    prev: T;
+}
+/**
+ * Focus options for configuring getter/setter behavior.
+ *
+ * @example
+ * // With fallback for nullable values
+ * const focus = ctx.focus("profile", {
+ *   fallback: () => ({ name: "Guest" })
+ * });
+ *
+ * @example
+ * // With custom equality for change detection
+ * const focus = ctx.focus("items", {
+ *   equality: "shallow"
+ * });
+ */
+export interface FocusOptions<T> {
+    /**
+     * Fallback factory for when the focused value is nullish.
+     * Applied to both getter (returns fallback) and setter (reducer receives fallback).
+     */
+    fallback?: () => NonNullish<T>;
+    /**
+     * Equality strategy for change detection in on() listener.
+     * Defaults to strict equality (===).
+     */
+    equality?: Equality<T>;
+}
+/**
+ * Focus tuple: [getter, setter] with an on() method for subscribing to changes.
+ *
+ * @example
+ * const [getName, setName] = ctx.focus("profile.name");
+ *
+ * // Get current value
+ * const name = getName();
+ *
+ * // Set value directly
+ * setName("Jane");
+ *
+ * // Set value with reducer (returns new value)
+ * setName(prev => prev.toUpperCase());
+ *
+ * // Set value with produce (immer-style, mutate draft)
+ * setName(draft => { draft.nested = "value"; });
+ *
+ * // Listen to changes
+ * const unsubscribe = ctx.focus("profile.name").on(({ next, prev }) => {
+ *   console.log(`Name changed from ${prev} to ${next}`);
+ * });
+ */
+export type Focus<TValue> = [
+    /** Get the current value at the focused path */
+    getter: () => TValue,
+    /**
+     * Set the value at the focused path.
+     * - Direct value: `set(newValue)`
+     * - Reducer: `set(prev => newValue)` - returns new value
+     * - Produce: `set(draft => { draft.x = y })` - immer-style mutation, no return
+     */
+    setter: (valueOrReducerOrProduce: TValue | ((prev: TValue) => TValue | void)) => void
+] & {
+    readonly [STORION_TYPE]: "focus";
+    /**
+     * Subscribe to changes at the focused path.
+     * Uses the configured equality to determine if value has changed.
+     *
+     * @param listener - Called with { next, prev } when value changes
+     * @returns Unsubscribe function
+     */
+    on(listener: (event: FocusChangeEvent<TValue>) => void): VoidFunction;
+    /**
+     * Create a new Focus relative to the current path.
+     *
+     * @param relativePath - Dot-notation path relative to current focus
+     * @param options - Focus options for the new focus
+     * @returns A new Focus at the combined path
+     *
+     * @example
+     * const userFocus = focus("user");
+     * const addressFocus = userFocus.to("address");
+     * const cityFocus = userFocus.to("address.city");
+     */
+    to<TChild>(relativePath: string, options?: FocusOptions<TChild>): Focus<TChild>;
+};
 /**
  * Controls when a store instance is automatically disposed.
  *
@@ -96,14 +220,32 @@ export type ReactiveActions<TActions extends ActionsBase> = {
     [K in keyof TActions]: ReactiveAction<TActions, K>;
 };
 /**
- * Store specification (definition).
+ * Store specification (definition) that is also a factory function.
  * A spec describes HOW to create a store instance - it holds no state.
+ *
+ * Can be called directly as a factory: `spec(resolver) => instance`
+ *
+ * @example
+ * ```ts
+ * const counterSpec = store({ count: state(0) });
+ *
+ * // Use with container (recommended)
+ * const instance = container.get(counterSpec);
+ *
+ * // Or call directly as factory
+ * const instance = counterSpec(resolver);
+ * ```
  */
-export interface StoreSpec<TState extends StateBase = StateBase, TActions extends ActionsBase = ActionsBase> {
-    /** Store name for debugging */
-    readonly name: string;
+export interface StoreSpec<TState extends StateBase = StateBase, TActions extends ActionsBase = ActionsBase> extends StorionObject<"store.spec"> {
+    /** Store display name for debugging (renamed from 'name' since that's a reserved function property) */
+    readonly displayName: string;
     /** Store options (state, setup, lifetime, etc.) */
     readonly options: StoreOptions<TState, TActions>;
+    /**
+     * Factory function - creates a new store instance.
+     * Called by container/resolver internally.
+     */
+    (resolver: Resolver): StoreInstance<TState, TActions>;
 }
 /**
  * A reusable mixin for store setup.
@@ -129,10 +271,61 @@ export type StoreMixin<TState extends StateBase, TResult, TArgs extends unknown[
  *   }, 0);
  */
 export type SelectorMixin<TResult, TArgs extends unknown[] = []> = (context: SelectorContext, ...args: TArgs) => TResult;
+/**
+ * Tuple returned by get() with both array destructuring and named properties.
+ *
+ * @example
+ * // Array destructuring
+ * const [state, actions] = get(counterSpec);
+ *
+ * // Named properties
+ * const tuple = get(counterSpec);
+ * tuple.state.count;
+ * tuple.actions.increment();
+ */
+export type StoreTuple<S extends StateBase, A extends ActionsBase> = readonly [
+    Readonly<S>,
+    A
+] & {
+    readonly state: Readonly<S>;
+    readonly actions: A;
+};
+/**
+ * Update function with action creator.
+ *
+ * Can be called directly to update state, or use `.action()` to create
+ * action functions that wrap updates.
+ */
+export interface StoreUpdate<TState extends StateBase> {
+    /**
+     * Update state using Immer-style updater function.
+     */
+    (updater: (draft: TState) => void): void;
+    /**
+     * Update state with partial object (shallow merge).
+     */
+    (partial: Partial<TState>): void;
+    /**
+     * Create an action function that wraps an updater.
+     * Throws error if the updater returns a PromiseLike (async not supported).
+     *
+     * @example
+     * // No arguments
+     * increment: update.action(draft => {
+     *   draft.count++;
+     * }),
+     *
+     * // With arguments
+     * addItem: update.action((draft, name: string, price: number) => {
+     *   draft.items.push({ name, price });
+     * }),
+     */
+    action<TArgs extends unknown[]>(updater: (draft: TState, ...args: TArgs) => void): (...args: TArgs) => void;
+}
 /**
  * Context provided to the setup() function.
  */
-export interface StoreContext<TState extends StateBase> {
+export interface StoreContext<TState extends StateBase = StateBase> extends StorionObject<"store.context"> {
     /**
      * Mutable reactive state proxy.
      * Writes trigger subscriber notifications.
@@ -141,30 +334,93 @@ export interface StoreContext<TState extends StateBase> {
     readonly state: TState;
     /**
      * Get another store's state and actions.
-     * Returns [readonlyState, actions] tuple.
+     * Returns tuple with both array destructuring and named properties.
      * Creates dependency - store is created if not exists.
      *
-     * Note: Returns limited tuple, not full StoreInstance.
-     * You cannot access id, subscribe(), or dispose().
+     * @example
+     * // Array destructuring
+     * const [state, actions] = get(counterSpec);
+     *
+     * // Named properties
+     * const tuple = get(counterSpec);
+     * tuple.state.count;
      */
-    resolve<S extends StateBase, A extends ActionsBase>(spec: StoreSpec<S, A>): readonly [Readonly<S>, A];
+    get<S extends StateBase, A extends ActionsBase>(spec: StoreSpec<S, A>): StoreTuple<S, A>;
     /**
-     * Update state using Immer-style updater function.
+     * Get a service or factory instance.
+     * Creates and caches the instance using the factory function.
+     * Returns the instance directly (not a tuple).
+     *
+     * @example
+     * const db = get(indexedDBService);
+     * await db.users.getAll();
+     */
+    get<T>(factory: (...args: any[]) => T): T;
+    /**
+     * Create a child store instance that is automatically disposed
+     * when the parent store is disposed.
+     *
+     * Unlike `get()`, this returns the full StoreInstance with access to
+     * id, subscribe(), dispose(), etc.
+     *
+     * Use this when you need a store with the same lifecycle as the parent,
+     * or when you need full instance access.
+     *
+     * @example
+     * setup: (ctx) => {
+     *   // Create a child store - disposed when parent disposes
+     *   const childInstance = ctx.create(childSpec);
+     *
+     *   return {
+     *     getChildState: () => childInstance.state,
+     *     disposeChild: () => childInstance.dispose(),
+     *   };
+     * }
+     */
+    create<S extends StateBase, A extends ActionsBase>(spec: StoreSpec<S, A>): StoreInstance<S, A>;
+    /**
+     * Create a service or factory instance that is automatically disposed
+     * when the parent store is disposed (if the instance has a dispose method).
+     *
+     * Unlike `get()` which caches instances, `create()` always creates fresh instances.
      *
      * @example
+     * setup: (ctx) => {
+     *   // Create a fresh service instance - disposed with parent
+     *   const db = ctx.create(indexedDBService);
+     *
+     *   return {
+     *     clearData: () => db.clearAll(),
+     *   };
+     * }
+     */
+    create<T>(factory: (...args: any[]) => T): T;
+    /**
+     * Update state using Immer-style updater function or partial object.
+     *
+     * Also provides `.action()` to create action functions that wrap updates.
+     *
+     * @example
+     * // Direct update with updater function
      * update(draft => {
      *   draft.items.push({ id: 1, name: 'New Item' });
      *   draft.count++;
      * });
-     */
-    update(updater: (draft: TState) => void): void;
-    /**
-     * Update state with partial object (shallow merge).
      *
-     * @example
+     * // Direct update with partial object
      * update({ count: 10, name: 'Updated' });
+     *
+     * // Create action with update.action()
+     * increment: update.action(draft => {
+     *   draft.count++;
+     * }),
+     *
+     * // Action with arguments
+     * addItem: update.action((draft, name: string) => {
+     *   draft.items.push({ id: Date.now(), name });
+     * }),
      */
-    update(partial: Partial<TState>): void;
+    update: StoreUpdate<TState>;
     /**
      * Check if state has been modified since setup completed.
      *
@@ -183,15 +439,46 @@ export interface StoreContext<TState extends StateBase> {
      */
     reset(): void;
     /**
-     * Use a mixin to compose reusable logic.
+     * Apply a mixin to compose reusable logic.
      * Mixins receive the same context and can return actions or values.
      * Only callable during setup phase.
      *
      * @example
-     * const counter = ctx.use(counterMixin);
-     * const multiplier = ctx.use(multiplyMixin, 2);
+     * const counter = ctx.mixin(counterMixin);
+     * const multiplier = ctx.mixin(multiplyMixin, 2);
+     */
+    mixin<TResult, TArgs extends unknown[]>(mixin: StoreMixin<TState, TResult, TArgs>, ...args: TArgs): TResult;
+    /**
+     * Create a lens-like accessor for a nested state path.
+     * Returns a [getter, setter] tuple with an on() method for subscribing to changes.
+     *
+     * @example
+     * // Basic usage - get/set value
+     * const [getName, setName] = focus("profile.name");
+     * const name = getName();
+     * setName("Jane");
+     *
+     * // With reducer
+     * setName(prev => prev.toUpperCase());
+     *
+     * // With fallback for nullable values
+     * const [getProfile, setProfile] = focus("profile", {
+     *   fallback: () => ({ name: "Guest" })
+     * });
+     *
+     * // Subscribe to changes
+     * const unsubscribe = focus("profile.name").on(({ next, prev }) => {
+     *   console.log(`Changed from ${prev} to ${next}`);
+     * });
+     *
+     * // Can be returned as actions
+     * return { nameFocus: focus("name"), profileFocus: focus("profile") };
      */
-    use<TResult, TArgs extends unknown[]>(mixin: StoreMixin<TState, TResult, TArgs>, ...args: TArgs): TResult;
+    focus<P extends StatePath<TState>>(path: P): Focus<PathValue<TState, P>>;
+    focus<P extends StatePath<TState>>(path: P, options: FocusOptions<PathValue<TState, P>> & {
+        fallback: () => NonNullish<PathValue<TState, P>>;
+    }): Focus<NonNullish<PathValue<TState, P>>>;
+    focus<P extends StatePath<TState>>(path: P, options: FocusOptions<PathValue<TState, P>>): Focus<PathValue<TState, P>>;
 }
 /**
  * Options for defining a store.
@@ -277,7 +564,7 @@ export interface StoreOptions<TState extends StateBase, TActions extends Actions
  * Created and managed by the container.
  * Provides access to state, actions, and lifecycle management.
  */
-export interface StoreInstance<TState extends StateBase = StateBase, TActions extends ActionsBase = ActionsBase> {
+export interface StoreInstance<TState extends StateBase = StateBase, TActions extends ActionsBase = ActionsBase> extends StorionObject<"store"> {
     /** Unique identifier for this instance */
     readonly id: string;
     /** The store specification that created this instance */
@@ -286,7 +573,7 @@ export interface StoreInstance<TState extends StateBase = StateBase, TActions ex
     readonly state: Readonly<TState>;
     /** Bound actions with reactive last() method */
     readonly actions: ReactiveActions<TActions>;
-    /** Store instances this store depends on (via resolve() in setup) */
+    /** Store instances this store depends on (via get() in setup) */
     readonly deps: readonly StoreInstance<any, any>[];
     /**
      * Subscribe to state changes.
@@ -380,79 +667,214 @@ export interface StoreInstance<TState extends StateBase = StateBase, TActions ex
     _subscribeInternal<K extends keyof TState>(propKey: K | string, listener: () => void): VoidFunction;
 }
 /**
- * Middleware function for intercepting store creation.
+ * Container options.
+ */
+export interface ContainerOptions {
+    /** Auto dispose options for all stores */
+    autoDispose?: AutoDisposeOptions;
+    /** Middleware chain for intercepting store creation */
+    middleware?: StoreMiddleware[];
+}
+/**
+ * Factory function that creates an instance using the resolver.
+ * The factory itself is used as the cache key (by reference).
  *
- * Middleware can:
- * - Modify the spec before creation
- * - Call next() to get the instance
- * - Wrap or modify the instance after creation
+ * StoreSpec is a specialized factory that returns StoreInstance.
+ */
+export type Factory<T = any> = (resolver: Resolver) => T;
+/**
+ * Context passed to generic middleware functions (for any factory).
+ */
+export interface MiddlewareContext<T = any> {
+    /** The factory being invoked (StoreSpec or plain factory) */
+    readonly factory: Factory<T>;
+    /** The resolver instance */
+    readonly resolver: Resolver;
+    /** Call the next middleware or the factory itself */
+    readonly next: () => T;
+    /**
+     * Display name for debugging.
+     * - For stores: spec.displayName
+     * - For factories: factory.displayName ?? factory.name ?? undefined
+     */
+    readonly displayName: string | undefined;
+}
+/**
+ * Context passed to store middleware functions.
+ * Unlike MiddlewareContext, `spec` is always present.
+ */
+export interface StoreMiddlewareContext<S extends StateBase = StateBase, A extends ActionsBase = ActionsBase> extends MiddlewareContext<StoreInstance<S, A>> {
+    /** The store spec being invoked */
+    readonly spec: StoreSpec<S, A>;
+    /** Store display name (always present for stores) */
+    readonly displayName: string;
+}
+/**
+ * Generic middleware function for intercepting any factory creation.
+ * Use for resolver middleware that handles both stores and plain factories.
  *
  * @example
- * // Logging middleware
- * const loggingMiddleware: StoreMiddleware = (spec, next) => {
- *   console.log(`Creating store: ${spec.name}`);
- *   const instance = next(spec);
- *   console.log(`Created store: ${instance.id}`);
- *   return instance;
+ * ```ts
+ * const loggingMiddleware: Middleware = (ctx) => {
+ *   if (ctx.displayName) {
+ *     console.log("Creating:", ctx.displayName);
+ *   }
+ *   return ctx.next();
  * };
+ * ```
+ */
+export type Middleware = <T>(ctx: MiddlewareContext<T>) => T;
+/**
+ * Store-specific middleware function.
+ * Use for container middleware where you always work with stores.
+ * The context always has `spec` available.
  *
  * @example
- * // Wrap actions with error boundary
- * const errorBoundaryMiddleware: StoreMiddleware = (spec, next) => {
- *   const instance = next(spec);
- *   // Wrap actions here if needed
+ * ```ts
+ * const loggingMiddleware: StoreMiddleware = (ctx) => {
+ *   console.log(`Creating store: ${ctx.displayName}`);
+ *   const instance = ctx.next();
+ *   console.log(`Created: ${instance.id}`);
  *   return instance;
  * };
+ * ```
  */
-export type StoreMiddleware = <S extends StateBase, A extends ActionsBase>(spec: StoreSpec<S, A>, next: (spec: StoreSpec<S, A>) => StoreInstance<S, A>) => StoreInstance<S, A>;
+export type StoreMiddleware = <S extends StateBase = StateBase, A extends ActionsBase = ActionsBase>(ctx: StoreMiddlewareContext<S, A>) => StoreInstance<S, A>;
 /**
- * Container options.
+ * Options for creating a resolver.
  */
-export interface ContainerOptions {
-    /** Default lifetime for stores */
-    defaultLifetime?: Lifetime;
-    /** Default equality for stores */
-    defaultEquality?: Equality;
-    /** Middleware chain for intercepting store creation */
-    middleware?: StoreMiddleware[];
+export interface ResolverOptions {
+    /** Middleware to apply to factory creation */
+    middleware?: Middleware[];
+    /** Parent resolver for hierarchical lookup */
+    parent?: Resolver;
 }
 /**
- * Resolver interface to get store instances.
- * StoreContainer implements this interface.
+ * Resolver interface for factory-based dependency injection.
+ * Provides caching, override support, and scoped resolvers.
+ *
+ * StoreContainer extends this with store-specific lifecycle methods.
  */
-export interface StoreResolver {
+export interface Resolver {
     /**
-     * Get a store instance by spec.
-     * First call creates instance, subsequent calls return cached.
+     * Get or create a cached instance from a factory.
+     * Returns the same instance on subsequent calls.
      */
-    get<S extends StateBase, A extends ActionsBase>(spec: StoreSpec<S, A>): StoreInstance<S, A>;
+    get<T>(factory: Factory<T>): T;
     /**
-     * Get a store instance by its unique ID.
+     * Create a fresh instance from a factory (bypasses cache).
      */
-    get(id: string): StoreInstance<any, any> | undefined;
+    create<T>(factory: Factory<T>): T;
     /**
-     * Check if a store instance exists.
+     * Override a factory with a custom implementation.
+     * Useful for testing or environment-specific behavior.
+     * Clears the cached instance if one exists.
      */
-    has(spec: StoreSpec<any, any>): boolean;
+    set<T>(factory: Factory<T>, override: Factory<T>): void;
+    /**
+     * Check if a factory has a cached instance.
+     */
+    has(factory: Factory): boolean;
+    /**
+     * Get a cached instance if it exists, otherwise return undefined.
+     * Does NOT create the instance if not cached.
+     */
+    tryGet<T>(factory: Factory<T>): T | undefined;
+    /**
+     * Delete a cached instance.
+     * If the instance has a `dispose()` method, it will be called.
+     * Returns true if an instance was deleted.
+     */
+    delete(factory: Factory): boolean;
+    /**
+     * Clear all cached instances.
+     * Calls `dispose()` on each instance that has the method.
+     */
+    clear(): void;
+    /**
+     * Create a child resolver that inherits from this resolver.
+     * Child can override factories without affecting parent.
+     */
+    scope(options?: ResolverOptions): Resolver;
 }
+export type AutoDisposeOptions = {
+    /** Grace period in ms before disposing the store (default: 100) */
+    gracePeriodMs?: number;
+};
 /**
- * Store container - manages store instances.
+ * Store container - manages store instances with resolver pattern.
  *
  * The container is responsible for:
  * - Creating instances on first access (lazy)
  * - Caching instances (singleton per spec)
  * - Resolving dependencies between stores
  * - Managing lifetime and disposal
+ * - Supporting DI via set() overrides
+ * - Scoped containers via scope()
+ *
+ * Note: StoreContainer has store-specific method signatures.
+ * For generic factory DI, use createResolver() instead.
  */
-export interface StoreContainer extends StoreResolver {
+export interface StoreContainer extends StorionObject<"container"> {
+    /**
+     * Get a store instance by spec (cached).
+     * First call creates instance, subsequent calls return cached.
+     */
+    get<S extends StateBase, A extends ActionsBase>(spec: StoreSpec<S, A>): StoreInstance<S, A>;
+    /**
+     * Get a service or factory instance (cached).
+     * Returns the instance directly (not a StoreInstance).
+     *
+     * @example
+     * const db = container.get(indexedDBService);
+     * await db.users.getAll();
+     */
+    get<T>(factory: Factory<T>): T;
+    /**
+     * Get a store instance by its unique ID.
+     */
+    get(id: string): StoreInstance<any, any> | undefined;
+    /**
+     * Create a fresh store instance (bypasses cache).
+     * Useful for child stores or temporary instances.
+     */
+    create<S extends StateBase, A extends ActionsBase>(spec: StoreSpec<S, A>): StoreInstance<S, A>;
+    /**
+     * Create a fresh factory instance (bypasses cache).
+     * Returns the instance directly.
+     */
+    create<T>(factory: Factory<T>): T;
+    /**
+     * Override a spec with a custom implementation.
+     * Useful for testing or environment-specific behavior.
+     */
+    set<S extends StateBase, A extends ActionsBase>(spec: StoreSpec<S, A>, override: StoreSpec<S, A>): void;
     /**
-     * Dispose all cached instances.
+     * Check if a store instance is cached.
+     */
+    has(spec: StoreSpec<any, any>): boolean;
+    /**
+     * Get cached instance if exists, otherwise undefined.
+     * Does NOT create the instance.
+     */
+    tryGet<S extends StateBase, A extends ActionsBase>(spec: StoreSpec<S, A>): StoreInstance<S, A> | undefined;
+    /**
+     * Remove a cached instance.
+     */
+    delete(spec: StoreSpec<any, any>): boolean;
+    /**
+     * Clear all cached instances (disposes them).
      */
     clear(): void;
     /**
      * Dispose a specific store instance.
      */
     dispose(spec: StoreSpec<any, any>): boolean;
+    /**
+     * Create a child container that inherits from this one.
+     * Child can override specs without affecting parent.
+     */
+    scope(options?: ContainerOptions): StoreContainer;
     /**
      * Subscribe to store creation events.
      */
@@ -468,25 +890,70 @@ export interface StoreContainer extends StoreResolver {
  * Provides access to stores within a selector function.
  * Returns tuple [readonlyState, actions] with tracking proxy.
  */
-export interface SelectorContext {
+export interface SelectorContext extends StorionObject<"selector.context"> {
     /**
      * Get a store's state and actions.
      *
-     * Returns a tracking proxy that records property access
-     * for fine-grained re-render optimization.
+     * Returns tuple with both array destructuring and named properties.
+     * Includes tracking proxy for fine-grained re-render optimization.
+     *
+     * @example
+     * // Array destructuring
+     * const [state, actions] = get(counterSpec);
+     *
+     * // Named properties
+     * const tuple = get(counterSpec);
+     * tuple.state.count;
+     * tuple.actions.increment();
      *
      * @param spec - Store specification
-     * @returns Tuple of [trackingState, actions]
+     * @returns Tuple of [trackingState, actions] with .state and .actions props
+     */
+    get<S extends StateBase, A extends ActionsBase>(spec: StoreSpec<S, A>): StoreTuple<S, A>;
+    /**
+     * Get a service or factory instance.
+     * Creates and caches the instance using the factory function.
+     * Returns the instance directly (not a tuple).
+     *
+     * @example
+     * const db = get(indexedDBService);
+     * await db.users.getAll();
      */
-    resolve<S extends StateBase, A extends ActionsBase>(spec: StoreSpec<S, A>): readonly [Readonly<S>, A];
+    get<T>(factory: (...args: any[]) => T): T;
     /**
-     * Use a mixin to compose reusable selector logic.
+     * Apply a mixin to compose reusable selector logic.
      * Mixins receive the same context and can return computed values.
      *
      * @example
-     * const total = ctx.use(sumMixin, [store1, store2]);
+     * const total = ctx.mixin(sumMixin, [store1, store2]);
+     */
+    mixin<TResult, TArgs extends unknown[]>(mixin: SelectorMixin<TResult, TArgs>, ...args: TArgs): TResult;
+    /**
+     * Unique identifier for this selector context (per component instance).
+     * Useful for scoping operations with trigger().
+     *
+     * @example
+     * const { data } = useStore(({ get, id }) => {
+     *   const store = get(dataStore);
+     *   // Each component instance gets unique scope
+     *   trigger(id, store.actions.dispatch, [params], params);
+     *   return { data: store.state.data };
+     * });
+     */
+    readonly id: object;
+    /**
+     * Run a callback once when the component mounts.
+     * The callback is executed immediately during render (before paint).
+     *
+     * @example
+     * useStore(({ get, once }) => {
+     *   const mutation = get(submitStore);
+     *   // Reset mutation state on mount
+     *   once(() => mutation.actions.reset());
+     *   return mutation;
+     * });
      */
-    use<TResult, TArgs extends unknown[]>(mixin: SelectorMixin<TResult, TArgs>, ...args: TArgs): TResult;
+    once(callback: () => void): void;
 }
 /**
  * Selector function type.