smart-lifecycle 0.1.1

package/dist/rendering/templates/template-compilation-cache.d.ts

@@ -0,0 +1,96 @@
+import { ICompiledTemplate } from "./compiled-template.interface.js";
+import { ITemplateAnalyzer } from "./template-analyzer.js";
+/**
+ * Implements the responsibility of caching compiled templates.
+ *
+ * @description
+ * Caches compiled templates to avoid re-parsing.
+ * Templates are indexed by a cache key that includes both componentId and template content hash
+ * to prevent staleness when constants or rules change.
+ *
+ * @example
+ * ```typescript
+ * const cache = new TemplateCompilationCache();
+ * const analyzer = new TemplateAnalyzer();
+ *
+ * // First call: compiles and caches
+ * const compiled1 = cache.getOrCompile('my-counter', '<div>{{count}}</div>', analyzer);
+ *
+ * // Second call with same template: returns cached version
+ * const compiled2 = cache.getOrCompile('my-counter', '<div>{{count}}</div>', analyzer);
+ *
+ * // Different resolved template (e.g., constants changed): new compilation
+ * const compiled3 = cache.getOrCompile('my-counter', '<div class="new-class">{{count}}</div>', analyzer);
+ *
+ * // compiled1 === compiled2 (same reference)
+ * // compiled1 !== compiled3 (different template)
+ * ```
+ */
+export declare class TemplateCompilationCache {
+    private cache;
+    /**
+     * Generates a cache key from componentId and template content.
+     *
+     * @description
+     * Uses SHA-1 hash of template to ensure different resolved templates
+     * (due to different constants/rules) produce different cache keys.
+     *
+     * @param componentId - Component selector (tag name)
+     * @param template - Resolved template string (after static binding resolution)
+     * @returns Cache key combining componentId and template hash
+     */
+    private generateCacheKey;
+    /**
+     * Gets cached compiled template or compiles and caches it.
+     *
+     * @param componentId - Component selector (tag name)
+     * @param template - HTML template string (should already be resolved of [[...]] and [[RULES.*]])
+     * @param analyzer - Template analyzer instance
+     * @returns Compiled template (cached or newly compiled)
+     * @throws Error if any parameter is null or undefined
+     *
+     * @example
+     * ```typescript
+     * const cache = new TemplateCompilationCache();
+     * const analyzer = new TemplateAnalyzer();
+     *
+     * const compiled = cache.getOrCompile(
+     *   'my-counter',
+     *   '<div>{{count}}</div>',
+     *   analyzer
+     * );
+     * ```
+     */
+    getOrCompile(componentId: string, template: string, analyzer: ITemplateAnalyzer): ICompiledTemplate;
+    /**
+     * Checks if a template is cached.
+     *
+     * @param componentId - Component selector (tag name)
+     * @param template - Template string to check
+     * @returns true if cached, false otherwise
+     * @throws Error if parameters are null or undefined
+     *
+     * @example
+     * ```typescript
+     * if (cache.has('my-counter', '<div>{{count}}</div>')) {
+     *   console.log('Template is cached');
+     * }
+     * ```
+     */
+    has(componentId: string, template: string): boolean;
+    /**
+     * Clears all cached templates.
+     *
+     * @description
+     * Used for testing to ensure test isolation.
+     *
+     * @example
+     * ```typescript
+     * afterEach(() => {
+     *   cache.clear();
+     * });
+     * ```
+     */
+    clear(): void;
+}
+//# sourceMappingURL=template-compilation-cache.d.ts.map

package/dist/rendering/templates/template-compilation-cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"template-compilation-cache.d.ts","sourceRoot":"","sources":["../../../src/rendering/templates/template-compilation-cache.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,iBAAiB,EAAE,MAAM,kCAAkC,CAAC;AACrE,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAE3D;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,qBAAa,wBAAwB;IACnC,OAAO,CAAC,KAAK,CAAwC;IAErD;;;;;;;;;;OAUG;IACH,OAAO,CAAC,gBAAgB;IAQxB;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,YAAY,CACV,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,iBAAiB,GAC1B,iBAAiB;IAgBpB;;;;;;;;;;;;;;OAcG;IACH,GAAG,CAAC,WAAW,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO;IAOnD;;;;;;;;;;;;OAYG;IACH,KAAK,IAAI,IAAI;CAGd"}

package/dist/rendering/templates/template-compilation-cache.js

@@ -0,0 +1,125 @@
+import { createHash } from "crypto";
+/**
+ * Implements the responsibility of caching compiled templates.
+ *
+ * @description
+ * Caches compiled templates to avoid re-parsing.
+ * Templates are indexed by a cache key that includes both componentId and template content hash
+ * to prevent staleness when constants or rules change.
+ *
+ * @example
+ * ```typescript
+ * const cache = new TemplateCompilationCache();
+ * const analyzer = new TemplateAnalyzer();
+ *
+ * // First call: compiles and caches
+ * const compiled1 = cache.getOrCompile('my-counter', '<div>{{count}}</div>', analyzer);
+ *
+ * // Second call with same template: returns cached version
+ * const compiled2 = cache.getOrCompile('my-counter', '<div>{{count}}</div>', analyzer);
+ *
+ * // Different resolved template (e.g., constants changed): new compilation
+ * const compiled3 = cache.getOrCompile('my-counter', '<div class="new-class">{{count}}</div>', analyzer);
+ *
+ * // compiled1 === compiled2 (same reference)
+ * // compiled1 !== compiled3 (different template)
+ * ```
+ */
+export class TemplateCompilationCache {
+    cache = new Map();
+    /**
+     * Generates a cache key from componentId and template content.
+     *
+     * @description
+     * Uses SHA-1 hash of template to ensure different resolved templates
+     * (due to different constants/rules) produce different cache keys.
+     *
+     * @param componentId - Component selector (tag name)
+     * @param template - Resolved template string (after static binding resolution)
+     * @returns Cache key combining componentId and template hash
+     */
+    generateCacheKey(componentId, template) {
+        const hash = createHash("sha1")
+            .update(template)
+            .digest("hex")
+            .substring(0, 8);
+        return `${componentId}:${hash}`;
+    }
+    /**
+     * Gets cached compiled template or compiles and caches it.
+     *
+     * @param componentId - Component selector (tag name)
+     * @param template - HTML template string (should already be resolved of [[...]] and [[RULES.*]])
+     * @param analyzer - Template analyzer instance
+     * @returns Compiled template (cached or newly compiled)
+     * @throws Error if any parameter is null or undefined
+     *
+     * @example
+     * ```typescript
+     * const cache = new TemplateCompilationCache();
+     * const analyzer = new TemplateAnalyzer();
+     *
+     * const compiled = cache.getOrCompile(
+     *   'my-counter',
+     *   '<div>{{count}}</div>',
+     *   analyzer
+     * );
+     * ```
+     */
+    getOrCompile(componentId, template, analyzer) {
+        if (!componentId)
+            throw new Error("ComponentId is required");
+        if (!template)
+            throw new Error("Template is required");
+        if (!analyzer)
+            throw new Error("Analyzer is required");
+        const cacheKey = this.generateCacheKey(componentId, template);
+        const cached = this.cache.get(cacheKey);
+        if (cached) {
+            return cached;
+        }
+        const compiled = analyzer.analyze(template);
+        this.cache.set(cacheKey, compiled);
+        return compiled;
+    }
+    /**
+     * Checks if a template is cached.
+     *
+     * @param componentId - Component selector (tag name)
+     * @param template - Template string to check
+     * @returns true if cached, false otherwise
+     * @throws Error if parameters are null or undefined
+     *
+     * @example
+     * ```typescript
+     * if (cache.has('my-counter', '<div>{{count}}</div>')) {
+     *   console.log('Template is cached');
+     * }
+     * ```
+     */
+    has(componentId, template) {
+        if (!componentId)
+            throw new Error("ComponentId is required");
+        if (!template)
+            throw new Error("Template is required");
+        const cacheKey = this.generateCacheKey(componentId, template);
+        return this.cache.has(cacheKey);
+    }
+    /**
+     * Clears all cached templates.
+     *
+     * @description
+     * Used for testing to ensure test isolation.
+     *
+     * @example
+     * ```typescript
+     * afterEach(() => {
+     *   cache.clear();
+     * });
+     * ```
+     */
+    clear() {
+        this.cache.clear();
+    }
+}
+//# sourceMappingURL=template-compilation-cache.js.map

package/dist/rendering/templates/template-compilation-cache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"template-compilation-cache.js","sourceRoot":"","sources":["../../../src/rendering/templates/template-compilation-cache.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,QAAQ,CAAC;AAIpC;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,MAAM,OAAO,wBAAwB;IAC3B,KAAK,GAAG,IAAI,GAAG,EAA6B,CAAC;IAErD;;;;;;;;;;OAUG;IACK,gBAAgB,CAAC,WAAmB,EAAE,QAAgB;QAC5D,MAAM,IAAI,GAAG,UAAU,CAAC,MAAM,CAAC;aAC5B,MAAM,CAAC,QAAQ,CAAC;aAChB,MAAM,CAAC,KAAK,CAAC;aACb,SAAS,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;QACnB,OAAO,GAAG,WAAW,IAAI,IAAI,EAAE,CAAC;IAClC,CAAC;IAED;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,YAAY,CACV,WAAmB,EACnB,QAAgB,EAChB,QAA2B;QAE3B,IAAI,CAAC,WAAW;YAAE,MAAM,IAAI,KAAK,CAAC,yBAAyB,CAAC,CAAC;QAC7D,IAAI,CAAC,QAAQ;YAAE,MAAM,IAAI,KAAK,CAAC,sBAAsB,CAAC,CAAC;QACvD,IAAI,CAAC,QAAQ;YAAE,MAAM,IAAI,KAAK,CAAC,sBAAsB,CAAC,CAAC;QAEvD,MAAM,QAAQ,GAAG,IAAI,CAAC,gBAAgB,CAAC,WAAW,EAAE,QAAQ,CAAC,CAAC;QAC9D,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;QACxC,IAAI,MAAM,EAAE,CAAC;YACX,OAAO,MAAM,CAAC;QAChB,CAAC;QAED,MAAM,QAAQ,GAAG,QAAQ,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;QAC5C,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC;QACnC,OAAO,QAAQ,CAAC;IAClB,CAAC;IAED;;;;;;;;;;;;;;OAcG;IACH,GAAG,CAAC,WAAmB,EAAE,QAAgB;QACvC,IAAI,CAAC,WAAW;YAAE,MAAM,IAAI,KAAK,CAAC,yBAAyB,CAAC,CAAC;QAC7D,IAAI,CAAC,QAAQ;YAAE,MAAM,IAAI,KAAK,CAAC,sBAAsB,CAAC,CAAC;QACvD,MAAM,QAAQ,GAAG,IAAI,CAAC,gBAAgB,CAAC,WAAW,EAAE,QAAQ,CAAC,CAAC;QAC9D,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;IAClC,CAAC;IAED;;;;;;;;;;;;OAYG;IACH,KAAK;QACH,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC;IACrB,CAAC;CACF"}

package/dist/rendering/templates/template-compiler.d.ts

@@ -0,0 +1,76 @@
+import { SmartComponent } from "../../core/smart-component.js";
+import { IDomContext } from "../dom-context/dom-context.interface.js";
+import { ITemplateCompiler } from "./template-compiler.interface.js";
+import { IDomAdapter } from "../dom/dom-adapter.interface.js";
+import type { IManagedElementRegistry } from "../managed-host/managed-element-registry.js";
+import type { IComponentMetadataRegistry } from "../../core/component-metadata-registry.interface.js";
+import { ComponentMetadata } from "../../core/component-metadata.js";
+import { IBindingResolver } from "../bindings/binding-resolver.js";
+/**
+ * Implements the responsibility of compiling template HTML with reactive bindings.
+ *
+ * @description
+ * Transforms template strings into live DOM elements with reactive state bindings.
+ * Creates subscriptions for property changes. Content projection is handled
+ * natively by the browser via Shadow DOM <slot> elements.
+ *
+ * @architecture
+ * Compilation Process:
+ * 1. Parse template HTML into DOM element using IDomAdapter
+ * 2. Bind reactive properties to DOM updates
+ */
+export declare class TemplateCompiler implements ITemplateCompiler {
+    private readonly domAdapter;
+    private readonly bindingResolver;
+    private readonly metadataSource;
+    private readonly managedRegistry?;
+    /**
+     * Framework built-in elements that manage their own child binding scope.
+     * The BindingResolver must not recurse into these — their children serve
+     * as templates compiled separately with a different reactive context.
+     */
+    private static readonly TEMPLATE_BOUNDARY_ELEMENTS;
+    /**
+     * Initializes a new instance of TemplateCompiler.
+     *
+     * @param domAdapter - Adapter for DOM element creation
+     * @param bindingResolver - Resolver for attribute/text bindings with input cleanup
+     * @param metadataSource - Read-only source for component metadata lookup
+     * @param managedRegistry - Registry for managed element tracking
+     * @throws Error if domAdapter or bindingResolver is null or undefined
+     */
+    constructor(domAdapter: IDomAdapter, bindingResolver: IBindingResolver, metadataSource: IComponentMetadataRegistry, managedRegistry?: IManagedElementRegistry | undefined);
+    /**
+     * Compiles template source into a reactive DOM element
+     *
+     * @param templateSource - HTML template string
+     * @param component - Component instance for property access
+     * @param domContext - DOM context for subscription management
+     * @param metadata - Optional component metadata for selector and configuration
+     * @returns Promise resolving to compiled HTMLElement
+     * @throws Error if any parameter is null or undefined
+     *
+     * @example
+     * ```typescript
+     * const compiler = new TemplateCompiler();
+     * const element = await compiler.compile(
+     *   '<div>{{message}}</div>',
+     *   myComponent,
+     *   domContext,
+     *   metadata
+     * );
+     * ```
+     */
+    compile<T extends SmartComponent>(templateSource: string, component: T, domContext: IDomContext, metadata?: ComponentMetadata): Promise<HTMLElement>;
+    /**
+     * Registers nested custom elements that are SmartComponents as managed.
+     *
+     * All registered SmartComponents found in the template are marked as managed.
+     * The binding resolver stops recursing into their children because each
+     * nested component renders inside its own Shadow DOM scope.
+     *
+     * @param rootElement - Root element to scan for nested components
+     */
+    private registerNestedManagedElements;
+}
+//# sourceMappingURL=template-compiler.d.ts.map

package/dist/rendering/templates/template-compiler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"template-compiler.d.ts","sourceRoot":"","sources":["../../../src/rendering/templates/template-compiler.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAC;AAC/D,OAAO,EAAE,WAAW,EAAE,MAAM,yCAAyC,CAAC;AACtE,OAAO,EAAE,iBAAiB,EAAE,MAAM,kCAAkC,CAAC;AACrE,OAAO,EAAE,WAAW,EAAE,MAAM,iCAAiC,CAAC;AAC9D,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,6CAA6C,CAAC;AAC3F,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,qDAAqD,CAAC;AACtG,OAAO,EAAE,iBAAiB,EAAE,MAAM,kCAAkC,CAAC;AACrE,OAAO,EAAE,gBAAgB,EAAE,MAAM,iCAAiC,CAAC;AAEnE;;;;;;;;;;;;GAYG;AACH,qBAAa,gBAAiB,YAAW,iBAAiB;IAkBtD,OAAO,CAAC,QAAQ,CAAC,UAAU;IAC3B,OAAO,CAAC,QAAQ,CAAC,eAAe;IAChC,OAAO,CAAC,QAAQ,CAAC,cAAc;IAC/B,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAC;IApBnC;;;;OAIG;IACH,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,0BAA0B,CAA0B;IAE5E;;;;;;;;OAQG;gBAEgB,UAAU,EAAE,WAAW,EACvB,eAAe,EAAE,gBAAgB,EACjC,cAAc,EAAE,0BAA0B,EAC1C,eAAe,CAAC,EAAE,uBAAuB,YAAA;IAS5D;;;;;;;;;;;;;;;;;;;;OAoBG;IACG,OAAO,CAAC,CAAC,SAAS,cAAc,EACpC,cAAc,EAAE,MAAM,EACtB,SAAS,EAAE,CAAC,EACZ,UAAU,EAAE,WAAW,EACvB,QAAQ,CAAC,EAAE,iBAAiB,GAC3B,OAAO,CAAC,WAAW,CAAC;IAsDvB;;;;;;;;OAQG;IACH,OAAO,CAAC,6BAA6B;CAgBtC"}

package/dist/rendering/templates/template-compiler.interface.d.ts

@@ -0,0 +1,35 @@
+import { SmartComponent } from "../../core/smart-component.js";
+import { IDomContext } from "../dom-context/dom-context.interface.js";
+import { ComponentMetadata } from "../../core/component-metadata.js";
+/**
+ * Defines the responsibility of compiling template HTML strings into live DOM elements.
+ *
+ * @description
+ * Defines the contract for compiling template HTML strings into live DOM elements
+ * with reactive bindings and host projection applied.
+ */
+export interface ITemplateCompiler {
+    /**
+     * Compiles a template string into a reactive DOM element.
+     *
+     * @param templateSource - Preprocessed template HTML string
+     * @param component - Component instance for binding context
+     * @param domContext - DOM context for managing subscriptions and element references
+     * @param metadata - Optional component metadata for selector and configuration
+     * @returns Promise resolving to compiled HTMLElement ready for insertion
+     * @throws Error if template has no root element or compilation fails
+     *
+     * @example
+     * ```typescript
+     * const compiler = new TemplateCompiler();
+     * const element = await compiler.compile(
+     *   '<div>{{message}}</div>',
+     *   myComponent,
+     *   domContext,
+     *   metadata
+     * );
+     * ```
+     */
+    compile(templateSource: string, component: SmartComponent, domContext: IDomContext, metadata?: ComponentMetadata): Promise<HTMLElement>;
+}
+//# sourceMappingURL=template-compiler.interface.d.ts.map

package/dist/rendering/templates/template-compiler.interface.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"template-compiler.interface.d.ts","sourceRoot":"","sources":["../../../src/rendering/templates/template-compiler.interface.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAC;AAC/D,OAAO,EAAE,WAAW,EAAE,MAAM,yCAAyC,CAAC;AACtE,OAAO,EAAE,iBAAiB,EAAE,MAAM,kCAAkC,CAAC;AAErE;;;;;;GAMG;AACH,MAAM,WAAW,iBAAiB;IAChC;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,OAAO,CACL,cAAc,EAAE,MAAM,EACtB,SAAS,EAAE,cAAc,EACzB,UAAU,EAAE,WAAW,EACvB,QAAQ,CAAC,EAAE,iBAAiB,GAC3B,OAAO,CAAC,WAAW,CAAC,CAAC;CACzB"}

package/dist/rendering/templates/template-compiler.interface.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=template-compiler.interface.js.map

package/dist/rendering/templates/template-compiler.interface.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"template-compiler.interface.js","sourceRoot":"","sources":["../../../src/rendering/templates/template-compiler.interface.ts"],"names":[],"mappings":""}

package/dist/rendering/templates/template-compiler.js

@@ -0,0 +1,136 @@
+/**
+ * Implements the responsibility of compiling template HTML with reactive bindings.
+ *
+ * @description
+ * Transforms template strings into live DOM elements with reactive state bindings.
+ * Creates subscriptions for property changes. Content projection is handled
+ * natively by the browser via Shadow DOM <slot> elements.
+ *
+ * @architecture
+ * Compilation Process:
+ * 1. Parse template HTML into DOM element using IDomAdapter
+ * 2. Bind reactive properties to DOM updates
+ */
+export class TemplateCompiler {
+    domAdapter;
+    bindingResolver;
+    metadataSource;
+    managedRegistry;
+    /**
+     * Framework built-in elements that manage their own child binding scope.
+     * The BindingResolver must not recurse into these — their children serve
+     * as templates compiled separately with a different reactive context.
+     */
+    static TEMPLATE_BOUNDARY_ELEMENTS = new Set(["smart-for"]);
+    /**
+     * Initializes a new instance of TemplateCompiler.
+     *
+     * @param domAdapter - Adapter for DOM element creation
+     * @param bindingResolver - Resolver for attribute/text bindings with input cleanup
+     * @param metadataSource - Read-only source for component metadata lookup
+     * @param managedRegistry - Registry for managed element tracking
+     * @throws Error if domAdapter or bindingResolver is null or undefined
+     */
+    constructor(domAdapter, bindingResolver, metadataSource, managedRegistry) {
+        this.domAdapter = domAdapter;
+        this.bindingResolver = bindingResolver;
+        this.metadataSource = metadataSource;
+        this.managedRegistry = managedRegistry;
+        if (!domAdapter) {
+            throw new Error("Dom adapter is required");
+        }
+        if (!bindingResolver) {
+            throw new Error("Binding resolver is required");
+        }
+    }
+    /**
+     * Compiles template source into a reactive DOM element
+     *
+     * @param templateSource - HTML template string
+     * @param component - Component instance for property access
+     * @param domContext - DOM context for subscription management
+     * @param metadata - Optional component metadata for selector and configuration
+     * @returns Promise resolving to compiled HTMLElement
+     * @throws Error if any parameter is null or undefined
+     *
+     * @example
+     * ```typescript
+     * const compiler = new TemplateCompiler();
+     * const element = await compiler.compile(
+     *   '<div>{{message}}</div>',
+     *   myComponent,
+     *   domContext,
+     *   metadata
+     * );
+     * ```
+     */
+    async compile(templateSource, component, domContext, metadata) {
+        if (!templateSource)
+            throw new Error("Template source is required");
+        if (!component)
+            throw new Error("Component is required");
+        if (!domContext)
+            throw new Error("DOM context is required");
+        // Use provided metadata or fallback to registry lookup
+        const resolvedMetadata = metadata && typeof metadata === "object" && "selector" in metadata
+            ? metadata
+            : this.metadataSource.get(component.constructor.name.toLowerCase());
+        const selector = resolvedMetadata?.selector || component.constructor.name.toLowerCase();
+        const template = this.domAdapter.createTemplateElement();
+        template.innerHTML = templateSource.trim();
+        let rootElement;
+        if (template.content.children.length === 1) {
+            rootElement = template.content.firstElementChild;
+        }
+        else {
+            const wrapper = this.domAdapter.createElement("div");
+            wrapper.className = selector;
+            while (template.content.firstChild) {
+                wrapper.appendChild(template.content.firstChild);
+            }
+            rootElement = wrapper;
+        }
+        if (!rootElement.classList.contains(selector)) {
+            rootElement.classList.add(selector);
+        }
+        // Register nested component elements as managed BEFORE binding so resolver can detect them
+        this.registerNestedManagedElements(rootElement);
+        // Use BindingResolver to compile all bindings (handles recursion internally)
+        this.bindingResolver.bindElement(rootElement, component, domContext);
+        // Pre-capture templates for nested smart-for elements AFTER binding (so the items
+        // attribute is already resolved) but BEFORE DOM insertion.  Uses a data attribute
+        // because elements in <template> content fragments are NOT upgraded to Custom
+        // Elements — instance methods like setPresetTemplate() do not exist on them.
+        // This prevents a browser Custom Elements ordering race where an inner smart-for's
+        // connectedCallback fires before the outer's, clearing its innerHTML and corrupting
+        // the outer's template.
+        const nestedSmartFors = rootElement.querySelectorAll("smart-for");
+        for (let i = 0; i < nestedSmartFors.length; i++) {
+            const sf = nestedSmartFors[i];
+            sf.setAttribute("data-preset-template", sf.innerHTML);
+        }
+        return rootElement;
+    }
+    /**
+     * Registers nested custom elements that are SmartComponents as managed.
+     *
+     * All registered SmartComponents found in the template are marked as managed.
+     * The binding resolver stops recursing into their children because each
+     * nested component renders inside its own Shadow DOM scope.
+     *
+     * @param rootElement - Root element to scan for nested components
+     */
+    registerNestedManagedElements(rootElement) {
+        const allElements = rootElement.getElementsByTagName("*");
+        for (let i = 0; i < allElements.length; i++) {
+            const element = allElements[i];
+            const tagName = element.tagName.toLowerCase();
+            if (tagName.includes("-") &&
+                (this.metadataSource.has(tagName) ||
+                    TemplateCompiler.TEMPLATE_BOUNDARY_ELEMENTS.has(tagName))) {
+                this.managedRegistry?.register(element, tagName);
+            }
+        }
+    }
+}
+//# sourceMappingURL=template-compiler.js.map

package/dist/rendering/templates/template-compiler.js.map

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

package/dist/rendering/templates/template-provider.d.ts

@@ -0,0 +1,112 @@
+import { SmartComponent } from "../../core/smart-component.js";
+import { RenderOptions } from "../render-engine.js";
+import type { IComponentMetadataRegistry } from "../../core/component-metadata-registry.interface.js";
+import { IStaticBindingResolver } from "../bindings/static-binding-resolver.interface.js";
+import { IRulesResolver } from "../bindings/rules-resolver.interface.js";
+/**
+ * Implements the responsibility of handling template sourcing and static preprocessing.
+ *
+ * @description
+ * Responsible for retrieving component templates from @SmartRender decorator metadata
+ * and preprocessing static bindings like [[CONSTANT]] and [[RULES.field]] before reactive compilation.
+ * Content projection is handled natively by Shadow DOM <slot> elements.
+ *
+ * @architecture
+ * Template Processing Pipeline:
+ * 1. Load template from metadata.template (already in bundle)
+ * 2. Preprocess [[CONSTANT]] bindings (static, replaced once)
+ * 3. Preprocess [[RULES.field]] bindings (converted to HTML validation attributes)
+ * 4. Return preprocessed template for reactive {{binding}} compilation
+ */
+/**
+ * Defines the responsibility of retrieving component templates from metadata and preprocessing.
+ *
+ * @description
+ * Defines the contract for retrieving component templates from metadata and preprocessing
+ * static bindings like [[CONSTANT]] before reactive compilation.
+ */
+export interface ITemplateProvider {
+    /**
+     * Retrieves and preprocesses the template source for a component.
+     *
+     * @param component - The component instance
+     * @param options - Render options containing host element for host projection content capture
+     * @returns Promise resolving to preprocessed template HTML string
+     * @throws Error if no template found in component metadata
+     */
+    getSource(component: SmartComponent, options: RenderOptions<SmartComponent>): Promise<string>;
+}
+export declare class TemplateProvider implements ITemplateProvider {
+    /**
+     * Static binding resolver for [[CONSTANT]] preprocessing
+     */
+    private readonly staticBindingResolver;
+    /**
+     * Rules resolver for [[RULES.field]] preprocessing
+     */
+    private readonly rulesResolver;
+    /**
+     * Read-only metadata source for component metadata lookup
+     */
+    private readonly metadataSource;
+    /**
+     * Initializes a new instance of TemplateProvider.
+     *
+     * @param staticBindingResolver - Resolver for static constant bindings
+     * @param rulesResolver - Resolver for validation rules bindings
+     * @param metadataSource - Read-only source for component metadata lookup
+     * @throws Error if any dependency is null or undefined
+     */
+    constructor(staticBindingResolver: IStaticBindingResolver, rulesResolver: IRulesResolver, metadataSource?: IComponentMetadataRegistry);
+    /**
+     * Retrieves and preprocesses the template source for a component
+     *
+     * @description
+     * Gets template HTML from component metadata and resolves static constants and rules.
+     *
+     * @param component - Component instance
+     * @param options - Render options with hostElement
+     * @returns Promise<string> - Template HTML with [[CONSTANT]] and [[RULES.field]] bindings resolved
+     * @throws Error if no template found in metadata
+     *
+     * @example
+     * ```typescript
+     * // Component with constants and rules
+     * @SmartRender({
+     *   selector: 'login-form',
+     *   constants: {
+     *     Styles: { INPUT: 'form-control' },
+     *     Events: { SUBMIT: 'login-submit' }
+     *   },
+     *   template: `
+     *     <form>
+     *       <input [[RULES.username]] class="[[Styles.INPUT]]" placeholder="Username" />
+     *       <input [[RULES.password]] class="[[Styles.INPUT]]" type="password" placeholder="Password" />
+     *       <button event="[[Events.SUBMIT]]">Login</button>
+     *     </form>
+     *   `
+     * })
+     * class LoginForm extends SmartComponent {
+     *   rules = {
+     *     username: { required: true, minlength: 3 },
+     *     password: { required: true, minlength: 8 }
+     *   };
+     * }
+     *
+     * // After getSource():
+     * // `<form>
+     * //    <input required minlength="3" class="form-control" placeholder="Username" />
+     * //    <input required minlength="8" class="form-control" type="password" placeholder="Password" />
+     * //    <button event="login-submit">Login</button>
+     * //  </form>`
+     * ```
+     */
+    getSource(component: SmartComponent, options: RenderOptions<SmartComponent>): Promise<string>;
+    /**
+     * Type guard — returns true when a component has validation rules (duck-typing).
+     * Not all components are forms; rules are only present when injected via ctx.rules()
+     * or assigned explicitly. Avoids polluting the SmartComponent base class.
+     */
+    private hasRules;
+}
+//# sourceMappingURL=template-provider.d.ts.map

package/dist/rendering/templates/template-provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"template-provider.d.ts","sourceRoot":"","sources":["../../../src/rendering/templates/template-provider.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAC;AAC/D,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEpD,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,qDAAqD,CAAC;AACtG,OAAO,EAAE,sBAAsB,EAAE,MAAM,kDAAkD,CAAC;AAC1F,OAAO,EAAE,cAAc,EAAE,MAAM,yCAAyC,CAAC;AAEzE;;;;;;;;;;;;;;GAcG;AAEH;;;;;;GAMG;AACH,MAAM,WAAW,iBAAiB;IAChC;;;;;;;OAOG;IACH,SAAS,CACP,SAAS,EAAE,cAAc,EACzB,OAAO,EAAE,aAAa,CAAC,cAAc,CAAC,GACrC,OAAO,CAAC,MAAM,CAAC,CAAC;CACpB;AAED,qBAAa,gBAAiB,YAAW,iBAAiB;IACxD;;OAEG;IACH,OAAO,CAAC,QAAQ,CAAC,qBAAqB,CAAyB;IAE/D;;OAEG;IACH,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAiB;IAE/C;;OAEG;IACH,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAyC;IAExE;;;;;;;OAOG;gBAED,qBAAqB,EAAE,sBAAsB,EAC7C,aAAa,EAAE,cAAc,EAC7B,cAAc,CAAC,EAAE,0BAA0B;IAW7C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA0CG;IACG,SAAS,CACb,SAAS,EAAE,cAAc,EACzB,OAAO,EAAE,aAAa,CAAC,cAAc,CAAC,GACrC,OAAO,CAAC,MAAM,CAAC;IAkClB;;;;OAIG;IACH,OAAO,CAAC,QAAQ;CAMjB"}

package/dist/rendering/templates/template-provider.factory.d.ts

@@ -0,0 +1,35 @@
+import { ITemplateProvider } from "./template-provider.js";
+import type { IComponentMetadataRegistry } from "../../core/component-metadata-registry.interface.js";
+/**
+ * Factory for creating TemplateProvider instances.
+ * Implements the Factory Pattern for centralized object creation.
+ *
+ * @description
+ * Provides a centralized way to create TemplateProvider instances with their dependencies.
+ * Ensures consistent dependency injection and allows for easy testing and mocking.
+ *
+ * @example
+ * ```typescript
+ * const provider = TemplateProviderFactory.createDefault(metadataSource);
+ * const template = await provider.getSource(component, options);
+ * ```
+ */
+export declare class TemplateProviderFactory {
+    /**
+     * Creates a TemplateProvider with default dependencies.
+     *
+     * @param metadataSource - Optional metadata source for component metadata lookup
+     * @returns A fully configured TemplateProvider instance
+     */
+    static createDefault(metadataSource?: IComponentMetadataRegistry): ITemplateProvider;
+    /**
+     * Creates a TemplateProvider with custom dependencies.
+     *
+     * @param staticBindingResolver - Custom static binding resolver implementation
+     * @param rulesResolver - Custom rules resolver implementation
+     * @param metadataSource - Optional metadata source for component metadata lookup
+     * @returns A TemplateProvider instance with custom dependencies
+     */
+    static createWithDependencies(staticBindingResolver: import("../bindings/static-binding-resolver.interface.js").IStaticBindingResolver, rulesResolver: import("../bindings/rules-resolver.interface.js").IRulesResolver, metadataSource?: IComponentMetadataRegistry): ITemplateProvider;
+}
+//# sourceMappingURL=template-provider.factory.d.ts.map

package/dist/rendering/templates/template-provider.factory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"template-provider.factory.d.ts","sourceRoot":"","sources":["../../../src/rendering/templates/template-provider.factory.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAC3D,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,qDAAqD,CAAC;AAEtG;;;;;;;;;;;;;GAaG;AACH,qBAAa,uBAAuB;IAClC;;;;;OAKG;IACH,MAAM,CAAC,aAAa,CAClB,cAAc,CAAC,EAAE,0BAA0B,GAC1C,iBAAiB;IAWpB;;;;;;;OAOG;IACH,MAAM,CAAC,sBAAsB,CAC3B,qBAAqB,EAAE,OAAO,kDAAkD,EAAE,sBAAsB,EACxG,aAAa,EAAE,OAAO,yCAAyC,EAAE,cAAc,EAC/E,cAAc,CAAC,EAAE,0BAA0B,GAC1C,iBAAiB;CAOrB"}