@elenajs/core 1.0.0-rc.3 → 1.0.0-rc.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@elenajs/core",
-  "version": "1.0.0-rc.3",
+  "version": "1.0.0-rc.4",
   "description": "Elena is a simple, tiny library for building Progressive Web Components.",
   "author": "Elena <hi@elenajs.com>",
   "homepage": "https://elenajs.com/",
@@ -16,6 +16,7 @@
   "publishConfig": {
     "access": "public"
   },
+  "source": "./src/elena.js",
   "main": "./dist/elena.js",
   "types": "./dist/elena.d.ts",
   "type": "module",
@@ -27,7 +28,8 @@
     "./bundle": "./dist/bundle.js"
   },
   "files": [
-    "dist"
+    "dist",
+    "src"
   ],
   "scripts": {
     "prebuild": "npm run -s clean",
@@ -54,5 +56,5 @@
     "typescript": "5.9.3",
     "vitest": "4.1.0"
   },
-  "gitHead": "18e13f305c8823f7633c739f2ec61cec2420267b"
+  "gitHead": "33e1f2c6a4f2a6693a557edf495ec48579269def"
 }

package/src/common/props.js

@@ -0,0 +1,132 @@
+/**
+ * Get the value of the Elena Element property.
+ *
+ * @param {string} type
+ * @param {any} value
+ * @param {"toAttribute" | "toProp"} [transform]
+ */
+export function getPropValue(type, value, transform) {
+  value = type === "boolean" && typeof value !== "boolean" ? value !== null : value;
+
+  if (!transform) {
+    return value;
+  } else if (transform === "toAttribute") {
+    switch (type) {
+      case "object":
+      case "array":
+        return value === null ? null : JSON.stringify(value);
+      case "boolean":
+        return value ? "" : null;
+      case "number":
+        return value === null ? null : value;
+      default:
+        return value === "" ? null : value;
+    }
+  } else {
+    switch (type) {
+      case "object":
+      case "array":
+        if (!value) {
+          return value;
+        }
+        try {
+          return JSON.parse(value);
+        } catch {
+          console.warn("░█ [ELENA]: Invalid JSON: " + value);
+          return null;
+        }
+      case "boolean":
+        return value; // conversion already handled above
+      case "number":
+        return value !== null ? +value : value;
+      default:
+        return value ?? "";
+    }
+  }
+}
+
+/**
+ * Set or remove an attribute on an Elena Element.
+ *
+ * @param {Element} element - Target element
+ * @param {string} name - Attribute name
+ * @param {string | null} value - Attribute value, or null to remove
+ */
+export function syncAttribute(element, name, value) {
+  if (!element) {
+    console.warn("░█ [ELENA]: Cannot sync attrs.");
+    return;
+  }
+  if (value === null) {
+    element.removeAttribute(name);
+  } else {
+    element.setAttribute(name, value);
+  }
+}
+
+/**
+ * Define prop getters/setters on the prototype once
+ * at class-creation time. Values are stored per-instance
+ * via a `_props` Map that is lazily created.
+ *
+ * @param {Function} proto - The class prototype
+ * @param {string[]} propNames - Prop names to define
+ * @param {Set<string>} [noReflect] - Props that should not reflect to attributes
+ */
+export function setProps(proto, propNames, noReflect) {
+  for (const prop of propNames) {
+    const reflects = !noReflect || !noReflect.has(prop);
+    Object.defineProperty(proto, prop, {
+      configurable: true,
+      enumerable: true,
+      get() {
+        return this._props ? this._props.get(prop) : undefined;
+      },
+      set(value) {
+        if (!this._props) {
+          this._props = new Map();
+        }
+        if (value === this._props.get(prop)) {
+          return;
+        }
+
+        this._props.set(prop, value);
+        if (!this.isConnected) {
+          return;
+        }
+
+        if (reflects) {
+          // Skip reflection when called from attributeChangedCallback. The
+          // attribute is already at the new value, setting it again is redundant
+          // and would fire an extra attributeChangedCallback with identical values.
+          if (!this._syncing) {
+            const attrValue = getPropValue(typeof value, value, "toAttribute");
+            syncAttribute(this, prop, attrValue);
+          }
+        } else if (this._hydrated && !this._isRendering) {
+          this._safeRender();
+        }
+      },
+    });
+  }
+}
+
+/**
+ * We need to update the internals of the Elena Element
+ * when props on the host element are changed.
+ *
+ * @param {object} context
+ * @param {string} name
+ * @param {any} oldValue
+ * @param {any} newValue
+ */
+export function getProps(context, name, oldValue, newValue) {
+  if (oldValue !== newValue) {
+    const type = typeof context[name];
+    if (type === "undefined") {
+      console.warn(`░█ [ELENA]: Prop "${name}" has no default.`);
+    }
+    const newAttr = getPropValue(type, newValue, "toProp");
+    context[name] = newAttr;
+  }
+}

package/src/common/render.js

@@ -0,0 +1,230 @@
+import { collapseWhitespace, isRaw, resolveValue, toPlainText } from "./utils.js";
+
+const stringsCache = new WeakMap();
+const markerKey = "e" + Math.random().toString(36).slice(2, 6);
+
+/**
+ * Render a tagged template into an Elena Element with DOM diffing.
+ * Returns true if the DOM was fully rebuilt, false if only text
+ * nodes were patched in place.
+ *
+ * @param {HTMLElement} element
+ * @param {TemplateStringsArray} strings - Static parts of the tagged template
+ * @param {Array} values - Dynamic interpolated values
+ * @returns {boolean}
+ */
+export function renderTemplate(element, strings, values) {
+  if (patchTextNodes(element, strings, values)) {
+    return false;
+  }
+  fullRender(element, strings, values);
+  return true;
+}
+
+/**
+ * Fast path: patch only the text nodes whose values changed.
+ *
+ * @param {HTMLElement} element - The host element with cached template state
+ * @param {TemplateStringsArray} strings - Static parts of the tagged template
+ * @param {Array} values - Dynamic interpolated values
+ * @returns {boolean} Whether patching was sufficient (false = full render)
+ */
+function patchTextNodes(element, strings, values) {
+  // Only works when re-rendering the same template shape
+  if (element._tplStrings !== strings || !element._tplParts) {
+    return false;
+  }
+
+  for (let i = 0; i < values.length; i++) {
+    const v = values[i];
+    const comparable = Array.isArray(v) ? toPlainText(v) : v;
+
+    if (comparable === element._tplValues[i]) {
+      continue;
+    }
+
+    if (isRaw(v) || !element._tplParts[i]) {
+      return false;
+    }
+
+    element._tplValues[i] = comparable;
+    element._tplParts[i].textContent = toPlainText(v);
+  }
+
+  return true;
+}
+
+/**
+ * Cold path: clone a cached <template> and patch in values.
+ *
+ * @param {HTMLElement} element - The host element to render into
+ * @param {TemplateStringsArray} strings - Static parts of the tagged template
+ * @param {Array} values - Dynamic interpolated values
+ */
+function fullRender(element, strings, values) {
+  let entry = stringsCache.get(strings);
+
+  if (!entry) {
+    const processedStrings = Array.from(strings, collapseWhitespace);
+    entry = {
+      processedStrings,
+      template: values.length > 0 ? createTemplate(processedStrings, values.length) : null,
+    };
+    stringsCache.set(strings, entry);
+  }
+
+  if (entry.template) {
+    element._tplParts = cloneAndPatch(element, entry.template, values);
+  } else {
+    // Fallback for attribute-position values or static templates.
+    // White space collapsing here protects against Vue SSR mismatches.
+    const renderedValues = values.map(value => resolveValue(value));
+    const markup = entry.processedStrings
+      .reduce((out, str, i) => out + str + (renderedValues[i] ?? ""), "")
+      .replace(/>\s+</g, "><")
+      .trim();
+
+    // Morph existing DOM to match new markup instead of replacing it.
+    const tpl = document.createElement("template");
+    tpl.innerHTML = markup;
+    morphContent(element, tpl.content.childNodes);
+    element._tplParts = null;
+  }
+
+  element._tplStrings = strings;
+  element._tplValues = values.map(v => (Array.isArray(v) ? toPlainText(v) : v));
+}
+
+/**
+ * Build a <template> element with comment markers.
+ *
+ * @param {string[]} processedStrings - Whitespace-collapsed static parts
+ * @param {number} valueCount - Number of dynamic values
+ * @returns {HTMLTemplateElement | null}
+ */
+function createTemplate(processedStrings, valueCount) {
+  const marker = `<!--${markerKey}-->`;
+  const markup = processedStrings
+    .reduce((out, str, i) => out + str + (i < valueCount ? marker : ""), "")
+    .trim();
+
+  const tpl = document.createElement("template");
+  tpl.innerHTML = markup;
+
+  // Mismatch means this template shape cannot use the clone path.
+  const walker = document.createTreeWalker(tpl.content, NodeFilter.SHOW_COMMENT);
+  let count = 0;
+
+  while (walker.nextNode()) {
+    if (walker.currentNode.data === markerKey) {
+      count++;
+    }
+  }
+
+  return count === valueCount ? tpl : null;
+}
+
+/**
+ * Clone a cached template and replace comment markers
+ * with actual content.
+ *
+ * @param {HTMLElement} element - The host element to render into
+ * @param {HTMLTemplateElement} template - Cached template with markers
+ * @param {Array} values - Raw interpolated values
+ * @returns {Array<Text | undefined>} Text node map for fast-path patching
+ */
+function cloneAndPatch(element, template, values) {
+  const clone = template.content.cloneNode(true);
+  const walker = document.createTreeWalker(clone, NodeFilter.SHOW_COMMENT);
+  const parts = new Array(values.length);
+  const markers = [];
+  let node;
+
+  // Collect markers before modifying the tree
+  while ((node = walker.nextNode())) {
+    if (node.data === markerKey) {
+      markers.push(node);
+    }
+  }
+
+  for (let i = 0; i < markers.length; i++) {
+    const value = values[i];
+
+    if (isRaw(value)) {
+      // Raw HTML: parse and insert as fragment
+      const tmp = document.createElement("template");
+      tmp.innerHTML = resolveValue(value);
+      markers[i].parentNode.replaceChild(tmp.content, markers[i]);
+
+      // Raw values can't be fast-patched; leave parts undefined
+    } else {
+      // Create text node with unescaped content
+      const textNode = document.createTextNode(toPlainText(value));
+      markers[i].parentNode.replaceChild(textNode, markers[i]);
+      parts[i] = textNode;
+    }
+  }
+
+  element.replaceChildren(clone);
+  return parts;
+}
+
+/**
+ * Patches attributes and text content in-place when structure is stable,
+ * preserving element identity and focus state across re-renders.
+ *
+ * @param {Node} parent
+ * @param {NodeList} nextNodes - The desired child nodes from the new render
+ */
+function morphContent(parent, nextNodes) {
+  const current = Array.from(parent.childNodes);
+  const next = Array.from(nextNodes);
+  const len = Math.max(current.length, next.length);
+
+  for (let i = 0; i < len; i++) {
+    const cur = current[i];
+    const nxt = next[i];
+
+    if (!cur) {
+      parent.appendChild(nxt);
+    } else if (!nxt) {
+      parent.removeChild(cur);
+    } else if (
+      cur.nodeType !== nxt.nodeType ||
+      (cur.nodeType === Node.ELEMENT_NODE && cur.tagName !== nxt.tagName)
+    ) {
+      parent.replaceChild(nxt, cur);
+    } else if (cur.nodeType === Node.TEXT_NODE) {
+      if (cur.textContent !== nxt.textContent) {
+        cur.textContent = nxt.textContent;
+      }
+    } else if (cur.nodeType === Node.ELEMENT_NODE) {
+      morphAttributes(cur, nxt);
+      morphContent(cur, nxt.childNodes);
+    }
+  }
+}
+
+/**
+ * Morhp element’s attributes without rebuilding the DOM.
+ *
+ * @param {Element} current - The current existing DOM element
+ * @param {Element} next - The desired element from the new render
+ */
+function morphAttributes(current, next) {
+  for (let i = current.attributes.length - 1; i >= 0; i--) {
+    const { name } = current.attributes[i];
+
+    if (!next.hasAttribute(name)) {
+      current.removeAttribute(name);
+    }
+  }
+
+  for (let i = 0; i < next.attributes.length; i++) {
+    const { name, value } = next.attributes[i];
+
+    if (current.getAttribute(name) !== value) {
+      current.setAttribute(name, value);
+    }
+  }
+}

package/src/common/utils.js

@@ -0,0 +1,124 @@
+/**
+ * Register the Elena Element if the browser supports it.
+ *
+ * @param {string} tagName
+ * @param {Function} Element
+ */
+export function defineElement(tagName, Element) {
+  if (typeof window !== "undefined" && "customElements" in window) {
+    if (!window.customElements.get(tagName)) {
+      window.customElements.define(tagName, Element);
+    }
+  }
+}
+
+/**
+ * Escape a string for safe insertion into HTML.
+ *
+ * @param {string} str
+ * @returns {string}
+ */
+const Escape = { "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" };
+export function escapeHtml(str) {
+  return String(str).replace(/[&<>"']/g, c => Escape[c]);
+}
+
+/**
+ * Resolve an interpolated template value to its
+ * HTML string representation.
+ *
+ * @param {*} value
+ * @returns {string}
+ */
+export function resolveValue(value) {
+  if (Array.isArray(value)) {
+    return value.map(item => resolveItem(item)).join("");
+  }
+  return resolveItem(value);
+}
+
+/**
+ * Resolve a single value to its HTML string
+ * representation.
+ *
+ * @param {*} value
+ * @returns {string}
+ */
+function resolveItem(value) {
+  return value?.__raw ? String(value) : escapeHtml(String(value ?? ""));
+}
+
+/**
+ * Tagged template for trusted HTML. Use as the return value
+ * of render(), or for sub-fragments inside render methods.
+ *
+ * @param {TemplateStringsArray} strings
+ * @param {...*} values
+ * @returns {{ __raw: true, strings: TemplateStringsArray, values: Array, toString(): string }}
+ */
+export function html(strings, ...values) {
+  let str;
+  return {
+    __raw: true,
+    strings,
+    values,
+    toString: () => {
+      if (str === undefined) {
+        str = strings.reduce((acc, s, i) => {
+          return acc + s + resolveValue(values[i]);
+        }, "");
+      }
+      return str;
+    },
+  };
+}
+
+/**
+ * Renders a string as HTML rather than text.
+ *
+ * @param {string} str - The raw HTML string to trust.
+ * @returns {{ __raw: true, toString(): string }}
+ */
+export function unsafeHTML(str) {
+  return { __raw: true, toString: () => str ?? "" };
+}
+
+/**
+ * A placeholder you can return from a conditional expression
+ * inside a template to render nothing.
+ *
+ * @type {{ __raw: true, toString(): string }}
+ */
+export const nothing = Object.freeze({ __raw: true, toString: () => "" });
+
+/**
+ * Check if a value contains trusted HTML fragments.
+ *
+ * @param {*} value
+ * @returns {boolean}
+ */
+export const isRaw = value =>
+  Array.isArray(value) ? value.some(item => item?.__raw) : value?.__raw;
+
+/**
+ * Convert a value to its plain text string.
+ *
+ * @param {*} value
+ * @returns {string}
+ */
+export const toPlainText = value =>
+  Array.isArray(value) ? value.map(item => String(item ?? "")).join("") : String(value ?? "");
+
+/**
+ * Collapse whitespace from a static string part.
+ *
+ * @param {string} string
+ * @returns {string}
+ */
+export function collapseWhitespace(string) {
+  return string
+    .replace(/>\n\s*/g, ">") // newline after tag close
+    .replace(/\n\s*</g, "<") // newline before tag open
+    .replace(/\n\s*/g, " ") // newline in text content, preserve word boundary
+    .replace(/>\s+</g, "><"); // whitespace between tags
+}

package/src/elena.js

@@ -0,0 +1,562 @@
+/**
+ *  ██████████ ████
+ * ░░███░░░░░█░░███
+ *  ░███  █ ░  ░███   ██████  ████████    ██████
+ *  ░██████    ░███  ███░░███░░███░░███  ░░░░░███
+ *  ░███░░█    ░███ ░███████  ░███ ░███   ███████
+ *  ░███ ░   █ ░███ ░███░░░   ░███ ░███  ███░░███
+ *  ██████████ █████░░██████  ████ █████░░████████
+ * ░░░░░░░░░░ ░░░░░  ░░░░░░  ░░░░ ░░░░░  ░░░░░░░░
+ *
+ * Elena Progressive Web Components
+ * https://elenajs.com
+ */
+
+import { setProps, getProps, getPropValue, syncAttribute } from "./common/props.js";
+import { defineElement, html, unsafeHTML, nothing } from "./common/utils.js";
+import { renderTemplate } from "./common/render.js";
+
+export { html, unsafeHTML, nothing };
+
+/**
+ * Returns a function that finds the inner element using the given selector.
+ * Built once per component class to avoid repeated work.
+ *
+ * - No selector: uses firstElementChild
+ * - Any string: uses querySelector
+ *
+ * @param {string | undefined} selector
+ * @returns {(host: HTMLElement) => HTMLElement | null}
+ */
+function elementResolver(selector) {
+  if (!selector) {
+    return host => host.firstElementChild;
+  }
+  return host => host.querySelector(selector);
+}
+
+/**
+ * @typedef {new (...args: any[]) => HTMLElement} ElenaConstructor
+ */
+
+/**
+ * @typedef {{ text: string, element: HTMLElement | null, render(): void, willUpdate(): void, firstUpdated(): void, updated(): void, connectedCallback(): void, disconnectedCallback(): void }} ElenaInstanceMembers
+ */
+
+/**
+ * @typedef {{ name: string, reflect?: boolean }} ElenaPropObject
+ */
+
+/**
+ * @typedef {(new (...args: any[]) => HTMLElement & ElenaInstanceMembers) & {
+ *   define(): void,
+ *   readonly observedAttributes: string[],
+ *   tagName?: string,
+ *   props?: (string | ElenaPropObject)[],
+ *   events?: string[],
+ *   element?: string,
+ *   shadow?: "open" | "closed",
+ *   styles?: CSSStyleSheet | string | (CSSStyleSheet | string)[],
+ * }} ElenaElementConstructor
+ */
+
+// Tracks which component classes have already been set up.
+const setupRegistry = new WeakSet();
+
+/**
+ * Creates an Elena component class by extending `superClass`.
+ *
+ * Adds rendering, props, and event handling to your component.
+ * Configure it using static class fields: `static tagName`,
+ * `static props`, `static events`, and `static element`.
+ *
+ * @param {ElenaConstructor} superClass - The base class to extend (usually `HTMLElement`).
+ * @returns {ElenaElementConstructor} A class ready to be defined as a custom element.
+ */
+export function Elena(superClass) {
+  /**
+   * The base Elena element class with all built-in behavior.
+   */
+  class ElenaElement extends superClass {
+    /**
+     * The inner element rendered by this component.
+     *
+     * @type {HTMLElement | null}
+     */
+    element = null;
+
+    /**
+     * Called by the browser when an observed attribute changes.
+     * Updates the matching prop and re-renders if needed.
+     *
+     * @param {string} prop
+     * @param {string} oldValue
+     * @param {string} newValue
+     */
+    attributeChangedCallback(prop, oldValue, newValue) {
+      super.attributeChangedCallback?.(prop, oldValue, newValue);
+
+      if (prop === "text") {
+        this.text = newValue ?? "";
+        return;
+      }
+
+      // Set flag so the property setter skips redundant attribute reflection:
+      // the attribute is already at the new value, no need to set it again.
+      this._syncing = true;
+      getProps(this, prop, oldValue, newValue);
+      this._syncing = false;
+
+      // Re-render when attributes change (after initial render).
+      // Guard against re-entrant renders: if render() itself mutates an observed
+      // attribute, skip the recursive call to prevent an infinite loop.
+      if (this._hydrated && oldValue !== newValue && !this._isRendering) {
+        this._safeRender();
+      }
+    }
+
+    /**
+     * Lists the attributes Elena watches for changes.
+     * Reads from the subclass’s `static props` field.
+     */
+    static get observedAttributes() {
+      if (this._observedAttrs) {
+        return this._observedAttrs;
+      }
+
+      const propNames = (this.props || []).map(p => (typeof p === "string" ? p : p.name));
+      this._observedAttrs = [...propNames, "text"];
+      return this._observedAttrs;
+    }
+
+    /**
+     * Called by the browser each time the element is added to the page.
+     */
+    connectedCallback() {
+      super.connectedCallback?.();
+      this._setupStaticProps();
+      this._captureClassFieldDefaults();
+      this._captureText();
+      this._attachShadow();
+      this.willUpdate();
+      this._applyRender();
+      this._syncProps();
+      this._delegateEvents();
+      if (!this._hydrated) {
+        this._hydrated = true;
+        this.setAttribute("hydrated", "");
+        this.firstUpdated();
+      }
+      this.updated();
+    }
+
+    /**
+     * Sets up props, events, and the element selector once per component class.
+     * Runs the first time an instance of a given class connects to the page.
+     *
+     * @internal
+     */
+    _setupStaticProps() {
+      const component = this.constructor;
+
+      if (setupRegistry.has(component)) {
+        return;
+      }
+
+      // Props with reflect: false
+      const noRef = new Set();
+      const names = [];
+
+      if (component.props) {
+        for (const p of component.props) {
+          if (typeof p === "string") {
+            names.push(p);
+          } else {
+            names.push(p.name);
+
+            if (p.reflect === false) {
+              noRef.add(p.name);
+            }
+          }
+        }
+
+        if (names.includes("text")) {
+          console.warn('░█ [ELENA]: "text" is reserved.');
+        }
+
+        setProps(component.prototype, names, noRef);
+      }
+
+      component._propNames = names;
+      component._noReflect = noRef;
+      component._elenaEvents = component.events || null;
+
+      if (component._elenaEvents) {
+        for (const e of component._elenaEvents) {
+          if (!Object.prototype.hasOwnProperty.call(component.prototype, e)) {
+            component.prototype[e] = function (...args) {
+              return this.element[e](...args);
+            };
+          }
+        }
+      }
+
+      component._resolver = elementResolver(component.element);
+      setupRegistry.add(component);
+    }
+
+    /**
+     * Moves class field defaults into Elena’s internal props store
+     * so that getters and setters work correctly.
+     *
+     * @internal
+     */
+    _captureClassFieldDefaults() {
+      this._syncing = true;
+
+      for (const name of this.constructor._propNames) {
+        if (Object.prototype.hasOwnProperty.call(this, name)) {
+          const value = this[name];
+          delete this[name];
+          this[name] = value;
+        }
+      }
+
+      this._syncing = false;
+    }
+
+    /**
+     * Saves any text inside the element before the first render.
+     *
+     * @internal
+     */
+    _captureText() {
+      if (!this._hydrated && this._text === undefined) {
+        this.text = this.textContent.trim();
+      }
+    }
+
+    /**
+     * The root node to render into. Returns the shadow root when shadow mode
+     * is enabled, otherwise the host element itself.
+     *
+     * @type {ShadowRoot | HTMLElement}
+     */
+    get _renderRoot() {
+      return this._shadow ?? this.shadowRoot ?? this;
+    }
+
+    /**
+     * Attaches a shadow root and adopts styles on first connect.
+     * Only runs when `static shadow` is set on the component class.
+     *
+     * @internal
+     */
+    _attachShadow() {
+      const component = this.constructor;
+
+      if (!component.shadow) {
+        return;
+      }
+
+      // A shadow root may already exist if Declarative Shadow DOM was used.
+      // In that case skip attachShadow() but still adopt styles below.
+      // Store the reference so closed shadow roots remain accessible.
+      if (!this._shadow && !this.shadowRoot) {
+        this._shadow = this.attachShadow({ mode: component.shadow });
+      }
+
+      const shadowRoot = this._shadow ?? this.shadowRoot;
+
+      if (!component.styles) {
+        return;
+      }
+
+      // Normalize to array and cache converted CSSStyleSheet instances on the class.
+      // Avoids re-parsing CSS strings on every element instance.
+      if (!component._adoptedSheets) {
+        const stylesList = Array.isArray(component.styles) ? component.styles : [component.styles];
+
+        component._adoptedSheets = stylesList.map(s => {
+          if (typeof s === "string") {
+            const sheet = new CSSStyleSheet();
+            sheet.replaceSync(s);
+            return sheet;
+          }
+          return s;
+        });
+      }
+
+      shadowRoot.adoptedStyleSheets = component._adoptedSheets;
+    }
+
+    /**
+     * Calls render() and updates the DOM with the result.
+     * Also resolves the inner element reference.
+     *
+     * @internal
+     */
+    _applyRender() {
+      const result = this.render();
+
+      if (result && result.strings) {
+        const root = this._renderRoot;
+        const rebuilt = renderTemplate(root, result.strings, result.values);
+
+        // Re-resolve element ref when the DOM was fully rebuilt.
+        // Fast-path text node patching leaves the DOM structure intact,
+        // so the existing ref is still valid.
+        if (rebuilt) {
+          const oldElement = this.element;
+          this.element = this.constructor._resolver(root);
+
+          // Re-bind event listeners when the inner element was replaced.
+          if (this._events && oldElement && this.element !== oldElement) {
+            const events = this.constructor._elenaEvents;
+
+            for (const e of events) {
+              oldElement.removeEventListener(e, this);
+              this.element.addEventListener(e, this);
+            }
+          }
+        }
+      }
+
+      // Resolve inner element on first render
+      if (!this.element) {
+        const root = this._renderRoot;
+        this.element = this.constructor._resolver(root);
+
+        if (!this.element) {
+          if (this.constructor.element) {
+            console.warn("░█ [ELENA]: Element not found.");
+          }
+          this.element = root.firstElementChild;
+        }
+      }
+    }
+
+    /**
+     * Syncs any props that were set before the element
+     * connected to the page.
+     *
+     * @internal
+     */
+    _syncProps() {
+      if (this._props) {
+        const noReflect = this.constructor._noReflect;
+
+        for (const [prop, value] of this._props) {
+          if (noReflect.has(prop)) {
+            continue;
+          }
+
+          const attrValue = getPropValue(typeof value, value, "toAttribute");
+
+          if (attrValue === null && !this.hasAttribute(prop)) {
+            continue;
+          }
+
+          syncAttribute(this, prop, attrValue);
+        }
+      }
+    }
+
+    /**
+     * Forwards events from the inner element
+     * up to the host element.
+     *
+     * @internal
+     */
+    _delegateEvents() {
+      const events = this.constructor._elenaEvents;
+
+      if (!this._events && events?.length) {
+        if (!this.element) {
+          console.warn("░█ [ELENA]: Cannot add events.");
+        } else {
+          this._events = true;
+
+          for (const e of events) {
+            this.element.addEventListener(e, this);
+          }
+        }
+      }
+    }
+
+    /**
+     * Define the element’s HTML here. Return an `html`
+     * tagged template. If not overridden, the element connects
+     * to the page without rendering anything.
+     */
+    render() {}
+
+    /**
+     * Called before every render.
+     * Override to prepare state before the template runs.
+     */
+    willUpdate() {}
+
+    /**
+     * Called once after the element’s first render.
+     * Override to run setup that needs the DOM.
+     */
+    firstUpdated() {}
+
+    /**
+     * Called after every render.
+     * Override to react to changes.
+     */
+    updated() {}
+
+    /**
+     * Called by the browser when the element is moved
+     * to a new document via `adoptNode()`.
+     */
+    adoptedCallback() {
+      super.adoptedCallback?.();
+    }
+
+    /**
+     * Called by the browser each time the element
+     * is removed from the page.
+     */
+    disconnectedCallback() {
+      super.disconnectedCallback?.();
+      if (this._events) {
+        this._events = false;
+
+        for (const e of this.constructor._elenaEvents) {
+          this.element?.removeEventListener(e, this);
+        }
+      }
+    }
+
+    /**
+     * Forwards events that cannot reach the host naturally:
+     * non-bubbling events (focus, blur) and non-composed
+     * events in Shadow DOM (change, submit, reset).
+     * Composed bubbling events (click, input) pass through on their own.
+     *
+     * @internal
+     */
+    handleEvent(event) {
+      if (!this.constructor._elenaEvents?.includes(event.type)) {
+        return;
+      }
+
+      if (!event.bubbles || (!event.composed && this._renderRoot !== this)) {
+        /** @internal */
+        this.dispatchEvent(new Event(event.type, { bubbles: event.bubbles }));
+      }
+    }
+
+    /**
+     * The text content of the element. Elena reads this
+     * from the element’s children before the first render.
+     * Updating it triggers a re-render.
+     *
+     * @type {string}
+     */
+    get text() {
+      return this._text ?? "";
+    }
+
+    set text(value) {
+      const old = this._text;
+      this._text = value;
+
+      if (this._hydrated && old !== value && !this._isRendering) {
+        this._safeRender();
+      }
+    }
+
+    /**
+     * Registers the component as a custom element using `static tagName`.
+     * Call this on your component class after the class body is defined,
+     * not on the Elena mixin itself.
+     */
+    static define() {
+      if (this.tagName) {
+        defineElement(this.tagName, this);
+      } else {
+        console.warn("░█ [ELENA]: define() without a tagName.");
+      }
+    }
+
+    /**
+     * Schedules a re-render via microtask. If called multiple times
+     * before the microtask fires, only one render runs.
+     *
+     * @internal
+     */
+    _safeRender() {
+      if (this._isRendering) {
+        return;
+      }
+      if (!this._renderPending) {
+        this._renderPending = true;
+        this._updateComplete = new Promise(resolve => {
+          this._resolveUpdate = resolve;
+        });
+        queueMicrotask(() => {
+          try {
+            this._performUpdate();
+          } catch (e) {
+            console.error("░█ [ELENA]:", e);
+          }
+        });
+      }
+    }
+
+    /**
+     * Runs the batched update cycle.
+     * Called by the microtask in _safeRender().
+     *
+     * @internal
+     */
+    _performUpdate() {
+      this._renderPending = false;
+      const resolve = this._resolveUpdate;
+      this._resolveUpdate = null;
+      try {
+        try {
+          this.willUpdate();
+          this._isRendering = true;
+          this._applyRender();
+        } finally {
+          this._isRendering = false;
+        }
+        this.updated();
+      } finally {
+        this._updateComplete = null;
+        resolve();
+      }
+    }
+
+    /**
+     * A Promise that resolves after the render completes.
+     * Resolves immediately if no render is scheduled.
+     *
+     * @type {Promise<void>}
+     */
+    get updateComplete() {
+      if (this._updateComplete) {
+        return this._updateComplete;
+      }
+      return Promise.resolve();
+    }
+
+    /**
+     * Schedules a re-render. Use this to manually trigger an
+     * update when Elena cannot detect the change automatically.
+     */
+    requestUpdate() {
+      if (this._hydrated && !this._isRendering) {
+        this._safeRender();
+      }
+    }
+  }
+
+  return ElenaElement;
+}