smart-lifecycle 0.1.1

package/dist/rendering/render-engine-factory.js

@@ -0,0 +1,225 @@
+import { SkeletonRenderer } from './skeleton/skeleton-renderer.js';
+import { SkeletonValidator } from './skeleton/skeleton-validator.js';
+import { TemplateProviderFactory } from './templates/template-provider.factory.js';
+import { BindingResolver } from './bindings/binding-resolver.js';
+import { HostProjector } from './expression-parser/host-projector.js';
+import { ErrorRenderer } from './errors/error-renderer.js';
+import { RenderPipeline } from './pipeline/render-pipeline.js';
+import { RenderEngine } from './render-engine.js';
+import { DomContextFactory } from './dom-context/dom-context-factory.js';
+import { BrowserDomAdapter } from './dom/browser-dom-adapter.js';
+import { TemplateCompilationCache } from './templates/template-compilation-cache.js';
+import { TemplateAnalyzer } from './templates/template-analyzer.js';
+import { TemplateCompiler } from './templates/template-compiler.js';
+import { ComponentInstanceRegistry } from '../core/component-instance-registry.js';
+import { ComponentMetadataRegistry } from '../core/component-metadata-registry.js';
+import { DomContextHostResolver } from './host-resolver/dom-context-host-resolver.js';
+import { HostProjectionRegistry } from './host-projection/host-projection.registry.js';
+/**
+ * Implements the responsibility of creating RenderEngine instances with standard dependencies.
+ *
+ * @description
+ * Creates RenderEngine instances with standard dependencies.
+ * Uses composition to wire all modules together properly.
+ *
+ * @architecture
+ * **Dependency Graph:**
+ * ```
+ * RenderEngine
+ * ├── ISkeletonRenderer (SkeletonRenderer)
+ * ├── IRenderPipeline (RenderPipeline)
+ * │   ├── IServiceProvider
+ * │   ├── ITemplateProvider (TemplateProvider)
+ * │   ├── ITemplateCompiler (inline object)
+ * │   │   ├── IHostProjector (HostProjector)
+ * │   │   └── IBindingResolver (BindingResolver)
+ * │   └── IErrorRenderer (ErrorRenderer)
+ * └── IDomContextFactory (DomContextFactory)
+ * ```
+ */
+export class RenderEngineFactory {
+    /**
+     * Creates a RenderEngine with all dependencies properly configured
+     *
+     * @param serviceProvider - Optional service provider for DI
+     * @returns RenderEngine instance ready for use
+     *
+     * @example
+     * ```typescript
+     * // Default configuration
+     * const factory = new RenderEngineFactory();
+     * const renderEngine = factory.create();
+     *
+     * // With custom service provider
+     * const renderEngine = factory.create(customServices);
+     * ```
+     */
+    create(serviceProvider) {
+        const domAdapter = this.createDomAdapter();
+        const metadataSource = this.createMetadataSource();
+        const hostProjectionRegistry = this.resolveHostProjectionRegistry(serviceProvider);
+        const skeletonRenderer = this.createSkeletonRenderer(domAdapter);
+        const bindingResolver = this.createBindingResolver(metadataSource);
+        const hostProjector = this.createHostProjector(domAdapter, hostProjectionRegistry);
+        const errorHandler = this.createErrorHandler(domAdapter);
+        const domContextFactory = this.createDomContextFactory();
+        const templateCache = this.createTemplateCache();
+        const templateAnalyzer = this.createTemplateAnalyzer();
+        const hostResolver = this.createHostResolver();
+        const templateCompiler = this.createTemplateCompiler(domAdapter, hostProjector, bindingResolver, metadataSource, hostProjectionRegistry);
+        // Register framework services in the service provider for lifecycle managers
+        if (serviceProvider) {
+            this.registerFrameworkServices(serviceProvider, {
+                domAdapter,
+                bindingResolver,
+                templateCompiler,
+                hostResolver
+            });
+        }
+        const renderPipeline = this.createRenderPipeline(serviceProvider, templateCompiler, errorHandler);
+        const templateProvider = this.createTemplateProvider(hostProjectionRegistry);
+        return this.createRenderEngine(skeletonRenderer, renderPipeline, domContextFactory, templateCache, templateAnalyzer, this.createInstanceRegistry(), metadataSource, templateProvider);
+    }
+    // ============================================================================
+    // FACTORY METHODS - Override these for custom implementations
+    // ============================================================================
+    /**
+     * Creates the skeleton renderer
+     */
+    createSkeletonRenderer(domAdapter) {
+        const validator = new SkeletonValidator();
+        return new SkeletonRenderer(domAdapter, validator);
+    }
+    /**
+     * Creates the template provider
+     */
+    createTemplateProvider(hostProjectionRegistry) {
+        return TemplateProviderFactory.createDefault(hostProjectionRegistry);
+    }
+    /**
+     * Creates the binding resolver
+     */
+    createBindingResolver(metadataSource) {
+        return new BindingResolver(undefined, undefined, undefined, metadataSource);
+    }
+    /**
+     * Creates the host projector
+     */
+    createHostProjector(domAdapter, hostProjectionRegistry) {
+        return new HostProjector(domAdapter, hostProjectionRegistry);
+    }
+    /**
+     * Creates the error handler
+     */
+    createErrorHandler(domAdapter) {
+        return new ErrorRenderer(domAdapter);
+    }
+    /**
+     * Creates the DOM adapter for environment-specific DOM operations
+     */
+    createDomAdapter() {
+        return new BrowserDomAdapter();
+    }
+    /**
+     * Creates the template compilation cache
+     */
+    createTemplateCache() {
+        return new TemplateCompilationCache();
+    }
+    /**
+     * Creates the template analyzer with default extractors
+     */
+    createTemplateAnalyzer() {
+        return new TemplateAnalyzer();
+    }
+    /**
+     * Creates the template compiler using composed dependencies
+     */
+    createTemplateCompiler(domAdapter, hostProjector, bindingResolver, metadataSource, hostProjectionRegistry) {
+        return new TemplateCompiler(domAdapter, hostProjector, bindingResolver, metadataSource, hostProjectionRegistry);
+    }
+    /**
+     * Creates the render pipeline
+     */
+    createRenderPipeline(serviceProvider, templateCompiler, errorHandler) {
+        return new RenderPipeline(serviceProvider || this.createNullServiceProvider(), templateCompiler, errorHandler);
+    }
+    /**
+     * Creates a null service provider when none is provided
+     */
+    createNullServiceProvider() {
+        return {
+            has() {
+                return false;
+            },
+            get() {
+                throw new Error('[RenderEngineFactory] No service provider configured');
+            }
+        };
+    }
+    /**
+     * Creates the host resolver for lifecycle managers
+     */
+    createHostResolver() {
+        return new DomContextHostResolver();
+    }
+    /**
+     * Creates the DOM context factory
+     */
+    createDomContextFactory() {
+        return new DomContextFactory();
+    }
+    /**
+     * Registers framework-provided services in the service provider.
+     * These services are essential for lifecycle managers and rendering.
+     *
+     * @param serviceProvider - Service provider to register services into
+     * @param services - Core framework services to register
+     */
+    registerFrameworkServices(serviceProvider, services) {
+        const registry = serviceProvider;
+        if (!serviceProvider.has('IDomAdapter')) {
+            registry.register('IDomAdapter', () => services.domAdapter);
+        }
+        if (!serviceProvider.has('IBindingResolver')) {
+            registry.register('IBindingResolver', () => services.bindingResolver);
+        }
+        if (!serviceProvider.has('ITemplateCompiler')) {
+            registry.register('ITemplateCompiler', () => services.templateCompiler);
+        }
+        if (!serviceProvider.has('IHostResolver')) {
+            registry.register('IHostResolver', () => services.hostResolver);
+        }
+    }
+    /**
+     * Creates the component instance registry
+     */
+    createInstanceRegistry() {
+        return new ComponentInstanceRegistry();
+    }
+    /**
+     * Creates the read-only metadata source for component metadata lookup
+     */
+    createMetadataSource() {
+        return ComponentMetadataRegistry;
+    }
+    /**
+     * Creates the render engine with its required dependencies
+     */
+    createRenderEngine(skeletonRenderer, renderPipeline, domContextFactory, templateCache, templateAnalyzer, instanceRegistry, metadataSource, templateProvider) {
+        return new RenderEngine(skeletonRenderer, renderPipeline, domContextFactory, templateCache, templateAnalyzer, templateProvider, instanceRegistry, metadataSource);
+    }
+    /**
+     * Resolves the host projection registry from the service provider or creates a new instance.
+     *
+     * @param serviceProvider - Optional service provider to resolve from
+     * @returns IHostProjectionRegistry instance
+     */
+    resolveHostProjectionRegistry(serviceProvider) {
+        if (serviceProvider?.has('IHostProjectionRegistry')) {
+            return serviceProvider.get('IHostProjectionRegistry');
+        }
+        return new HostProjectionRegistry();
+    }
+}
+//# sourceMappingURL=render-engine-factory.js.map

package/dist/rendering/render-engine-factory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"render-engine-factory.js","sourceRoot":"","sources":["../../src/rendering/render-engine-factory.ts"],"names":[],"mappings":"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"}

package/dist/rendering/render-engine.d.ts

@@ -0,0 +1,200 @@
+import { SmartComponent } from "../core/smart-component.js";
+import type { IComponentMetadataRegistry } from "../core/component-metadata-registry.interface.js";
+import { IComponentInstanceRegistry } from "../core/component-instance-registry.js";
+import { ISkeletonRenderer } from "./skeleton/skeleton-renderer.js";
+import { IRenderPipeline } from "./pipeline/render-pipeline.interface.js";
+import { IDomContextFactory } from "./dom-context/dom-context-factory.js";
+import { ITemplateAnalyzer } from "./templates/template-analyzer.js";
+import { ITemplateProvider } from "./templates/template-provider.js";
+import type { TemplateCompilationCache } from "./templates/template-compilation-cache.js";
+/**
+ * Defines the responsibility of configuring render operations for SmartComponents.
+ *
+ * @template T - The SmartComponent type being rendered
+ *
+ * @example
+ * ```typescript
+ * const options: RenderOptions<MyComponent> = {
+ *   componentId: 'my-component',
+ *   component: new MyComponent(),
+ *   targetRoot: document.body
+ * };
+ * ```
+ */
+export interface RenderOptions<T extends SmartComponent> {
+    /** Component ID (selector) for metadata lookup */
+    componentId: string;
+    /** The component instance to render */
+    component: T;
+    /** Target DOM root (HTMLElement or ShadowRoot) */
+    targetRoot: HTMLElement | ShadowRoot;
+    /** The custom element itself (for host projection content) */
+    hostElement?: HTMLElement;
+}
+/**
+ * Defines the responsibility of representing the outcome of a component render operation.
+ *
+ * @template T - The SmartComponent type that was rendered
+ *
+ * @example
+ * ```typescript
+ * const result: RenderResult<MyComponent> = {
+ *   component: myComponent,
+ *   domContext: domContext,
+ *   lifecycleManager: lifecycleManager,
+ *   cleanup: () => {}
+ * };
+ * ```
+ */
+export interface RenderResult {
+    /** Cleanup function to destroy component and remove from DOM */
+    cleanup: () => void;
+}
+/**
+ * Defines the responsibility of rendering SmartComponents and HTML fragments.
+ *
+ * @example
+ * ```typescript
+ * const renderEngine: IRenderEngine = new RenderEngine(
+ *   skeletonRenderer,
+ *   renderPipeline,
+ *   fragmentRenderer,
+ *   domContextFactory
+ * );
+ * ```
+ */
+export interface IRenderEngine {
+    render<T extends SmartComponent>(options: RenderOptions<T>): Promise<RenderResult>;
+}
+/**
+ * Implements the responsibility of orchestrating the complete rendering lifecycle of SmartComponents.
+ *
+ * @description
+ * The RenderEngine is the core rendering system that transforms SmartComponents into
+ * interactive DOM elements. It manages the entire lifecycle from skeleton display
+ * through initialization, template compilation, reactive binding, and cleanup.
+ *
+ * Now uses composition with specialized modules for each responsibility.
+ *
+ * @architecture
+ * **Rendering Pipeline (6 Steps):**
+ *
+ * 1. **Skeleton Display** - Show loading state immediately (synchronous)
+ * 2. **Initializer Check** - Detect if component requires async initialization
+ * 3. **Initialize & Wait** - Run initializer.initialize() and await completion
+ * 4. **Template Compilation** - Parse template, bind reactive state with {{bindings}}
+ * 5. **Lifecycle Start** - Begin lifecycle manager event listeners
+ *
+ * **Reactive Binding System:**
+ * - Scans template for {{propertyName}} expressions
+ * - Creates state$.subscribe() for each binding
+ * - Updates DOM automatically when component.setState() is called
+ * - Subscriptions managed by DomContext, cleaned up on destroy
+ *
+ * **Skeleton Strategy:**
+ * - Metadata: metadata.skeleton property from @SmartRender decorator
+ * - Fallback: Default skeleton with animated dots
+ *
+ * @example
+ * ```typescript
+ * // RenderEngine is called automatically by @SmartRender decorator
+ * @SmartRender({
+ *   selector: 'my-counter',
+ *   template: `<div>Count: {{count}}</div>
+ *              <button @click="increment">+</button>`,
+ *   initializer: CounterInitializer,
+ *   lifecycle: CounterLifecycle
+ * })
+ * class Counter extends SmartComponent {
+ *   @Reactive accessor count = 0;
+ *
+ *   increment() {
+ *     this.count++; // Auto-triggers state$.next() → DOM update
+ *   }
+ * }
+ *
+ * // Manual render (advanced):
+ * const renderEngine = new RenderEngine();
+ * const result = await renderEngine.render({
+ *   component: new Counter(),
+ *   componentCtor: Counter,
+ *   tagName: 'my-counter',
+ *   targetRoot: shadowRoot
+ * });
+ *
+ * result.cleanup(); // Destroys component, removes DOM, cleans subscriptions
+ * ```
+ *
+ * @remarks
+ * - render() returns immediately with skeleton, completes asynchronously
+ * - Template must be provided via @SmartRender decorator metadata
+ * - Error handling shows error overlay on skeleton
+ * - All subscriptions automatically cleaned up on component destroy
+ * - RenderEngine requires IServiceProvider for dependency resolution
+ */
+export declare class RenderEngine implements IRenderEngine {
+    private readonly skeletonRenderer;
+    private readonly renderPipeline;
+    private readonly domContextFactory;
+    private readonly templateCache;
+    private readonly templateAnalyzer;
+    private readonly templateProvider;
+    private readonly instanceRegistry;
+    private readonly metadataSource;
+    /**
+     * Creates a new RenderEngine instance with injected dependencies
+     *
+     * @param skeletonRenderer - Module for skeleton rendering
+     * @param renderPipeline - Module for executing render pipeline
+     * @param domContextFactory - Factory for creating DOM contexts
+     * @param templateCache - Optional template compilation cache
+     * @param templateAnalyzer - Optional template analyzer
+     * @throws Error if any required dependency is null or undefined
+     *
+     * @example
+     * ```typescript
+     * // Resolve from container (recommended)
+     * const renderEngine = registry.get<IRenderEngine>('IRenderEngine');
+     *
+     * // Manual construction (advanced — all params required)
+     * const renderEngine = new RenderEngine(
+     *   skeletonRenderer,
+     *   renderPipeline,
+     *   domContextFactory,
+     *   templateCache,
+     *   templateAnalyzer,
+     *   templateProvider,
+     *   instanceRegistry,
+     *   metadataSource
+     * );
+     * ```
+     */
+    constructor(skeletonRenderer: ISkeletonRenderer, renderPipeline: IRenderPipeline, domContextFactory: IDomContextFactory, templateCache: TemplateCompilationCache, templateAnalyzer: ITemplateAnalyzer, templateProvider: ITemplateProvider, instanceRegistry: IComponentInstanceRegistry, metadataSource: IComponentMetadataRegistry);
+    /**
+     * Renders a SmartComponent with full lifecycle support
+     *
+     * @description
+     * Main entry point for rendering a component. Looks up metadata from registry,
+     * manages component instance lifecycle (1:1 with DomContext),
+     * and executes the render pipeline.
+     *
+     * @template T - The SmartComponent type being rendered
+     * @param options - Render configuration options
+     * @returns Promise<RenderResult> - Cleanup function for this render context
+     * @throws Error if component metadata not found or rendering fails
+     *
+     * @example
+     * ```typescript
+     * const renderEngine = new RenderEngine();
+     * const result = await renderEngine.render({
+     *   componentId: 'my-component',
+     *   component: myComponent,
+     *   targetRoot: document.getElementById('app')!
+     * });
+     *
+     * result.cleanup(); // Full cleanup
+     * ```
+     */
+    render<T extends SmartComponent>(options: RenderOptions<T>): Promise<RenderResult>;
+}
+//# sourceMappingURL=render-engine.d.ts.map

package/dist/rendering/render-engine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"render-engine.d.ts","sourceRoot":"","sources":["../../src/rendering/render-engine.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAC;AAC5D,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,kDAAkD,CAAC;AACnG,OAAO,EAAE,0BAA0B,EAAE,MAAM,wCAAwC,CAAC;AACpF,OAAO,EAAE,iBAAiB,EAAE,MAAM,iCAAiC,CAAC;AACpE,OAAO,EAAE,eAAe,EAAE,MAAM,yCAAyC,CAAC;AAC1E,OAAO,EAAE,kBAAkB,EAAE,MAAM,sCAAsC,CAAC;AAC1E,OAAO,EAAE,iBAAiB,EAAE,MAAM,kCAAkC,CAAC;AACrE,OAAO,EAAE,iBAAiB,EAAE,MAAM,kCAAkC,CAAC;AACrE,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,2CAA2C,CAAC;AAE1F;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,aAAa,CAAC,CAAC,SAAS,cAAc;IACrD,kDAAkD;IAClD,WAAW,EAAE,MAAM,CAAC;IACpB,uCAAuC;IACvC,SAAS,EAAE,CAAC,CAAC;IACb,kDAAkD;IAClD,UAAU,EAAE,WAAW,GAAG,UAAU,CAAC;IACrC,8DAA8D;IAC9D,WAAW,CAAC,EAAE,WAAW,CAAC;CAC3B;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,WAAW,YAAY;IAC3B,gEAAgE;IAChE,OAAO,EAAE,MAAM,IAAI,CAAC;CACrB;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,aAAa;IAC5B,MAAM,CAAC,CAAC,SAAS,cAAc,EAC7B,OAAO,EAAE,aAAa,CAAC,CAAC,CAAC,GACxB,OAAO,CAAC,YAAY,CAAC,CAAC;CAC1B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiEG;AACH,qBAAa,YAAa,YAAW,aAAa;IAkC9C,OAAO,CAAC,QAAQ,CAAC,gBAAgB;IACjC,OAAO,CAAC,QAAQ,CAAC,cAAc;IAC/B,OAAO,CAAC,QAAQ,CAAC,iBAAiB;IAClC,OAAO,CAAC,QAAQ,CAAC,aAAa;IAC9B,OAAO,CAAC,QAAQ,CAAC,gBAAgB;IACjC,OAAO,CAAC,QAAQ,CAAC,gBAAgB;IACjC,OAAO,CAAC,QAAQ,CAAC,gBAAgB;IACjC,OAAO,CAAC,QAAQ,CAAC,cAAc;IApCjC;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2BG;gBAEgB,gBAAgB,EAAE,iBAAiB,EACnC,cAAc,EAAE,eAAe,EAC/B,iBAAiB,EAAE,kBAAkB,EACrC,aAAa,EAAE,wBAAwB,EACvC,gBAAgB,EAAE,iBAAiB,EACnC,gBAAgB,EAAE,iBAAiB,EACnC,gBAAgB,EAAE,0BAA0B,EAC5C,cAAc,EAAE,0BAA0B;IAgB7D;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACG,MAAM,CAAC,CAAC,SAAS,cAAc,EACnC,OAAO,EAAE,aAAa,CAAC,CAAC,CAAC,GACxB,OAAO,CAAC,YAAY,CAAC;CAuEzB"}

package/dist/rendering/render-engine.js

@@ -0,0 +1,205 @@
+/**
+ * Implements the responsibility of orchestrating the complete rendering lifecycle of SmartComponents.
+ *
+ * @description
+ * The RenderEngine is the core rendering system that transforms SmartComponents into
+ * interactive DOM elements. It manages the entire lifecycle from skeleton display
+ * through initialization, template compilation, reactive binding, and cleanup.
+ *
+ * Now uses composition with specialized modules for each responsibility.
+ *
+ * @architecture
+ * **Rendering Pipeline (6 Steps):**
+ *
+ * 1. **Skeleton Display** - Show loading state immediately (synchronous)
+ * 2. **Initializer Check** - Detect if component requires async initialization
+ * 3. **Initialize & Wait** - Run initializer.initialize() and await completion
+ * 4. **Template Compilation** - Parse template, bind reactive state with {{bindings}}
+ * 5. **Lifecycle Start** - Begin lifecycle manager event listeners
+ *
+ * **Reactive Binding System:**
+ * - Scans template for {{propertyName}} expressions
+ * - Creates state$.subscribe() for each binding
+ * - Updates DOM automatically when component.setState() is called
+ * - Subscriptions managed by DomContext, cleaned up on destroy
+ *
+ * **Skeleton Strategy:**
+ * - Metadata: metadata.skeleton property from @SmartRender decorator
+ * - Fallback: Default skeleton with animated dots
+ *
+ * @example
+ * ```typescript
+ * // RenderEngine is called automatically by @SmartRender decorator
+ * @SmartRender({
+ *   selector: 'my-counter',
+ *   template: `<div>Count: {{count}}</div>
+ *              <button @click="increment">+</button>`,
+ *   initializer: CounterInitializer,
+ *   lifecycle: CounterLifecycle
+ * })
+ * class Counter extends SmartComponent {
+ *   @Reactive accessor count = 0;
+ *
+ *   increment() {
+ *     this.count++; // Auto-triggers state$.next() → DOM update
+ *   }
+ * }
+ *
+ * // Manual render (advanced):
+ * const renderEngine = new RenderEngine();
+ * const result = await renderEngine.render({
+ *   component: new Counter(),
+ *   componentCtor: Counter,
+ *   tagName: 'my-counter',
+ *   targetRoot: shadowRoot
+ * });
+ *
+ * result.cleanup(); // Destroys component, removes DOM, cleans subscriptions
+ * ```
+ *
+ * @remarks
+ * - render() returns immediately with skeleton, completes asynchronously
+ * - Template must be provided via @SmartRender decorator metadata
+ * - Error handling shows error overlay on skeleton
+ * - All subscriptions automatically cleaned up on component destroy
+ * - RenderEngine requires IServiceProvider for dependency resolution
+ */
+export class RenderEngine {
+    skeletonRenderer;
+    renderPipeline;
+    domContextFactory;
+    templateCache;
+    templateAnalyzer;
+    templateProvider;
+    instanceRegistry;
+    metadataSource;
+    // ============================================================================
+    // CONSTRUCTOR
+    // ============================================================================
+    /**
+     * Creates a new RenderEngine instance with injected dependencies
+     *
+     * @param skeletonRenderer - Module for skeleton rendering
+     * @param renderPipeline - Module for executing render pipeline
+     * @param domContextFactory - Factory for creating DOM contexts
+     * @param templateCache - Optional template compilation cache
+     * @param templateAnalyzer - Optional template analyzer
+     * @throws Error if any required dependency is null or undefined
+     *
+     * @example
+     * ```typescript
+     * // Resolve from container (recommended)
+     * const renderEngine = registry.get<IRenderEngine>('IRenderEngine');
+     *
+     * // Manual construction (advanced — all params required)
+     * const renderEngine = new RenderEngine(
+     *   skeletonRenderer,
+     *   renderPipeline,
+     *   domContextFactory,
+     *   templateCache,
+     *   templateAnalyzer,
+     *   templateProvider,
+     *   instanceRegistry,
+     *   metadataSource
+     * );
+     * ```
+     */
+    constructor(skeletonRenderer, renderPipeline, domContextFactory, templateCache, templateAnalyzer, templateProvider, instanceRegistry, metadataSource) {
+        this.skeletonRenderer = skeletonRenderer;
+        this.renderPipeline = renderPipeline;
+        this.domContextFactory = domContextFactory;
+        this.templateCache = templateCache;
+        this.templateAnalyzer = templateAnalyzer;
+        this.templateProvider = templateProvider;
+        this.instanceRegistry = instanceRegistry;
+        this.metadataSource = metadataSource;
+        if (!skeletonRenderer)
+            throw new Error("SkeletonRenderer is required");
+        if (!renderPipeline)
+            throw new Error("RenderPipeline is required");
+        if (!domContextFactory)
+            throw new Error("DomContextFactory is required");
+        if (!templateCache)
+            throw new Error("TemplateCompilationCache is required");
+        if (!templateAnalyzer)
+            throw new Error("TemplateAnalyzer is required");
+        if (!templateProvider)
+            throw new Error("TemplateProvider is required");
+        if (!instanceRegistry)
+            throw new Error("InstanceRegistry is required");
+        if (!metadataSource)
+            throw new Error("MetadataSource is required");
+    }
+    // ============================================================================
+    // PUBLIC API
+    // ============================================================================
+    /**
+     * Renders a SmartComponent with full lifecycle support
+     *
+     * @description
+     * Main entry point for rendering a component. Looks up metadata from registry,
+     * manages component instance lifecycle (1:1 with DomContext),
+     * and executes the render pipeline.
+     *
+     * @template T - The SmartComponent type being rendered
+     * @param options - Render configuration options
+     * @returns Promise<RenderResult> - Cleanup function for this render context
+     * @throws Error if component metadata not found or rendering fails
+     *
+     * @example
+     * ```typescript
+     * const renderEngine = new RenderEngine();
+     * const result = await renderEngine.render({
+     *   componentId: 'my-component',
+     *   component: myComponent,
+     *   targetRoot: document.getElementById('app')!
+     * });
+     *
+     * result.cleanup(); // Full cleanup
+     * ```
+     */
+    async render(options) {
+        // 1. Lookup metadata
+        const metadata = this.metadataSource.get(options.componentId);
+        if (!metadata) {
+            throw new Error(`Component ${options.componentId} not registered in metadata registry`);
+        }
+        // 2. Create unique DOM context
+        const domContext = this.domContextFactory.create(options.targetRoot);
+        // 3. Get or create component instance (1:1 per contextId)
+        const entry = this.instanceRegistry.getOrCreate(domContext.contextId, () => options.component, metadata);
+        const instance = entry.instance;
+        // 4. Resolve constants early so skeleton can use [[BINDING]] syntax
+        const resolvedConstants = metadata.constants
+            ? typeof metadata.constants === "function"
+                ? metadata.constants(options.hostElement ?? instance)
+                : metadata.constants
+            : undefined;
+        // 5. Render skeleton (with resolved constants for [[BINDING]] support)
+        await this.skeletonRenderer.render(instance, metadata, domContext, resolvedConstants);
+        // 6. Resolve static bindings ([[CONSTANT]] and [[RULES.field]]) BEFORE template analysis
+        const resolvedTemplate = await this.templateProvider.getSource(instance, {
+            ...options,
+            component: instance,
+        });
+        // 6. Get or compile template
+        const compiledTemplate = this.templateCache.getOrCompile(options.componentId, resolvedTemplate, this.templateAnalyzer);
+        // 7. Execute pipeline
+        const result = await this.renderPipeline.execute({
+            component: instance,
+            metadata,
+            domContext,
+            compiledTemplate,
+            hostElement: options.hostElement,
+        }, domContext);
+        // 8. Wrap cleanup with ComponentInstanceRegistry.release
+        const originalCleanup = result.cleanup;
+        return {
+            cleanup: () => {
+                originalCleanup();
+                this.instanceRegistry.release(domContext.contextId);
+            },
+        };
+    }
+}
+//# sourceMappingURL=render-engine.js.map

package/dist/rendering/render-engine.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"render-engine.js","sourceRoot":"","sources":["../../src/rendering/render-engine.ts"],"names":[],"mappings":"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"}