@adaas/are-html 0.0.2 → 0.0.4

package/src/engine/AreHTML.constants.ts

@@ -1,2 +1,146 @@
+/**
+ * Boolean HTML attributes whose presence (regardless of value) implies "true",
+ * and whose absence implies "false". Setting these via `setAttribute(name, value)`
+ * always renders the attribute, which is wrong for reactive bindings.
+ *
+ * Reference: https://html.spec.whatwg.org/multipage/indices.html#attributes-3
+ */
+export const BOOLEAN_ATTRIBUTES = new Set<string>([
+    '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',
+]);
+
+export function isBooleanAttribute(name: string): boolean {
+    return BOOLEAN_ATTRIBUTES.has(name.toLowerCase());
+}
+
+/**
+ * Form-control IDL properties that must be set as a JS property
+ * (not just an attribute) so live user input is reflected.
+ *
+ * `<input value="foo">` only sets the *default* value;
+ * `input.value = "foo"` updates the live state.
+ */
+export const IDL_FORM_PROPERTIES: Record<string, Set<string>> = {
+    INPUT: new Set(['value', 'checked', 'indeterminate']),
+    TEXTAREA: new Set(['value']),
+    SELECT: new Set(['value']),
+    OPTION: new Set(['selected']),
+};
+
+export function isIDLFormProperty(tagName: string, attrName: string): boolean {
+    const set = IDL_FORM_PROPERTIES[tagName.toUpperCase()];
+    return !!set && set.has(attrName);
+}
+
+/**
+ * Normalize a `:class` binding value into a single space-separated string.
+ * Supports the common shapes:
+ *   - string                                       → "a b"
+ *   - array<string | object | falsy>               → ["a", { b: true, c: cond }, null]
+ *   - object<string, boolean>                      → { a: true, b: false }
+ */
+export function normalizeClassValue(value: any): string {
+    if (value === null || value === undefined || 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: string[] = [];
+        for (const key of Object.keys(value)) {
+            if (value[key]) parts.push(key);
+        }
+        return parts.join(' ');
+    }
+    return '';
+}
+
+/**
+ * Normalize a `:style` binding value into an inline-style string.
+ * Supports:
+ *   - string                                       → "color: red; font-size: 12px"
+ *   - object<string, string|number>                → { color: 'red', fontSize: '12px' }
+ *   - array<string | object>                       → ['color: red', { fontSize: '12px' }]
+ */
+export function normalizeStyleValue(value: any): string {
+    if (value === null || value === undefined || 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: string[] = [];
+        for (const key of Object.keys(value)) {
+            const v = value[key];
+            if (v === null || v === undefined || v === false) continue;
+            const kebab = key.replace(/[A-Z]/g, m => '-' + m.toLowerCase());
+            parts.push(`${kebab}: ${v}`);
+        }
+        return parts.join('; ');
+    }
+    return '';
+}
+
+/**
+ * Parse a DOM event name with modifiers, e.g. "click.stop.prevent" or "keydown.enter".
+ * Returns the bare event name plus the modifier set.
+ */
+export interface ParsedEventName {
+    event: string;
+    modifiers: Set<string>;
+}
+
+export function parseEventName(raw: string): ParsedEventName {
+    const [event, ...modifiers] = raw.split('.');
+    return { event, modifiers: new Set(modifiers) };
+}
+
+/**
+ * Known event-listener modifiers that map directly to addEventListener options.
+ */
+export const LISTENER_OPTION_MODIFIERS = new Set(['capture', 'once', 'passive']);
+
+/**
+ * Coerce a value into a string for DOM consumption.
+ * Avoids "undefined"/"null"/"[object Object]" leaks into the DOM.
+ */
+export function toDOMString(value: any): string {
+    if (value === null || value === undefined) return '';
+    if (typeof value === 'string') return value;
+    if (typeof value === 'number' || typeof value === 'boolean') return String(value);
+    try {
+        return JSON.stringify(value);
+    } catch {
+        return '';
+    }
+}
 
 

package/src/engine/AreHTML.context.ts

@@ -1,7 +1,12 @@
 import { AreContext, AreInstruction, AreNode } from "@adaas/are";
 import { AreHTMLContextConstructor } from "./AreHTML.types";
+import { A_Frame } from "@adaas/a-frame/core";
 
 
+@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.'
+})
 export class AreHTMLEngineContext extends AreContext {
 
     /**
@@ -41,7 +46,7 @@ export class AreHTMLEngineContext extends AreContext {
         /**
          * Event listeners attached to elements, used for proper cleanup when reverting instructions. Maps a DOM element to a map of event names and their corresponding listeners, allowing the engine to track which listeners are attached to which elements and remove them when necessary (e.g., when an instruction is reverted).
          */
-        elementListeners: new WeakMap<Node, Map<string, EventListenerOrEventListenerObject>>()
+        elementListeners: new WeakMap<Node, Map<string, Set<EventListenerOrEventListenerObject>>>()
     }
 
     /**
@@ -172,7 +177,11 @@ export class AreHTMLEngineContext extends AreContext {
         if (!this.index.elementListeners.has(element)) {
             this.index.elementListeners.set(element, new Map());
         }
-        this.index.elementListeners.get(element)!.set(eventName, listener);
+        const byEvent = this.index.elementListeners.get(element)!;
+        if (!byEvent.has(eventName)) {
+            byEvent.set(eventName, 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.
@@ -182,6 +191,16 @@ export class AreHTMLEngineContext extends AreContext {
      * @returns 
      */
     getListener(element: Node, eventName: string): EventListenerOrEventListenerObject | undefined {
+        const set = this.index.elementListeners.get(element)?.get(eventName);
+        if (!set || set.size === 0) return undefined;
+        // Return the first listener for backwards compatibility.
+        return set.values().next().value;
+    }
+
+    /**
+     * Returns all listeners registered for a given element + event name.
+     */
+    getListeners(element: Node, eventName: string): Set<EventListenerOrEventListenerObject> | undefined {
         return this.index.elementListeners.get(element)?.get(eventName);
     }
     /**
@@ -190,7 +209,17 @@ export class AreHTMLEngineContext extends AreContext {
      * @param element 
      * @param eventName 
      */
-    removeListener(element: Node, eventName: string): void {
-        this.index.elementListeners.get(element)?.delete(eventName);
+    removeListener(element: Node, eventName: string, listener?: EventListenerOrEventListenerObject): void {
+        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);
+        }
     }
 }

package/src/engine/AreHTML.engine.ts

@@ -1,5 +1,5 @@
 import { A_Feature, A_Inject, A_Scope } from "@adaas/a-concept";
-import { A_Frame } from "@adaas/a-frame";
+import { A_Frame } from "@adaas/a-frame/core"
 import { A_ServiceFeatures } from "@adaas/a-utils/a-service";
 import { AreEngine, AreSyntaxTokenMatch, AreSyntax } from "@adaas/are";
 import { AreHTMLInterpreter } from "@adaas/are-html/interpreter";
@@ -16,10 +16,9 @@ import { AreHTMLCompiler } from "./AreHTML.compiler";
 
 
 
-@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.'
 })
 export class AreHTMLEngine extends AreEngine {
 
@@ -167,8 +166,14 @@ export class AreHTMLEngine extends AreEngine {
                 if (nextOpen !== -1 && nextOpen < nextClose) {
                     const charAfter = source[nextOpen + tagName.length + 1]
                     if (charAfter === ' ' || charAfter === '>' || charAfter === '/') {
-                        level++
-                        searchIndex = nextOpen + tagName.length + 1
+                        // Skip self-closing nested occurrences, e.g. <div/> inside <div>...</div>.
+                        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
                     }
                 }

package/src/engine/AreHTML.interpreter.ts

@@ -1,5 +1,5 @@
 import { A_Caller, A_Inject } from "@adaas/a-concept";
-import { A_Frame } from "@adaas/a-frame";
+import { A_Frame } from "@adaas/a-frame/core"
 import { A_Logger } from "@adaas/a-utils/a-logger";
 import {
     AreSyntax, AreStore,
@@ -17,18 +17,25 @@ import { AddTextInstruction } from "@adaas/are-html/instructions/AddText.instruc
 import { AreDirectiveContext } from "@adaas/are-html/directive/AreDirective.context";
 import { AreHTMLNode } from "../lib/AreHTMLNode/AreHTMLNode";
 import { AreHTMLEngineContext } from "./AreHTML.context";
-
-
-@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.'
+import {
+    isBooleanAttribute,
+    isIDLFormProperty,
+    normalizeClassValue,
+    normalizeStyleValue,
+    parseEventName,
+    toDOMString,
+} from "./AreHTML.constants";
+
+
+@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 — 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.'
 })
 export class AreHTMLInterpreter extends AreInterpreter {
     // ─────────────────────────────────────────────────────────────────────────────
     // ── CreateElement — Apply / Revert ───────────────────────────────────────────
     // ─────────────────────────────────────────────────────────────────────────────
-    @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)
@@ -68,6 +75,7 @@ export class AreHTMLInterpreter extends AreInterpreter {
                 }
 
                 const element = context.container.createElement(tag);
+                element.setAttribute('data-aseid', node.aseid.toString());
 
                 if (mountPoint.nodeType === Node.ELEMENT_NODE) {
                     // parent is a real element — just append
@@ -109,7 +117,7 @@ export class AreHTMLInterpreter extends AreInterpreter {
     }
 
 
-    @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)
@@ -131,7 +139,7 @@ export class AreHTMLInterpreter extends AreInterpreter {
     // ─────────────────────────────────────────────────────────────────────────────
     // ── AddAttribute — Apply / Revert ────────────────────────────────────────────
     // ─────────────────────────────────────────────────────────────────────────────
-    @A_Frame.Method({
+    @A_Frame.Define({
         description: 'Add an attribute to an HTML element based on the provided mutation instruction.'
     })
     @AreInterpreter.Apply(AreHTMLInstructions.AddAttribute)
@@ -156,43 +164,93 @@ export class AreHTMLInterpreter 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;
 
+        const el = element as HTMLElement;
+        const lowerName = name.toLowerCase();
 
-        /**
-         * First time
-         */
-        if (mutation.cache === undefined) {
-
-            const existingValue = (element as HTMLElement).getAttribute(name);
-
-            const result = (existingValue ? `${existingValue} ${value}` : value);
-
-            (element as HTMLElement).setAttribute(name, result);
-
-            mutation.cache = value;
+        // ── 1. Boolean attributes ────────────────────────────────────────────
+        if (isBooleanAttribute(lowerName)) {
+            if (rawValue) {
+                el.setAttribute(lowerName, '');
+                // also reflect IDL property where supported (disabled, hidden, …)
+                try { (el as any)[lowerName] = true; } catch { /* ignore */ }
+            } else {
+                el.removeAttribute(lowerName);
+                try { (el as any)[lowerName] = false; } catch { /* ignore */ }
+            }
+            mutation.cache = rawValue ? 'true' : '';
+            return;
+        }
 
-        } else {
+        // ── 2. Form-control IDL properties (value/checked/selected) ─────────
+        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 as any)[propName] = !!rawValue;
+                } else {
+                    (el as any)[propName] = toDOMString(rawValue);
+                }
+            } catch { /* ignore */ }
+            // also keep the attribute in sync for SSR/CSS selectors
+            if (propName !== 'value') {
+                if (rawValue) el.setAttribute(name, ''); else el.removeAttribute(name);
+            } else {
+                el.setAttribute(name, toDOMString(rawValue));
+            }
+            mutation.cache = toDOMString(rawValue);
+            return;
+        }
 
-            const existingValue = (element as HTMLElement).getAttribute(name);
+        // ── 3. Class binding — supports object/array/string and merges ──────
+        if (lowerName === 'class') {
+            const newValue = normalizeClassValue(rawValue);
 
-            const existingParts = existingValue ? existingValue.split(/\s+/).filter(Boolean) : [];
-            const oldParts = new Set((mutation.cache as string).split(/\s+/).filter(Boolean));
-            const newParts = value ? value.split(/\s+/).filter(Boolean) : [];
+            if (mutation.cache === undefined) {
+                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 as string).split(/\s+/).filter(Boolean));
+                const newParts = newValue ? newValue.split(/\s+/).filter(Boolean) : [];
 
-            const result = [...existingParts.filter(part => !oldParts.has(part)), ...newParts].join(' ');
+                const merged = [...existingParts.filter(p => !oldParts.has(p)), ...newParts].join(' ');
+                if (merged) el.setAttribute('class', merged); else el.removeAttribute('class');
+            }
+            mutation.cache = newValue;
+            return;
+        }
 
-            (element as HTMLElement).setAttribute(name, result);
+        // ── 4. Style binding — supports object/array/string ─────────────────
+        if (lowerName === 'style') {
+            const newValue = normalizeStyleValue(rawValue);
+            if (newValue) el.setAttribute('style', newValue); else el.removeAttribute('style');
+            mutation.cache = newValue;
+            return;
+        }
 
-            mutation.cache = value;
+        // ── 5. Default: replace attribute (no whitespace merge) ─────────────
+        const stringValue = toDOMString(rawValue);
+        if (stringValue === '' && evaluate && (rawValue === false || rawValue === null || rawValue === undefined)) {
+            el.removeAttribute(name);
+        } else {
+            el.setAttribute(name, stringValue);
         }
+        mutation.cache = stringValue;
 
 
     }
 
-    @A_Frame.Method({
+    @A_Frame.Define({
         description: 'Remove an attribute from an HTML element based on the provided mutation instruction.'
     })
     @AreInterpreter.Revert(AreHTMLInstructions.AddAttribute)
@@ -221,7 +279,7 @@ export class AreHTMLInterpreter extends AreInterpreter {
     // ── addEventListener — Apply / Revert ────────────────────────────────────────
     // ─────────────────────────────────────────────────────────────────────────────
 
-    @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)
@@ -244,54 +302,117 @@ export class AreHTMLInterpreter extends AreInterpreter {
         }
 
         /**
-         * e.g. @click="handleClick" 
-         * 
+         * e.g. @click="handleClick"
          * e.g. @click="handleClick($event, element)"
-         * 
-         * e.g. @click="(e)=> user.name ?  handleClick(e) : null" (with conditional logic)
-         * 
-         * e.g. @click="(e)=> isValid(user.name) ?  handleClick(e) : null" (with conditional logic)
-         * 
-         * e.g. @click="(e)=> isValid(user.name) ?  handleClick(e, format(user.name)) : null" (with conditional logic)
+         * e.g. @click.stop.prevent="handleClick"
+         * e.g. @keydown.enter="submit"
+         * e.g. @click="(e)=> user.name ? handleClick(e) : null"
          */
 
+        const { event: eventName, modifiers } = parseEventName(mutation.payload.name);
+
+        const listenerOptions: AddEventListenerOptions = {};
+        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);
-        const handlerScope = {}
+
+        // Holds the live DOM event so handler invocations (with or without
+        // template arguments) always have access to it.
+        let liveEvent: Event | null = null;
+
+        const handlerScope: Record<string, any> = {};
 
         for (const handler of handlers) {
             const handlerFn = (...args: any[]) => {
-                const event = new AreEvent(handler)
-
-                event.set('args', args);
+                const event = new AreEvent(handler);
+                // If user passed only template args (e.g. $h('x')), append the DOM
+                // event as the last arg. If they passed nothing, args[0] is the DOM event.
+                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);
-            }
-
+            };
             handlerScope[`$${handler}`] = handlerFn;
         }
 
         const callback = (e: Event) => {
-            context.startPerformance('Click')
+            try {
+                liveEvent = e;
+
+                if (modifiers.has('self') && e.target !== element) return;
+                if (modifiers.has('stop')) e.stopPropagation();
+                if (modifiers.has('prevent')) e.preventDefault();
+
+                // key-name modifiers for keyboard events: @keydown.enter / .esc / .tab / .space / .up / .down / .left / .right / .delete
+                if (e instanceof KeyboardEvent && modifiers.size > 0) {
+                    const key = (e.key || '').toLowerCase();
+                    const KEY_ALIASES: Record<string, string[]> = {
+                        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;
+                    }
+                }
 
-            const result = syntax.evaluate(mutation.payload.handler, store, {
-                ...handlerScope,
-                ...(directiveContext?.scope || {})
-            });
-            if (typeof result === 'function') result(e);
-        };
+                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);
         }
+        // Track on both the context (for diagnostics) and the mutation itself
+        // so the revert path can detach the exact same callback.
+        (mutation.payload as any)._callback = callback;
+        context.addListener(element, mutation.payload.name, callback);
     }
 
 
-    @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)
@@ -304,12 +425,14 @@ export class AreHTMLInterpreter extends AreInterpreter {
         if (!element) return;
 
         const { name } = mutation.payload;
+        const { event: eventName } = parseEventName(name);
 
-        const listener = context.getListener(element, name);
+        const listener = (mutation.payload as any)._callback as EventListenerOrEventListenerObject | undefined;
 
         if (listener) {
-            element.removeEventListener(name, listener);
-            context.removeListener(element, name);
+            element.removeEventListener(eventName, listener);
+            context.removeListener(element, name, listener);
+            (mutation.payload as any)._callback = undefined;
         }
     }
 
@@ -318,7 +441,7 @@ export class AreHTMLInterpreter extends AreInterpreter {
     // ── AddText — Apply / Revert ─────────────────────────────────────────────────
     // ─────────────────────────────────────────────────────────────────────────────
 
-    @A_Frame.Method({
+    @A_Frame.Define({
         description: 'Add text content to an HTML element based on the provided declaration instruction.'
     })
     @AreInterpreter.Apply(AreHTMLInstructions.AddText)
@@ -335,10 +458,12 @@ export class AreHTMLInterpreter extends AreInterpreter {
         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);
@@ -375,7 +500,7 @@ export class AreHTMLInterpreter extends AreInterpreter {
     }
 
 
-    @A_Frame.Method({
+    @A_Frame.Define({
         description: 'Remove text content from an HTML element based on the provided declaration instruction.'
     })
     @AreInterpreter.Revert(AreHTMLInstructions.AddText)
@@ -393,7 +518,7 @@ export class AreHTMLInterpreter extends AreInterpreter {
 
 
 
-    @A_Frame.Method({
+    @A_Frame.Define({
         description: 'Add a comment node to the DOM based on the provided declaration instruction.'
     })
     @AreInterpreter.Apply(AreHTMLInstructions.AddComment)
@@ -410,10 +535,12 @@ export class AreHTMLInterpreter extends AreInterpreter {
         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);
@@ -448,7 +575,7 @@ export class AreHTMLInterpreter extends AreInterpreter {
     }
 
 
-    @A_Frame.Method({
+    @A_Frame.Define({
         description: 'Remove a comment node from the DOM based on the provided declaration instruction.'
     })
     @AreInterpreter.Revert(AreHTMLInstructions.AddComment)