@adaas/are-html 0.0.2 → 0.0.4

package/dist/browser/index.mjs

@@ -1,7 +1,7 @@
 import { AreStore, AreScene, AreSyntax, AreCompiler, AreInterpreter, AreInstructionDefaultNames, AreNodeFeatures, AreContext, AreLifecycle, AreSignalsContext, AreAttributeFeatures, Are, AreNode, AreAttribute, AreCompilerError, AreMutation, AreDeclaration, AreSignal, AreInterpreterError, AreTokenizer, AreTransformer, AreEngine, AreRoute as AreRoute$1, AreSignals, AreEvent } from '@adaas/are';
+import { A_Frame } from '@adaas/a-frame/core';
 import { A_Inject, A_Caller, A_Feature, A_Meta, A_Scope, A_Dependency, A_Component, A_Context, A_ComponentMeta, A_FormatterHelper, A_Fragment } from '@adaas/a-concept';
 import { A_Logger } from '@adaas/a-utils/a-logger';
-import { A_Frame } from '@adaas/a-frame';
 import { A_ExecutionContext } from '@adaas/a-utils/a-execution';
 import { A_Route } from '@adaas/a-utils/a-route';
 import { A_ServiceFeatures } from '@adaas/a-utils/a-service';
@@ -23,8 +23,12 @@ var AreHTMLAttribute = class extends AreAttribute {
     return this.scope.issuer();
   }
 };
-
-// src/attributes/AreBinding.attribute.ts
+AreHTMLAttribute = __decorateClass([
+  A_Frame.Define({
+    namespace: "a-are-html",
+    description: "Base class for all typed HTML attributes in the ARE framework. Provides typed access to the owning AreHTMLNode via the scope injector so that attribute subclasses can inspect host-node properties and resolve store bindings during transformation, compilation, and lifecycle phases."
+  })
+], AreHTMLAttribute);
 var AreBindingAttribute = class extends AreHTMLAttribute {
   // get value(): string {
   //     const [firstPart, ...pathPart] = this.content.split('.');
@@ -32,6 +36,12 @@ var AreBindingAttribute = class extends AreHTMLAttribute {
   //     return AreCommonHelper.extractPropertyByPath(primaryObject, pathPart.join('.')) as string;
   // }
 };
+AreBindingAttribute = __decorateClass([
+  A_Frame.Define({
+    namespace: "a-are-html",
+    description: "Attribute type for two-way value bindings (: prefix). Marks that the attribute value should be resolved dynamically from the node store rather than used verbatim, enabling reactive updates whenever the underlying store value changes during a rendering cycle."
+  })
+], AreBindingAttribute);
 var AreDirectiveAttribute = class extends AreHTMLAttribute {
   /**
    * Returns a custom directive component associated with this attribute, if available.
@@ -43,14 +53,28 @@ var AreDirectiveAttribute = class extends AreHTMLAttribute {
     return component;
   }
 };
-
-// src/attributes/AreEvent.attribute.ts
+AreDirectiveAttribute = __decorateClass([
+  A_Frame.Define({
+    namespace: "a-are-html",
+    description: "Attribute type for directive invocations ($ prefix). Carries the resolved directive component class and a cloned template node. The associated directive uses these during its Compile phase to emit conditional or repeated instruction groups and to manage per-item or per-condition subscopes."
+  })
+], AreDirectiveAttribute);
 var AreEventAttribute = class extends AreHTMLAttribute {
 };
-
-// src/attributes/AreStatic.attribute.ts
+AreEventAttribute = __decorateClass([
+  A_Frame.Define({
+    namespace: "a-are-html",
+    description: "Attribute type for DOM event listeners (@ prefix). Marks the attribute as an event binding \u2014 the compiler emits an AddListener instruction that attaches a handler expression resolved from the store to the specified event name on the host element."
+  })
+], AreEventAttribute);
 var AreStaticAttribute = class extends AreHTMLAttribute {
 };
+AreStaticAttribute = __decorateClass([
+  A_Frame.Define({
+    namespace: "a-are-html",
+    description: "Attribute type for plain static HTML attributes with no dynamic prefix. Its value is emitted verbatim via an AddAttribute instruction at compile time and does not participate in reactive update cycles."
+  })
+], AreStaticAttribute);
 var AreDirectiveMeta = class extends A_ComponentMeta {
   constructor() {
     super(...arguments);
@@ -73,8 +97,6 @@ var AreDirectiveFeatures = {
    */
   Update: "_AreDirective_Update"
 };
-
-// src/lib/AreDirective/AreDirective.component.ts
 var AreDirective = class extends A_Component {
   //==================================================================================
   //======================== LIFECYCLE DECORATORS ====================================
@@ -170,6 +192,10 @@ __decorateClass([
   __decorateParam(0, A_Inject(A_Caller))
 ], AreDirective.prototype, "update", 1);
 AreDirective = __decorateClass([
+  A_Frame.Define({
+    namespace: "a-are-html",
+    description: "Abstract base component for all ARE directive types. Provides lifecycle decorators (Transform, Compile, Apply, Revert, Priority) that subclasses hook into at each pipeline stage. Subclasses implement Transform to rewrite the attribute or template node, Compile to emit scene instructions, Apply to activate them in the DOM, and Revert to undo them on removal."
+  }),
   A_Meta.Define(AreDirectiveMeta)
 ], AreDirective);
 
@@ -198,9 +224,8 @@ var AddCommentInstruction = class extends AreDeclaration {
   }
 };
 AddCommentInstruction = __decorateClass([
-  A_Frame.Component({
-    namespace: "A-ARE",
-    name: "AddCommentInstruction",
+  A_Frame.Define({
+    namespace: "a-are-html",
     description: "Appends a comment node to an element. Apply creates the comment node; revert removes it. Content can be a static string or a dynamic getter for interpolations."
   })
 ], AddCommentInstruction);
@@ -210,8 +235,6 @@ var AreDirectiveContext = class extends A_ExecutionContext {
     this.scope = {};
   }
 };
-
-// src/directives/AreDirectiveFor.directive.ts
 var AreDirectiveFor = class extends AreDirective {
   transform(attribute, scope, store, scene, logger, ...args) {
     logger.debug(`[Transform] directive $FOR for <${attribute.owner.aseid.toString()}>`);
@@ -227,11 +250,9 @@ var AreDirectiveFor = class extends AreDirective {
     const { key, index, arrayExpr } = this.parseExpression(attribute.content);
     const array = this.resolveArray(store, arrayExpr, attribute.content);
     attribute.value = array;
-    console.log('Initial array for "for" directive:', scene);
     for (let i = 0; i < array.length; i++) {
       this.spawnItemNode(attribute.template, attribute.owner, key, index, array[i], i);
     }
-    console.log('Template for "for" directive:', forTemplate);
   }
   compile(attribute, store, scene, ...args) {
     const hostInstruction = scene.host;
@@ -242,49 +263,78 @@ var AreDirectiveFor = class extends AreDirective {
     scene.unPlan(hostInstruction);
   }
   update(attribute, store, scene, ...args) {
-    const { key, index, arrayExpr } = this.parseExpression(attribute.content);
+    const { key, index, arrayExpr, trackExpr } = this.parseExpression(attribute.content);
     const newArray = this.resolveArray(store, arrayExpr, attribute.content);
     const owner = attribute.owner;
     const currentChildren = [...owner.children];
     attribute.value = newArray;
-    const newLen = newArray.length;
-    const newItemSet = new Set(newArray);
-    const keptChildren = [];
-    const removedChildren = [];
-    for (const child of currentChildren) {
+    const computeKey = this.makeKeyFn(key, index, trackExpr);
+    const childByKey = /* @__PURE__ */ new Map();
+    const remaining = /* @__PURE__ */ new Set();
+    for (let i = 0; i < currentChildren.length; i++) {
+      const child = currentChildren[i];
       const ctx = child.scope.resolveFlat(AreDirectiveContext);
-      if (ctx && newItemSet.has(ctx.scope[key])) {
-        keptChildren.push(child);
+      const k = ctx ? computeKey(ctx.scope[key], ctx.scope[index || "index"]) : /* @__PURE__ */ Symbol("orphan");
+      childByKey.set(k, child);
+      remaining.add(child);
+    }
+    const newOnes = [];
+    for (let i = 0; i < newArray.length; i++) {
+      const item = newArray[i];
+      const k = computeKey(item, i);
+      const existing = childByKey.get(k);
+      if (existing) {
+        remaining.delete(existing);
+        let directiveContext = existing.scope.resolveFlat(AreDirectiveContext);
+        if (!directiveContext) {
+          directiveContext = new AreDirectiveContext(existing.aseid);
+          existing.scope.register(directiveContext);
+        }
+        directiveContext.scope = {
+          ...directiveContext.scope,
+          [key]: item,
+          [index || "index"]: i
+        };
       } else {
-        removedChildren.push(child);
+        const itemNode = this.spawnItemNode(attribute.template, owner, key, index, item, i);
+        newOnes.push(itemNode);
       }
     }
-    for (const child of removedChildren) {
+    for (const child of remaining) {
       child.unmount();
       owner.removeChild(child);
     }
-    for (let i = 0; i < keptChildren.length; i++) {
-      let directiveContext = keptChildren[i].scope.resolveFlat(AreDirectiveContext);
-      if (!directiveContext) {
-        directiveContext = new AreDirectiveContext(keptChildren[i].aseid);
-        keptChildren[i].scope.register(directiveContext);
-      }
-      directiveContext.scope = {
-        ...directiveContext.scope,
-        [key]: newArray[i],
-        [index || "index"]: i
-      };
-    }
-    for (let i = keptChildren.length; i < newLen; i++) {
-      const itemNode = this.spawnItemNode(attribute.template, owner, key, index, newArray[i], i);
-      itemNode.transform();
-      itemNode.compile();
-      itemNode.mount();
+    for (const child of newOnes) {
+      child.transform();
+      child.compile();
+      child.mount();
     }
   }
   // ─────────────────────────────────────────────────────────────────────────────
   // ── Helpers ──────────────────────────────────────────────────────────────────
   // ─────────────────────────────────────────────────────────────────────────────
+  /**
+   * Build a key-function that derives a stable identity from each item.
+   * If the user provided a `track <expr>` clause, evaluate it as a path on
+   * the item; otherwise fall back to the item identity (reference equality).
+   */
+  makeKeyFn(key, index, trackExpr) {
+    if (!trackExpr) {
+      return (item, i) => item ?? i;
+    }
+    const path = trackExpr.startsWith(key + ".") ? trackExpr.slice(key.length + 1) : trackExpr;
+    return (item, i) => {
+      if (item == null) return i;
+      if (path === key || path === "$index") return path === "$index" ? i : item;
+      const parts = path.split(".");
+      let v = item;
+      for (const p of parts) {
+        if (v == null) return i;
+        v = v[p];
+      }
+      return v ?? i;
+    };
+  }
   /**
    * Parses the $for expression string into its constituent parts.
    *
@@ -294,16 +344,29 @@ var AreDirectiveFor = class extends AreDirective {
    *   (item, index) in items
    *   item in filter(items)
    *   item, index in filter(items, 'active')
+   *   item in items track item.id
+   *   (item, i) in items track item.id
    */
   parseExpression(content) {
-    const inIndex = content.lastIndexOf(" in ");
-    const keyAndIndex = content.slice(0, inIndex).trim().replace(/^\(|\)$/g, "");
-    const arrayExpr = content.slice(inIndex + 4).trim();
+    let trackExpr;
+    const trackIdx = content.search(/\s+track\s+/);
+    let body = content;
+    if (trackIdx !== -1) {
+      const m = content.slice(trackIdx).match(/\s+track\s+(.+)$/);
+      if (m) {
+        trackExpr = m[1].trim();
+        body = content.slice(0, trackIdx).trim();
+      }
+    }
+    const inIndex = body.lastIndexOf(" in ");
+    const keyAndIndex = body.slice(0, inIndex).trim().replace(/^\(|\)$/g, "");
+    const arrayExpr = body.slice(inIndex + 4).trim();
     const keyParts = keyAndIndex.split(",").map((p) => p.trim());
     return {
       key: keyParts[0],
       index: keyParts[1] || void 0,
-      arrayExpr
+      arrayExpr,
+      trackExpr
     };
   }
   /**
@@ -394,6 +457,10 @@ __decorateClass([
   __decorateParam(2, A_Inject(AreScene))
 ], AreDirectiveFor.prototype, "update", 1);
 AreDirectiveFor = __decorateClass([
+  A_Frame.Define({
+    namespace: "a-are-html",
+    description: "Built-in $for directive. Iterates over an array expression resolved from the store and renders a cloned template fragment per item, managing per-item subscopes and comment-node anchors. Supports keyed diffing via an optional track clause to minimise DOM mutations on collection updates."
+  }),
   AreDirective.Priority(1)
 ], AreDirectiveFor);
 var AreDirectiveIf = class extends AreDirective {
@@ -412,7 +479,6 @@ var AreDirectiveIf = class extends AreDirective {
     attribute.template = ifTemplate;
   }
   compile(attribute, store, scene, syntax, directiveContext, ...args) {
-    console.log('Compiling directive "if" with attribute content:', attribute);
     attribute.value = syntax.evaluate(attribute.content, store, {
       ...directiveContext?.scope || {}
     });
@@ -428,8 +494,11 @@ var AreDirectiveIf = class extends AreDirective {
       attribute.template.scene.deactivate();
   }
   update(attribute, store, scope, syntax, scene, ...args) {
-    attribute.value = syntax.evaluate(attribute.content, store);
-    if (attribute.value) {
+    const previous = !!attribute.value;
+    const next = !!syntax.evaluate(attribute.content, store);
+    attribute.value = next;
+    if (previous === next) return;
+    if (next) {
       attribute.template.scene.activate();
       attribute.template.mount();
     } else {
@@ -463,6 +532,10 @@ __decorateClass([
   __decorateParam(4, A_Inject(AreScene))
 ], AreDirectiveIf.prototype, "update", 1);
 AreDirectiveIf = __decorateClass([
+  A_Frame.Define({
+    namespace: "a-are-html",
+    description: "Built-in $if directive. Conditionally renders a subtree based on a store expression. Replaces the target element with a stable comment anchor when the condition is false and restores the fully rendered subtree when it becomes true, preventing any leaking of the host element between states."
+  }),
   AreDirective.Priority(2)
 ], AreDirectiveIf);
 var AddAttributeInstruction = class extends AreMutation {
@@ -475,9 +548,8 @@ var AddAttributeInstruction = class extends AreMutation {
   }
 };
 AddAttributeInstruction = __decorateClass([
-  A_Frame.Component({
-    namespace: "A-ARE",
-    name: "AddAttributeInstruction",
+  A_Frame.Define({
+    namespace: "a-are-html",
     description: "Sets an attribute on an HTML element. Apply calls setAttribute; revert calls removeAttribute."
   })
 ], AddAttributeInstruction);
@@ -491,9 +563,8 @@ var AddElementInstruction = class extends AreDeclaration {
   }
 };
 AddElementInstruction = __decorateClass([
-  A_Frame.Component({
-    namespace: "A-ARE",
-    name: "AddElementInstruction",
+  A_Frame.Define({
+    namespace: "a-are-html",
     description: "Creates a new HTML element in the DOM. Apply creates the element; revert removes it."
   })
 ], AddElementInstruction);
@@ -507,9 +578,8 @@ var AddInterpolationInstruction = class extends AreMutation {
   }
 };
 AddInterpolationInstruction = __decorateClass([
-  A_Frame.Component({
-    namespace: "A-ARE",
-    name: "AddInterpolationInstruction",
+  A_Frame.Define({
+    namespace: "a-are-html",
     description: "Appends a reactive text node whose content is resolved dynamically from the store. Apply creates the text node with the getter; revert removes it."
   })
 ], AddInterpolationInstruction);
@@ -523,9 +593,8 @@ var AddListenerInstruction = class extends AreMutation {
   }
 };
 AddListenerInstruction = __decorateClass([
-  A_Frame.Component({
-    namespace: "A-ARE",
-    name: "AddListenerInstruction",
+  A_Frame.Define({
+    namespace: "a-are-html",
     description: "Attaches a DOM event listener to an element. Apply calls addEventListener; revert calls removeEventListener."
   })
 ], AddListenerInstruction);
@@ -539,9 +608,8 @@ var AddStyleInstruction = class extends AreMutation {
   }
 };
 AddStyleInstruction = __decorateClass([
-  A_Frame.Component({
-    namespace: "A-ARE",
-    name: "AddStyleInstruction",
+  A_Frame.Define({
+    namespace: "a-are-html",
     description: "Sets an inline CSS style property on an element. Apply sets the property; revert removes it."
   })
 ], AddStyleInstruction);
@@ -555,9 +623,8 @@ var AddTextInstruction = class extends AreDeclaration {
   }
 };
 AddTextInstruction = __decorateClass([
-  A_Frame.Component({
-    namespace: "A-ARE",
-    name: "AddTextInstruction",
+  A_Frame.Define({
+    namespace: "a-are-html",
     description: "Appends a text node to an element. Apply creates the text node; revert removes it. Content can be a static string or a dynamic getter for interpolations."
   })
 ], AddTextInstruction);
@@ -569,6 +636,12 @@ var AreStyle = class extends A_Fragment {
     this.styles = styles;
   }
 };
+AreStyle = __decorateClass([
+  A_Frame.Define({
+    namespace: "a-are-html",
+    description: "Context fragment that holds the resolved CSS style rules string for a component scope. Populated during lifecycle initialisation and read by the compiler when emitting AddStyle instructions for inline styles declared on the component host element."
+  })
+], AreStyle);
 
 // src/lib/AreHTMLNode/AreHTMLNode.ts
 var AreHTMLNode = class extends AreNode {
@@ -626,14 +699,11 @@ var AreHTMLNode = class extends AreNode {
   }
 };
 AreHTMLNode = __decorateClass([
-  A_Frame.Entity({
-    namespace: "A-ARE",
-    name: "AreHTMLNode",
+  A_Frame.Define({
+    namespace: "a-are-html",
     description: "AreHTMLNode represents a node in the HTML structure. It extends the base AreNode and includes properties and methods specific to HTML nodes, such as handling attributes, directives, events, and styles."
   })
 ], AreHTMLNode);
-
-// src/nodes/AreComment.ts
 var AreComment = class extends AreHTMLNode {
   fromNew(newEntity) {
     super.fromNew({
@@ -645,6 +715,12 @@ var AreComment = class extends AreHTMLNode {
     });
   }
 };
+AreComment = __decorateClass([
+  A_Frame.Define({
+    namespace: "a-are-html",
+    description: "Node type representing a comment node in the AreHTMLNode tree. Used as a stable DOM anchor by structural directives such as $if and $for that swap rendered content in and out, ensuring the parent container always has a consistent insertion point."
+  })
+], AreComment);
 var AreComponentNode = class extends AreHTMLNode {
   /**
    * A custom component associated with this node, which can be used to provide custom logic and behavior for the node. This component is typically defined in the context and can be resolved based on the node's type or other identifying information. The component can include its own template, markup, styles, and features that are specific to the functionality it provides.
@@ -658,14 +734,11 @@ var AreComponentNode = class extends AreHTMLNode {
   }
 };
 AreComponentNode = __decorateClass([
-  A_Frame.Entity({
-    namespace: "A-ARE",
-    name: "AreComponentNode",
+  A_Frame.Define({
+    namespace: "a-are-html",
     description: "AreComponentNode represents a node in the scene graph that corresponds to a component. It extends the base AreNode and includes additional properties and methods specific to component nodes, such as handling attributes, bindings, directives, events, styles, and interpolations associated with the component."
   })
 ], AreComponentNode);
-
-// src/nodes/AreInterpolation.ts
 var AreInterpolation = class extends AreHTMLNode {
   fromNew(newEntity) {
     super.fromNew({
@@ -677,6 +750,12 @@ var AreInterpolation = class extends AreHTMLNode {
     });
   }
 };
+AreInterpolation = __decorateClass([
+  A_Frame.Define({
+    namespace: "a-are-html",
+    description: "Node type representing a reactive inline expression in the AreHTMLNode tree. Its content expression is resolved from the store at render time and kept live via an AddInterpolation instruction that updates the corresponding text node on each reactive cycle."
+  })
+], AreInterpolation);
 var AreRootNode = class extends AreHTMLNode {
   /**
    * For the root node, we can default to a generic container element like <div> since it serves as the root of the component tree and does not correspond to a specific HTML tag defined in the markup. The actual content and structure of the root node will be determined by the child nodes and components that are rendered within it, allowing for flexibility in how the root node is used and what it contains.
@@ -696,14 +775,11 @@ var AreRootNode = class extends AreHTMLNode {
   }
 };
 AreRootNode = __decorateClass([
-  A_Frame.Entity({
-    namespace: "A-ARE",
-    name: "AreRootNode",
+  A_Frame.Define({
+    namespace: "a-are-html",
     description: "AreRootNode represents the root node in the scene graph. It extends the base AreHTMLNode and includes additional properties and methods specific to the root node, such as handling the root element and its associated component."
   })
 ], AreRootNode);
-
-// src/nodes/AreText.ts
 var AreText = class extends AreHTMLNode {
   fromNew(newEntity) {
     super.fromNew({
@@ -715,7 +791,13 @@ var AreText = class extends AreHTMLNode {
     });
   }
 };
-var AreRoute = class _AreRoute extends AreSignal {
+AreText = __decorateClass([
+  A_Frame.Define({
+    namespace: "a-are-html",
+    description: "Node type representing a plain or partially-dynamic text segment in the AreHTMLNode tree. Emits an AddText instruction that sets or updates the corresponding DOM text node; the content may carry a store getter for any dynamic portion."
+  })
+], AreText);
+var AreRoute = class extends AreSignal {
   constructor(path) {
     super({
       data: new A_Route(path)
@@ -725,12 +807,110 @@ var AreRoute = class _AreRoute extends AreSignal {
     return this.data;
   }
   static default() {
-    return new _AreRoute(document.location.pathname || "/");
+    return new AreRoute(document.location.pathname || "/");
   }
   compare(other) {
     return this.route.toRegExp().test(other.data.toString());
   }
 };
+AreRoute = __decorateClass([
+  A_Frame.Define({
+    namespace: "a-are-html",
+    description: "ARE signal that carries an A_Route value. Dispatched by AreRouteWatcher on client-side navigation events (pushState, replaceState, popstate). The signal bus delivers it to all subscribed root nodes, triggering route-based conditional rendering across the component tree."
+  })
+], AreRoute);
+
+// src/engine/AreHTML.constants.ts
+var BOOLEAN_ATTRIBUTES = /* @__PURE__ */ new Set([
+  "allowfullscreen",
+  "async",
+  "autofocus",
+  "autoplay",
+  "checked",
+  "controls",
+  "default",
+  "defer",
+  "disabled",
+  "formnovalidate",
+  "hidden",
+  "inert",
+  "ismap",
+  "itemscope",
+  "loop",
+  "multiple",
+  "muted",
+  "nomodule",
+  "novalidate",
+  "open",
+  "playsinline",
+  "readonly",
+  "required",
+  "reversed",
+  "selected"
+]);
+function isBooleanAttribute(name) {
+  return BOOLEAN_ATTRIBUTES.has(name.toLowerCase());
+}
+var IDL_FORM_PROPERTIES = {
+  INPUT: /* @__PURE__ */ new Set(["value", "checked", "indeterminate"]),
+  TEXTAREA: /* @__PURE__ */ new Set(["value"]),
+  SELECT: /* @__PURE__ */ new Set(["value"]),
+  OPTION: /* @__PURE__ */ new Set(["selected"])
+};
+function isIDLFormProperty(tagName, attrName) {
+  const set = IDL_FORM_PROPERTIES[tagName.toUpperCase()];
+  return !!set && set.has(attrName);
+}
+function normalizeClassValue(value) {
+  if (value === null || value === void 0 || value === false) return "";
+  if (typeof value === "string") return value;
+  if (typeof value === "number") return String(value);
+  if (Array.isArray(value)) {
+    return value.map(normalizeClassValue).filter(Boolean).join(" ");
+  }
+  if (typeof value === "object") {
+    const parts = [];
+    for (const key of Object.keys(value)) {
+      if (value[key]) parts.push(key);
+    }
+    return parts.join(" ");
+  }
+  return "";
+}
+function normalizeStyleValue(value) {
+  if (value === null || value === void 0 || value === false) return "";
+  if (typeof value === "string") return value;
+  if (typeof value === "number") return String(value);
+  if (Array.isArray(value)) {
+    return value.map(normalizeStyleValue).filter(Boolean).join("; ");
+  }
+  if (typeof value === "object") {
+    const parts = [];
+    for (const key of Object.keys(value)) {
+      const v = value[key];
+      if (v === null || v === void 0 || v === false) continue;
+      const kebab = key.replace(/[A-Z]/g, (m) => "-" + m.toLowerCase());
+      parts.push(`${kebab}: ${v}`);
+    }
+    return parts.join("; ");
+  }
+  return "";
+}
+function parseEventName(raw) {
+  const [event, ...modifiers] = raw.split(".");
+  return { event, modifiers: new Set(modifiers) };
+}
+var LISTENER_OPTION_MODIFIERS = /* @__PURE__ */ new Set(["capture", "once", "passive"]);
+function toDOMString(value) {
+  if (value === null || value === void 0) return "";
+  if (typeof value === "string") return value;
+  if (typeof value === "number" || typeof value === "boolean") return String(value);
+  try {
+    return JSON.stringify(value);
+  } catch {
+    return "";
+  }
+}
 var AreHTMLEngineContext = class extends AreContext {
   constructor(props) {
     super(props.container?.body.innerHTML || props.source || "");
@@ -856,7 +1036,11 @@ var AreHTMLEngineContext = class extends AreContext {
     if (!this.index.elementListeners.has(element)) {
       this.index.elementListeners.set(element, /* @__PURE__ */ new Map());
     }
-    this.index.elementListeners.get(element).set(eventName, listener);
+    const byEvent = this.index.elementListeners.get(element);
+    if (!byEvent.has(eventName)) {
+      byEvent.set(eventName, /* @__PURE__ */ new Set());
+    }
+    byEvent.get(eventName).add(listener);
   }
   /**
    * Retrieves the event listener associated with a specific DOM element and event name from the context's index. This method looks up the element in the elementListeners map and then retrieves the listener for the specified event name. If no listener is found for the given element and event, it returns undefined. This allows the engine to efficiently access and manage event listeners that have been attached to dynamically created elements, enabling proper cleanup when instructions are reverted or when nodes are removed from the DOM.
@@ -866,6 +1050,14 @@ var AreHTMLEngineContext = class extends AreContext {
    * @returns 
    */
   getListener(element, eventName) {
+    const set = this.index.elementListeners.get(element)?.get(eventName);
+    if (!set || set.size === 0) return void 0;
+    return set.values().next().value;
+  }
+  /**
+   * Returns all listeners registered for a given element + event name.
+   */
+  getListeners(element, eventName) {
     return this.index.elementListeners.get(element)?.get(eventName);
   }
   /**
@@ -874,10 +1066,26 @@ var AreHTMLEngineContext = class extends AreContext {
    * @param element 
    * @param eventName 
    */
-  removeListener(element, eventName) {
-    this.index.elementListeners.get(element)?.delete(eventName);
+  removeListener(element, eventName, listener) {
+    const byEvent = this.index.elementListeners.get(element);
+    if (!byEvent) return;
+    if (listener) {
+      const set = byEvent.get(eventName);
+      if (set) {
+        set.delete(listener);
+        if (set.size === 0) byEvent.delete(eventName);
+      }
+    } else {
+      byEvent.delete(eventName);
+    }
   }
 };
+AreHTMLEngineContext = __decorateClass([
+  A_Frame.Define({
+    namespace: "a-are-html",
+    description: "Runtime index for the HTML rendering engine. Maps each AreNode and instruction ASEID to its corresponding DOM element so that apply and revert handlers on interpreter instructions can look up their DOM node in O(1). Tracks root-element mounts and maintains the group-level index used by structural directives."
+  })
+], AreHTMLEngineContext);
 var AreHTMLCompiler = class extends AreCompiler {
   compileInterpolation(interpolation, scene, store, logger, ...args) {
     scene.plan(new AddTextInstruction({ content: interpolation.content, evaluate: true }));
@@ -919,38 +1127,66 @@ var AreHTMLCompiler = class extends AreCompiler {
       handler: attribute.content
     }));
   }
-  compileBindingAttribute(attribute, scene, parentStore, store, ...args) {
+  compileBindingAttribute(attribute, scene, parentStore, store, syntax, ...args) {
     if (!scene.host)
       throw new AreCompilerError({
         title: "Scene Host Not Found",
         description: `No host found for the scene with id: ${scene.id}. Please ensure that the scene is properly initialized and has a host before compiling binding attributes.`
       });
     const node = attribute.owner;
-    if (node.component && node.component.props[attribute.name]) {
-      const propDefinition = node.component.props[attribute.name];
-      let value = parentStore.get(attribute.content);
-      if (propDefinition.type) {
-        switch (propDefinition.type) {
-          case "string":
-            value = String(value);
-            break;
-          case "number":
-            value = Number(value);
-            break;
-          case "boolean":
-            value = Boolean(value);
-            break;
-        }
+    const props = node.component?.props;
+    let propName;
+    if (props) {
+      if (props[attribute.name]) {
+        propName = attribute.name;
+      } else {
+        const camel = A_FormatterHelper.toCamelCase(attribute.name);
+        if (props[camel]) propName = camel;
       }
-      store.set(attribute.name, value);
-    } else {
-      const instruction = new AddAttributeInstruction(scene.host, {
-        name: attribute.name,
-        content: attribute.content,
-        evaluate: true
-      });
-      scene.plan(instruction);
     }
+    if (propName && props) {
+      const propDefinition = props[propName];
+      const coerce = (raw) => {
+        let value = raw;
+        if (propDefinition.type) {
+          switch (propDefinition.type) {
+            case "string":
+              value = value === void 0 || value === null ? "" : String(value);
+              break;
+            case "number":
+              value = Number(value);
+              break;
+            case "boolean":
+              value = Boolean(value);
+              break;
+          }
+        }
+        return value;
+      };
+      const watcher = {
+        update: () => {
+          try {
+            parentStore.watch(watcher);
+            const next = coerce(syntax.evaluate(attribute.content, parentStore));
+            parentStore.unwatch(watcher);
+            store.set(propName, next);
+          } catch (e) {
+            parentStore.unwatch(watcher);
+          }
+        }
+      };
+      parentStore.watch(watcher);
+      const initial = coerce(syntax.evaluate(attribute.content, parentStore));
+      parentStore.unwatch(watcher);
+      store.set(propName, initial);
+      return;
+    }
+    const instruction = new AddAttributeInstruction(scene.host, {
+      name: attribute.name,
+      content: attribute.content,
+      evaluate: true
+    });
+    scene.plan(instruction);
   }
 };
 __decorateClass([
@@ -989,12 +1225,12 @@ __decorateClass([
   __decorateParam(1, A_Inject(AreScene)),
   __decorateParam(2, A_Dependency.Parent()),
   __decorateParam(2, A_Inject(AreStore)),
-  __decorateParam(3, A_Inject(AreStore))
+  __decorateParam(3, A_Inject(AreStore)),
+  __decorateParam(4, A_Inject(AreSyntax))
 ], AreHTMLCompiler.prototype, "compileBindingAttribute", 1);
 AreHTMLCompiler = __decorateClass([
-  A_Frame.Component({
-    namespace: "A-ARE",
-    name: "AreHTMLCompiler",
+  A_Frame.Define({
+    namespace: "a-are-html",
     description: "HTML-specific compiler for A-Concept Rendering Engine (ARE) components, extending the base AreCompiler to handle HTML templates, styles, and rendering logic tailored for web environments."
   })
 ], AreHTMLCompiler);
@@ -1021,6 +1257,7 @@ var AreHTMLInterpreter = class extends AreInterpreter {
           });
         }
         const element = context.container.createElement(tag);
+        element.setAttribute("data-aseid", node.aseid.toString());
         if (mountPoint.nodeType === Node.ELEMENT_NODE) {
           mountPoint.appendChild(element);
         } else {
@@ -1062,23 +1299,80 @@ var AreHTMLInterpreter = class extends AreInterpreter {
       });
     }
     const { name, content, evaluate } = mutation.payload;
-    const value = evaluate ? syntax.evaluate(content, store, {
+    const rawValue = evaluate ? syntax.evaluate(content, store, {
       ...directiveContext?.scope || {}
     }) : content;
-    if (mutation.cache === void 0) {
-      const existingValue = element.getAttribute(name);
-      const result = existingValue ? `${existingValue} ${value}` : value;
-      element.setAttribute(name, result);
-      mutation.cache = value;
+    const el = element;
+    const lowerName = name.toLowerCase();
+    if (isBooleanAttribute(lowerName)) {
+      if (rawValue) {
+        el.setAttribute(lowerName, "");
+        try {
+          el[lowerName] = true;
+        } catch {
+        }
+      } else {
+        el.removeAttribute(lowerName);
+        try {
+          el[lowerName] = false;
+        } catch {
+        }
+      }
+      mutation.cache = rawValue ? "true" : "";
+      return;
+    }
+    if (isIDLFormProperty(el.tagName, name)) {
+      const propName = name === "value" ? "value" : name === "checked" ? "checked" : name === "selected" ? "selected" : name === "indeterminate" ? "indeterminate" : name;
+      try {
+        if (propName === "checked" || propName === "selected" || propName === "indeterminate") {
+          el[propName] = !!rawValue;
+        } else {
+          el[propName] = toDOMString(rawValue);
+        }
+      } catch {
+      }
+      if (propName !== "value") {
+        if (rawValue) el.setAttribute(name, "");
+        else el.removeAttribute(name);
+      } else {
+        el.setAttribute(name, toDOMString(rawValue));
+      }
+      mutation.cache = toDOMString(rawValue);
+      return;
+    }
+    if (lowerName === "class") {
+      const newValue = normalizeClassValue(rawValue);
+      if (mutation.cache === void 0) {
+        const existingValue = el.getAttribute("class");
+        const merged = existingValue ? `${existingValue} ${newValue}`.trim() : newValue;
+        if (merged) el.setAttribute("class", merged);
+        else el.removeAttribute("class");
+      } else {
+        const existingValue = el.getAttribute("class");
+        const existingParts = existingValue ? existingValue.split(/\s+/).filter(Boolean) : [];
+        const oldParts = new Set(mutation.cache.split(/\s+/).filter(Boolean));
+        const newParts = newValue ? newValue.split(/\s+/).filter(Boolean) : [];
+        const merged = [...existingParts.filter((p) => !oldParts.has(p)), ...newParts].join(" ");
+        if (merged) el.setAttribute("class", merged);
+        else el.removeAttribute("class");
+      }
+      mutation.cache = newValue;
+      return;
+    }
+    if (lowerName === "style") {
+      const newValue = normalizeStyleValue(rawValue);
+      if (newValue) el.setAttribute("style", newValue);
+      else el.removeAttribute("style");
+      mutation.cache = newValue;
+      return;
+    }
+    const stringValue = toDOMString(rawValue);
+    if (stringValue === "" && evaluate && (rawValue === false || rawValue === null || rawValue === void 0)) {
+      el.removeAttribute(name);
     } else {
-      const existingValue = element.getAttribute(name);
-      const existingParts = existingValue ? existingValue.split(/\s+/).filter(Boolean) : [];
-      const oldParts = new Set(mutation.cache.split(/\s+/).filter(Boolean));
-      const newParts = value ? value.split(/\s+/).filter(Boolean) : [];
-      const result = [...existingParts.filter((part) => !oldParts.has(part)), ...newParts].join(" ");
-      element.setAttribute(name, result);
-      mutation.cache = value;
+      el.setAttribute(name, stringValue);
     }
+    mutation.cache = stringValue;
   }
   removeAttribute(mutation, context) {
     try {
@@ -1100,12 +1394,19 @@ var AreHTMLInterpreter = class extends AreInterpreter {
         description: `Could not find a DOM element associated with the instruction ASEID "${mutation.parent}". Ensure that the parent instruction is properly rendered and associated with a DOM element before adding event listeners.`
       });
     }
+    const { event: eventName, modifiers } = parseEventName(mutation.payload.name);
+    const listenerOptions = {};
+    if (modifiers.has("capture")) listenerOptions.capture = true;
+    if (modifiers.has("once")) listenerOptions.once = true;
+    if (modifiers.has("passive")) listenerOptions.passive = true;
     const handlers = syntax.extractEmitHandlers(mutation.payload.handler);
+    let liveEvent = null;
     const handlerScope = {};
     for (const handler of handlers) {
       const handlerFn = (...args) => {
         const event = new AreEvent(handler);
-        event.set("args", args);
+        const effectiveArgs = args.length === 0 && liveEvent ? [liveEvent] : liveEvent ? [...args, liveEvent] : args;
+        event.set("args", effectiveArgs);
         event.set("element", element);
         event.set("instruction", mutation);
         mutation.owner.emit(event);
@@ -1113,34 +1414,80 @@ var AreHTMLInterpreter = class extends AreInterpreter {
       handlerScope[`$${handler}`] = handlerFn;
     }
     const callback = (e) => {
-      context.startPerformance("Click");
-      const result = syntax.evaluate(mutation.payload.handler, store, {
-        ...handlerScope,
-        ...directiveContext?.scope || {}
-      });
-      if (typeof result === "function") result(e);
+      try {
+        liveEvent = e;
+        if (modifiers.has("self") && e.target !== element) return;
+        if (modifiers.has("stop")) e.stopPropagation();
+        if (modifiers.has("prevent")) e.preventDefault();
+        if (e instanceof KeyboardEvent && modifiers.size > 0) {
+          const key = (e.key || "").toLowerCase();
+          const KEY_ALIASES = {
+            enter: ["enter"],
+            esc: ["escape"],
+            escape: ["escape"],
+            tab: ["tab"],
+            space: [" ", "spacebar"],
+            up: ["arrowup"],
+            down: ["arrowdown"],
+            left: ["arrowleft"],
+            right: ["arrowright"],
+            delete: ["delete", "backspace"]
+          };
+          const keyMods = [...modifiers].filter((m) => m in KEY_ALIASES || m === "ctrl" || m === "alt" || m === "shift" || m === "meta");
+          if (keyMods.length > 0) {
+            const keyMatch = keyMods.some((m) => {
+              if (m === "ctrl") return e.ctrlKey;
+              if (m === "alt") return e.altKey;
+              if (m === "shift") return e.shiftKey;
+              if (m === "meta") return e.metaKey;
+              const aliases = KEY_ALIASES[m];
+              return aliases && aliases.includes(key);
+            });
+            if (!keyMatch) return;
+          }
+        }
+        context.startPerformance("event:" + eventName);
+        const result = syntax.evaluate(mutation.payload.handler, store, {
+          ...handlerScope,
+          $event: e,
+          ...directiveContext?.scope || {}
+        });
+        if (typeof result === "function") result(e);
+        context.endPerformance("event:" + eventName);
+      } catch (err) {
+        logger?.error(err);
+      } finally {
+        liveEvent = null;
+      }
     };
-    if (callback) {
-      element.addEventListener(mutation.payload.name, callback);
-      context.addListener(element, mutation.payload.name, callback);
+    const useOptions = listenerOptions.capture || listenerOptions.once || listenerOptions.passive;
+    if (useOptions) {
+      element.addEventListener(eventName, callback, listenerOptions);
+    } else {
+      element.addEventListener(eventName, callback);
     }
+    mutation.payload._callback = callback;
+    context.addListener(element, mutation.payload.name, callback);
   }
   removeEventListener(mutation, context) {
     const element = context.getElementByInstruction(mutation.parent);
     if (!element) return;
     const { name } = mutation.payload;
-    const listener = context.getListener(element, name);
+    const { event: eventName } = parseEventName(name);
+    const listener = mutation.payload._callback;
     if (listener) {
-      element.removeEventListener(name, listener);
-      context.removeListener(element, name);
+      element.removeEventListener(eventName, listener);
+      context.removeListener(element, name, listener);
+      mutation.payload._callback = void 0;
     }
   }
   addText(declaration, context, store, syntax, directiveContext, logger) {
     const node = declaration.owner.parent;
     const { content, evaluate } = declaration.payload;
-    const value = evaluate ? syntax.evaluate(content, store, {
+    const rawValue = evaluate ? syntax.evaluate(content, store, {
       ...directiveContext?.scope || {}
     }) : content;
+    const value = toDOMString(rawValue);
     if (!node) {
       const textNode = context.container.createTextNode(value);
       context.container.body.appendChild(textNode);
@@ -1173,9 +1520,10 @@ var AreHTMLInterpreter = class extends AreInterpreter {
   addComment(declaration, context, store, syntax, directiveContext, logger) {
     const node = declaration.owner.parent;
     const { content, evaluate } = declaration.payload;
-    const value = evaluate ? syntax.evaluate(content, store, {
+    const rawValue = evaluate ? syntax.evaluate(content, store, {
       ...directiveContext?.scope || {}
     }) : content;
+    const value = toDOMString(rawValue);
     if (!node) {
       const commentNode = context.container.createComment(value);
       context.container.body.appendChild(commentNode);
@@ -1207,7 +1555,7 @@ var AreHTMLInterpreter = class extends AreInterpreter {
   }
 };
 __decorateClass([
-  A_Frame.Method({
+  A_Frame.Define({
     description: "Create an HTML element based on the provided declaration instruction. Handles both root-level mounting and child element creation based on the structural parent hierarchy."
   }),
   AreInterpreter.Apply(AreInstructionDefaultNames.Default),
@@ -1217,7 +1565,7 @@ __decorateClass([
   __decorateParam(2, A_Inject(A_Logger))
 ], AreHTMLInterpreter.prototype, "addElement", 1);
 __decorateClass([
-  A_Frame.Method({
+  A_Frame.Define({
     description: "Remove an HTML element that was created by a CreateElement declaration. Cleans up the DOM and the context index."
   }),
   AreInterpreter.Revert(AreInstructionDefaultNames.Default),
@@ -1226,7 +1574,7 @@ __decorateClass([
   __decorateParam(1, A_Inject(AreHTMLEngineContext))
 ], AreHTMLInterpreter.prototype, "removeElement", 1);
 __decorateClass([
-  A_Frame.Method({
+  A_Frame.Define({
     description: "Add an attribute to an HTML element based on the provided mutation instruction."
   }),
   AreInterpreter.Apply(AreHTMLInstructions.AddAttribute),
@@ -1239,7 +1587,7 @@ __decorateClass([
   __decorateParam(5, A_Inject(A_Logger))
 ], AreHTMLInterpreter.prototype, "addAttribute", 1);
 __decorateClass([
-  A_Frame.Method({
+  A_Frame.Define({
     description: "Remove an attribute from an HTML element based on the provided mutation instruction."
   }),
   AreInterpreter.Revert(AreHTMLInstructions.AddAttribute),
@@ -1247,7 +1595,7 @@ __decorateClass([
   __decorateParam(1, A_Inject(AreHTMLEngineContext))
 ], AreHTMLInterpreter.prototype, "removeAttribute", 1);
 __decorateClass([
-  A_Frame.Method({
+  A_Frame.Define({
     description: "Add an event listener to an HTML element based on the provided mutation instruction."
   }),
   AreInterpreter.Apply(AreHTMLInstructions.AddListener),
@@ -1259,7 +1607,7 @@ __decorateClass([
   __decorateParam(5, A_Inject(A_Logger))
 ], AreHTMLInterpreter.prototype, "addEventListener", 1);
 __decorateClass([
-  A_Frame.Method({
+  A_Frame.Define({
     description: "Remove an event listener from an HTML element based on the provided mutation instruction."
   }),
   AreInterpreter.Revert(AreHTMLInstructions.AddListener),
@@ -1267,7 +1615,7 @@ __decorateClass([
   __decorateParam(1, A_Inject(AreHTMLEngineContext))
 ], AreHTMLInterpreter.prototype, "removeEventListener", 1);
 __decorateClass([
-  A_Frame.Method({
+  A_Frame.Define({
     description: "Add text content to an HTML element based on the provided declaration instruction."
   }),
   AreInterpreter.Apply(AreHTMLInstructions.AddText),
@@ -1280,7 +1628,7 @@ __decorateClass([
   __decorateParam(5, A_Inject(A_Logger))
 ], AreHTMLInterpreter.prototype, "addText", 1);
 __decorateClass([
-  A_Frame.Method({
+  A_Frame.Define({
     description: "Remove text content from an HTML element based on the provided declaration instruction."
   }),
   AreInterpreter.Revert(AreHTMLInstructions.AddText),
@@ -1288,7 +1636,7 @@ __decorateClass([
   __decorateParam(1, A_Inject(AreHTMLEngineContext))
 ], AreHTMLInterpreter.prototype, "removeText", 1);
 __decorateClass([
-  A_Frame.Method({
+  A_Frame.Define({
     description: "Add a comment node to the DOM based on the provided declaration instruction."
   }),
   AreInterpreter.Apply(AreHTMLInstructions.AddComment),
@@ -1301,7 +1649,7 @@ __decorateClass([
   __decorateParam(5, A_Inject(A_Logger))
 ], AreHTMLInterpreter.prototype, "addComment", 1);
 __decorateClass([
-  A_Frame.Method({
+  A_Frame.Define({
     description: "Remove a comment node from the DOM based on the provided declaration instruction."
   }),
   AreInterpreter.Revert(AreHTMLInstructions.AddComment),
@@ -1309,16 +1657,15 @@ __decorateClass([
   __decorateParam(1, A_Inject(AreHTMLEngineContext))
 ], AreHTMLInterpreter.prototype, "removeComment", 1);
 AreHTMLInterpreter = __decorateClass([
-  A_Frame.Component({
-    namespace: "A-ARE",
-    name: "AreHTMLInterpreter",
-    description: "AreHTMLInterpreter is a component that serves as a host for rendering AreNodes into HTML. It provides the necessary context and environment for AreNodes to be rendered and interact with the DOM."
+  A_Frame.Define({
+    namespace: "a-are-html",
+    description: "DOM interpreter for the HTML rendering pipeline. Extends AreInterpreter to apply and revert each ARE instruction type directly against the browser DOM \u2014 creating and removing elements, setting and removing attributes and event listeners, managing inline styles, and inserting text and comment nodes. Driven by the scene diff computed per render cycle."
   })
 ], AreHTMLInterpreter);
 var AreHTMLTokenizer = class extends AreTokenizer {
   constructor() {
     super(...arguments);
-    this.ATTR_PATTERN = /([$:@]?[\w-]+)(?:\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s>/"'=]+)))?/g;
+    this.ATTR_PATTERN = /([$:@]?[\w.-]+)(?:\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s>/"'=]+)))?/g;
   }
   tokenize(node, context, logger) {
     super.tokenize(node, context, logger);
@@ -1371,6 +1718,12 @@ __decorateClass([
   __decorateParam(1, A_Inject(AreContext)),
   __decorateParam(2, A_Inject(A_Logger))
 ], AreHTMLTokenizer.prototype, "tokenize", 1);
+AreHTMLTokenizer = __decorateClass([
+  A_Frame.Define({
+    namespace: "a-are-html",
+    description: "HTML-specific tokenizer extending AreTokenizer. Parses raw HTML template strings into AreHTMLNode trees by scanning element tags and resolving directive ($), event (@), binding (:), and static attributes to their typed attribute classes, constructing AreComponentNode and AreRootNode instances where required."
+  })
+], AreHTMLTokenizer);
 var AreHTMLLifecycle = class extends AreLifecycle {
   initComponent(node, scope, context, logger, ...args) {
     super.init(node, scope, context, logger, ...args);
@@ -1434,6 +1787,12 @@ __decorateClass([
   __decorateParam(2, A_Inject(A_Feature)),
   __decorateParam(3, A_Inject(A_Logger))
 ], AreHTMLLifecycle.prototype, "updateDirectiveAttribute", 1);
+AreHTMLLifecycle = __decorateClass([
+  A_Frame.Define({
+    namespace: "a-are-html",
+    description: "HTML-specific lifecycle handler extending AreLifecycle. Wires DOM-aware init hooks for component nodes, root nodes, interpolations, text nodes, and directive attributes to the ARE rendering pipeline, connecting each entity to its HTML engine context and priming the scene for subsequent compilation and interpretation."
+  })
+], AreHTMLLifecycle);
 var AreHTMLTransformer = class extends AreTransformer {
   transformDirectiveAttribute(directive, store, feature, logger, ...args) {
     store.watch(directive);
@@ -1455,6 +1814,12 @@ __decorateClass([
   __decorateParam(2, A_Inject(A_Feature)),
   __decorateParam(3, A_Inject(A_Logger))
 ], AreHTMLTransformer.prototype, "transformDirectiveAttribute", 1);
+AreHTMLTransformer = __decorateClass([
+  A_Frame.Define({
+    namespace: "a-are-html",
+    description: "HTML-specific transformer extending AreTransformer. Handles directive-attribute structural rewrites before compilation \u2014 sorting directives by declared priority and expanding compound directive expressions \u2014 so the compiler receives a clean, ordered AreHTMLNode tree ready for instruction emission."
+  })
+], AreHTMLTransformer);
 
 // src/engine/AreHTML.engine.ts
 var AreHTMLEngine = class extends AreEngine {
@@ -1566,8 +1931,12 @@ var AreHTMLEngine = class extends AreEngine {
         if (nextOpen !== -1 && nextOpen < nextClose) {
           const charAfter = source[nextOpen + tagName.length + 1];
           if (charAfter === " " || charAfter === ">" || charAfter === "/") {
-            level++;
-            searchIndex = nextOpen + tagName.length + 1;
+            const innerEnd = AreHTMLEngine.findTagClose(source, nextOpen);
+            const isSelfClose = innerEnd !== -1 && source[innerEnd - 1] === "/";
+            if (!isSelfClose) {
+              level++;
+            }
+            searchIndex = innerEnd === -1 ? nextOpen + tagName.length + 1 : innerEnd + 1;
             continue;
           }
         }
@@ -1611,10 +1980,9 @@ __decorateClass([
   __decorateParam(0, A_Inject(A_Scope))
 ], AreHTMLEngine.prototype, "init", 1);
 AreHTMLEngine = __decorateClass([
-  A_Frame.Component({
-    namespace: "A-ARE",
-    name: "AreHTMLEngine",
-    description: "HTML Rendering Engine for A-Concept Rendering Engine (ARE), responsible for processing and rendering HTML templates within the ARE framework."
+  A_Frame.Define({
+    namespace: "a-are-html",
+    description: "Concrete HTML rendering engine that assembles the full ARE pipeline for web environments. Bootstraps and wires AreHTMLTokenizer, AreHTMLTransformer, AreHTMLCompiler, AreHTMLInterpreter, and AreHTMLLifecycle; mounts root nodes from inline or fetched templates; and drives reactive re-renders via the AreSignals bus."
   })
 ], AreHTMLEngine);
 var AreRoot = class extends Are {
@@ -1707,13 +2075,12 @@ __decorateClass([
   __decorateParam(4, A_Inject(AreSignalsContext))
 ], AreRoot.prototype, "onSignal", 1);
 AreRoot = __decorateClass([
-  A_Frame.Component({
-    namespace: "A-ARE",
-    name: "AreRoot",
+  A_Frame.Define({
+    namespace: "a-are-html",
     description: "The AreRoot component serves as the foundational entry point for the A-Concept Rendering Engine (ARE). It is responsible for initializing the rendering process, managing the root node of the component tree, and handling signal-based rendering logic. The AreRoot component processes incoming signals to determine which child components to render, allowing for dynamic and responsive UI updates based on application state and user interactions."
   })
 ], AreRoot);
-var AreWatcher = class extends A_Component {
+var AreRouteWatcher = class extends A_Component {
   constructor() {
     super();
     this.handlers = /* @__PURE__ */ new Set();
@@ -1769,14 +2136,13 @@ var AreWatcher = class extends A_Component {
     }
   }
 };
-AreWatcher = __decorateClass([
-  A_Frame.Component({
-    namespace: "A-ARE",
-    name: "AreWatcher",
-    description: "AreWatcher is a component that observes browser navigation events (history pushState, replaceState, and popstate) and notifies registered handlers when the URL changes, enabling client-side routing and reactive route-based rendering within the ARE framework."
+AreRouteWatcher = __decorateClass([
+  A_Frame.Define({
+    namespace: "a-are-html",
+    description: "AreRouteWatcher is a component that observes browser navigation events (history pushState, replaceState, and popstate) and notifies registered handlers when the URL changes, enabling client-side routing and reactive route-based rendering within the ARE framework."
   })
-], AreWatcher);
+], AreRouteWatcher);
 
-export { AddAttributeInstruction, AddElementInstruction, AddInterpolationInstruction, AddListenerInstruction, AddStyleInstruction, AddTextInstruction, AreBindingAttribute, AreComment, AreComponentNode, AreDirective, AreDirectiveAttribute, AreDirectiveContext, AreDirectiveFeatures, AreDirectiveFor, AreDirectiveIf, AreDirectiveMeta, AreEventAttribute, AreHTMLAttribute, AreHTMLCompiler, AreHTMLEngine, AreHTMLEngineContext, AreHTMLInstructions, AreHTMLInterpreter, AreHTMLLifecycle, AreHTMLNode, AreHTMLTokenizer, AreHTMLTransformer, AreInterpolation, AreRoot, AreRootNode, AreRoute, AreStaticAttribute, AreStyle, AreText, AreWatcher };
+export { AddAttributeInstruction, AddElementInstruction, AddInterpolationInstruction, AddListenerInstruction, AddStyleInstruction, AddTextInstruction, AreBindingAttribute, AreComment, AreComponentNode, AreDirective, AreDirectiveAttribute, AreDirectiveContext, AreDirectiveFeatures, AreDirectiveFor, AreDirectiveIf, AreDirectiveMeta, AreEventAttribute, AreHTMLAttribute, AreHTMLCompiler, AreHTMLEngine, AreHTMLEngineContext, AreHTMLInstructions, AreHTMLInterpreter, AreHTMLLifecycle, AreHTMLNode, AreHTMLTokenizer, AreHTMLTransformer, AreInterpolation, AreRoot, AreRootNode, AreRoute, AreRouteWatcher, AreStaticAttribute, AreStyle, AreText, BOOLEAN_ATTRIBUTES, IDL_FORM_PROPERTIES, LISTENER_OPTION_MODIFIERS, isBooleanAttribute, isIDLFormProperty, normalizeClassValue, normalizeStyleValue, parseEventName, toDOMString };
 //# sourceMappingURL=index.mjs.map
 //# sourceMappingURL=index.mjs.map