import type { IMailbox } from '../mailbox/IMailbox';
import type { IExternalAdapterOptions } from '../../core/composite/IExternalAdapterOptions';
import type { IMatrixContext } from './IMatrixContext';
import type { IComponentDescriptor } from './IComponentDescriptor';
import type { IChildDescriptor } from './IChildDescriptor';
/**
 * Result of createOrGetChild operation.
 *
 * Vision 21 Pillar 6: Lifecycle - createOrGet semantics.
 */
export interface ICreateOrGetResult {
    /** Mount path of the component */
    mount: string;
    /** True if a new component was created, false if existing was returned */
    created: boolean;
    /** True if an existing component was reused */
    reused: boolean;
}
/**
 * Runtime interface for UI Control Inversion pattern.
 *
 * The runtime is the ORCHESTRATOR that:
 * - Creates actors (components)
 * - Creates hosts (shells) if in browser
 * - Wires them together
 * - Returns mount paths to callers
 *
 * Actors NEVER instantiate other actors directly - they ask the runtime.
 * See: UI-CONTROL-INVERSION.md
 *
 * NOTE: This interface lives here (not in core/IMatrixRuntime.ts) to avoid
 * circular dependencies. All runtime implementations (MatrixRuntime,
 * MockRuntime, MatrixRuntime) implement this interface.
 */
export interface IMatrixRuntime {
    /**
     * Create a child component.
     *
     * This is the CORE method for UI Control Inversion:
     * - Actor calls runtime.createChild()
     * - Runtime creates the child actor
     * - Runtime creates the host (if browser)
     * - Runtime wires them together
     * - Runtime returns MOUNT PATH (not reference!)
     *
     * Instantiation mode (Vision 21 Pillar 6) determines behavior if mount exists:
     * - create_new (default): Create new, suffix with uuid if exists
     * - reuse_existing: Return existing mount if occupied
     * - singleton: Fail if exists
     * - replace: Destroy existing, create new
     * - create_unique: Always suffix with uuid
     *
     * @param parentContext - Parent's context
     * @param id - Child identifier
     * @param descriptor - Component class, props, and instantiation mode
     * @returns Mount path of created child (string, NOT reference!)
     */
    createChild(parentContext: IMatrixContext, id: string, descriptor: IComponentDescriptor): Promise<string>;
    /**
     * Create or get a child component (Vision 21 Pillar 6: createOrGet semantics).
     *
     * Joe Armstrong (Erlang): "whereis() before spawn() prevents duplicates"
     *
     * This is equivalent to createChild with instantiation='reuse_existing',
     * but returns additional metadata about whether the component was created.
     *
     * @param parentContext - Parent's context
     * @param id - Child identifier
     * @param descriptor - Component class and props
     * @returns Mount path and whether component was newly created
     */
    createOrGetChild?(parentContext: IMatrixContext, id: string, descriptor: IComponentDescriptor): Promise<ICreateOrGetResult>;
    /**
     * Remove and dispose a component by mount path.
     *
     * This is the PROPER way for actors to remove children:
     * - Actor calls runtime.remove(mount)
     * - Runtime disposes the actor
     * - Runtime cleans up tracking
     * - Actor never holds reference to child
     *
     * @param mount - Mount path of component to remove
     */
    remove(mount: string): Promise<void>;
    /**
     * Parse a template string into child descriptors.
     */
    parseTemplate(html: string): Promise<IChildDescriptor[]>;
    /**
     * Runtime type.
     */
    readonly type: 'headless' | 'browser';
    /**
     * Whether this runtime supports DOM operations.
     */
    readonly supportsDom: boolean;
    /**
     * Create an exclusive mailbox for a component.
     *
     * Each actor gets ONE mailbox for receiving messages (Carl Hewitt's Actor Model).
     * The mailbox provides:
     * - Exclusive ownership (only owner can receive)
     * - Serialized delivery (messages processed one at a time)
     * - Backpressure management
     *
     * @param mount - Mount path of the component (forms base of mailbox address)
     * @returns The component's exclusive mailbox
     */
    createMailbox(mount: string): IMailbox;
    /**
     * Register an external adapter for a dynamically created component.
     *
     * This allows Matrix components to "attach" to external hierarchies
     * where we DON'T control the lifecycle:
     * - Browser: Creates CustomElement wrapper
     * - File system: Creates file/directory binding
     * - Object system: Wraps existing instance
     * - Network: Creates socket/HTTP binding
     *
     * The RUNTIME decides HOW based on its environment.
     * The ACTOR just says "please bind this component externally".
     *
     * Pattern References:
     * - Erlang Ports: Wrapping external resources in process semantics
     * - Channel Adapter (EIP): Connecting external systems to messaging
     * - Anti-Corruption Layer (DDD): Isolating foreign domains
     * - Object-Capability Membranes (Miller): Capability-controlled wrappers
     *
     * @param id - Unique identifier for the adapter
     * @param componentClass - The Matrix component class to adapt
     * @param options - Environment-specific adapter options
     * @returns Adapter identifier (e.g., custom element tag, watch path), or undefined if not supported
     *
     * @example
     * // Actor code (environment-agnostic):
     * const adapterId = this._context.runtime.registerExternalAdapter?.(
     *   'my-counter',
     *   CounterComponent,
     *   { template: '<div>...</div>', styles: '...' }
     * );
     *
     * @remarks
     * - Browser runtime mode: Creates CustomElement, returns tag name
     * - MatrixRuntime: No-op, returns undefined
     * - FileSystemRuntime: Creates file watcher, returns watch path
     * - ObjectRuntime: Creates proxy wrapper, returns proxy id
     */
    registerExternalAdapter?(id: string, componentClass: new () => unknown, options?: IExternalAdapterOptions): string | undefined;
    /**
     * Unregister an external adapter.
     *
     * Cleans up the environment-specific binding.
     * Called automatically when component is disposed.
     *
     * @param id - The adapter identifier returned from registerExternalAdapter
     */
    unregisterExternalAdapter?(id: string): void;
    /**
     * Check if an external adapter is registered.
     *
     * @param id - The adapter identifier
     * @returns true if registered, false otherwise
     */
    hasExternalAdapter?(id: string): boolean;
    /**
     * Check if dynamic component compilation is allowed.
     *
     * SECURITY: new Function() is essentially eval() - allows arbitrary code execution.
     * This should only be true in development/testing environments.
     *
     * Mark Miller: "Any code that reaches _compileDynamicComponent runs with full privileges."
     *
     * @returns true if dynamic compilation is allowed, false otherwise
     */
    isDynamicCompilationAllowed?(): boolean;
    /**
     * Get the root context for this runtime.
     * Used by MatrixDSLHost to derive child contexts.
     */
    getRootContext?(): IMatrixContext;
}
//# sourceMappingURL=IMatrixRuntime.d.ts.map