@microsoft/webui-framework 0.0.4 → 0.0.5

package/dist/element.js

@@ -0,0 +1,1008 @@
+import { getTemplate } from "./template.js";
+import { hydrationStart, hydrationEnd } from "./lifecycle.js";
+import { getObservableNames } from "./decorators.js";
+import { syncRepeat, dotWalk } from "./element/diff.js";
+import {
+  collectItemMarkers,
+  nextElement,
+  MARKER_COND_START,
+  MARKER_COND_END,
+  MARKER_REPEAT_START
+} from "./element/markers.js";
+import {
+  injectModuleStyle
+} from "./element/styles.js";
+import {
+  ATTR_KIND_BOOLEAN,
+  ATTR_KIND_COMPLEX,
+  ATTR_KIND_TEMPLATE
+} from "./element/types.js";
+const templateCache = /* @__PURE__ */ new WeakMap();
+const templateDOMCache = /* @__PURE__ */ new Map();
+const tplOrdinalCache = /* @__PURE__ */ new WeakMap();
+function getTplOrdinals(tplNode) {
+  let map = tplOrdinalCache.get(tplNode);
+  if (map) return map;
+  map = /* @__PURE__ */ new Map();
+  let elemOrd = 0;
+  let textOrd = 0;
+  const children = tplNode.childNodes;
+  for (let k = 0; k < children.length; k++) {
+    const type = children[k].nodeType;
+    if (type === 1) {
+      map.set(k, [1, elemOrd]);
+      elemOrd++;
+    } else if (type === 3) {
+      map.set(k, [3, textOrd]);
+      textOrd++;
+    }
+  }
+  tplOrdinalCache.set(tplNode, map);
+  return map;
+}
+const EMPTY_ARR = [];
+function childNodesArray(parent) {
+  const children = parent.childNodes;
+  const len = children.length;
+  const result = new Array(len);
+  for (let i = 0; i < len; i++) result[i] = children[i];
+  return result;
+}
+function getTemplateDom(meta) {
+  let cached = templateDOMCache.get(meta.h);
+  if (cached) return cached;
+  const div = document.createElement("div");
+  div.innerHTML = meta.h;
+  templateDOMCache.set(meta.h, div);
+  return div;
+}
+class WebUIElement extends HTMLElement {
+  constructor() {
+    super(...arguments);
+    this.$root = null;
+    this.$ready = false;
+    this.$hydrated = false;
+    this.$dirtyPaths = null;
+    this.$pendingFlush = false;
+    /** Cached condition resolver — avoids allocating a closure per evaluation. */
+    this.$resolver = (p, s) => this.$resolveValue(p, s);
+  }
+  static define(tagName) {
+    customElements.define(tagName, this);
+  }
+  // ── Lifecycle ─────────────────────────────────────────────────
+  connectedCallback() {
+    const tag = this.tagName.toLowerCase();
+    if (this.$hydrated && this.$root) {
+      hydrationStart();
+      this.$ready = true;
+      this.$update();
+      hydrationEnd();
+      return;
+    }
+    const meta = getTemplate(tag);
+    if (!meta) {
+      console.warn(
+        `[WebUI] Template metadata for <${tag}> not found. Ensure the component is included in the SSR output or registered via __webui_templates.`
+      );
+      return;
+    }
+    this.$meta = meta;
+    if (document.readyState === "loading") {
+      const handler = () => {
+        document.removeEventListener("DOMContentLoaded", handler);
+        this.$mount(meta);
+      };
+      document.addEventListener("DOMContentLoaded", handler);
+    } else {
+      this.$mount(meta);
+    }
+  }
+  /** Mount the component after children are available. */
+  $mount(meta) {
+    if (this.$hydrated) return;
+    hydrationStart();
+    const hasShadow = !!this.shadowRoot;
+    const wantShadow = hasShadow || !!meta.sd || !!window.__webui_shadow;
+    let root;
+    let isSSR;
+    if (hasShadow) {
+      root = this.shadowRoot;
+      isSSR = true;
+    } else if (this.childNodes.length > 0) {
+      root = this;
+      isSSR = true;
+    } else if (wantShadow) {
+      root = this.attachShadow({ mode: "open" });
+      const fragment = this.$parseTemplate(meta);
+      root.appendChild(fragment);
+      isSSR = false;
+    } else {
+      const fragment = this.$parseTemplate(meta);
+      this.appendChild(fragment);
+      root = this;
+      isSSR = false;
+    }
+    if (meta.sa) injectModuleStyle(meta.sa, this.shadowRoot);
+    if (isSSR) {
+      this.$applySSRState();
+      this.$root = this.$hydrate(root, meta, getTemplateDom(meta));
+    } else {
+      this.$root = this.$wire(root, meta);
+    }
+    this.$meta = meta;
+    this.$hydrated = true;
+    this.$ready = true;
+    hydrationEnd();
+  }
+  disconnectedCallback() {
+  }
+  /** Dispatch a bubbling custom event. Uses composed:true when in shadow DOM. */
+  $emit(name, detail) {
+    return this.dispatchEvent(
+      new CustomEvent(name, {
+        bubbles: true,
+        cancelable: true,
+        composed: !!this.shadowRoot,
+        detail
+      })
+    );
+  }
+  /** Populate @observable properties from router state. */
+  setInitialState(state) {
+    const names = getObservableNames(this.constructor);
+    for (const key of Object.keys(state)) {
+      if (names.has(key)) {
+        this[key] = state[key];
+      }
+    }
+  }
+  /**
+   * Apply SSR state from the global `window.__webui_state` object.
+   *
+   * Passing the same props to both server render and client
+   * hydrate, this ensures component observables match the server-rendered
+   * DOM. The handler emits the state as a `<script>` tag at the end of
+   * the page. Only observable properties are set — unknown keys are ignored.
+   *
+   * Writes directly to the backing field (`_prop`) to avoid triggering
+   * reactive updates before bindings are wired.
+   */
+  $applySSRState() {
+    const state = window.__webui_state;
+    if (!state || typeof state !== "object") return;
+    const names = getObservableNames(this.constructor);
+    for (const key of Object.keys(state)) {
+      if (names.has(key)) {
+        this[`_${key}`] = state[key];
+      }
+    }
+  }
+  /** Reactive update — called by @observable/@attr setters. */
+  $update(path) {
+    if (!this.$ready || !this.$root) return;
+    if (!this.$pathIndex) this.$buildPathIndex();
+    if (path && this.$pathIndex) {
+      const entry = this.$pathIndex.get(path);
+      if (entry) {
+        if (!this.$dirtyPaths) this.$dirtyPaths = /* @__PURE__ */ new Set();
+        this.$dirtyPaths.add(path);
+        if (!this.$pendingFlush) {
+          this.$pendingFlush = true;
+          queueMicrotask(() => this.$flush());
+        }
+        return;
+      }
+    }
+    this.$dirtyPaths = null;
+    this.$updateInstance(this.$root);
+  }
+  /** Synchronously flush all queued path updates. Call this when you need
+   *  the DOM to reflect pending property changes immediately. */
+  $flushUpdates() {
+    if (this.$pendingFlush) this.$flush();
+  }
+  /** Flush all queued path updates. Handles re-entrant setter calls. */
+  $flush() {
+    if (!this.$ready || !this.$root || !this.$pathIndex) {
+      this.$dirtyPaths = null;
+      this.$pendingFlush = false;
+      return;
+    }
+    while (this.$dirtyPaths && this.$dirtyPaths.size > 0) {
+      const dirty = this.$dirtyPaths;
+      this.$dirtyPaths = null;
+      for (const path of dirty) {
+        const entry = this.$pathIndex.get(path);
+        if (entry) {
+          this.$updateBindings(entry.texts, entry.attrs, entry.conds, entry.repeats);
+        }
+      }
+      if (this.$wildcardBindings) {
+        const wc = this.$wildcardBindings;
+        this.$updateBindings(wc.texts, wc.attrs, wc.conds, wc.repeats);
+      }
+    }
+    this.$pendingFlush = false;
+  }
+  // ── DOM resolution: client-created path ───────────────────────
+  // Compiled paths are childNode indices in meta.h parsed by the browser.
+  // For client-created components the DOM matches meta.h exactly.
+  $resolve(root, path, pathStart = 0) {
+    let cur = root;
+    for (let i = 0; i < pathStart; i++) {
+      const child = cur.childNodes[path[i]];
+      if (!child) return null;
+      cur = child;
+    }
+    for (let i = pathStart; i < path.length; i++) {
+      const child = cur.childNodes[path[i]];
+      if (!child) return null;
+      cur = child;
+    }
+    return cur;
+  }
+  // ── DOM resolution: SSR hydration path ────────────────────────
+  // SSR DOM may lack whitespace text nodes the compiled template has.
+  // We walk the template DOM in parallel to translate each childNode
+  // index into an element-ordinal lookup in the SSR DOM.
+  // pathStart: skip leading path segments for in-place block hydration.
+  $resolveSSR(ssrRoot, tplRoot, path, pathStart = 0) {
+    let ssr = ssrRoot;
+    let tpl = tplRoot;
+    for (let i = 0; i < pathStart; i++) {
+      const tplChild = tpl.childNodes[path[i]];
+      if (!tplChild) return null;
+      tpl = tplChild;
+    }
+    for (let i = pathStart; i < path.length; i++) {
+      const idx = path[i];
+      const tplChild = tpl.childNodes[idx];
+      if (!tplChild) return null;
+      const ordinals = getTplOrdinals(tpl);
+      const entry = ordinals.get(idx);
+      if (!entry) return null;
+      const [nodeType, ordinal] = entry;
+      let count = 0;
+      let child = ssr.firstChild;
+      while (child) {
+        if (child.nodeType === nodeType) {
+          if (count === ordinal) break;
+          count++;
+        }
+        child = child.nextSibling;
+      }
+      if (!child) return null;
+      ssr = child;
+      tpl = tplChild;
+    }
+    return ssr;
+  }
+  // ── Template parsing ──────────────────────────────────────────
+  $parseTemplate(meta) {
+    let cached = templateCache.get(meta);
+    if (cached) return cached.cloneNode(true);
+    const tpl = document.createElement("template");
+    tpl.innerHTML = meta.h;
+    templateCache.set(meta, tpl.content);
+    return tpl.content.cloneNode(true);
+  }
+  // ═══════════════════════════════════════════════════════════════
+  //  Client-created wiring — exact childNode index resolution
+  // ═══════════════════════════════════════════════════════════════
+  $wire(root, meta, scope) {
+    const instance = {
+      scope,
+      nodes: childNodesArray(root),
+      texts: [],
+      attrs: [],
+      conds: [],
+      repeats: []
+    };
+    const textRefs = [];
+    if (meta.tx) {
+      for (let i = 0; i < meta.tx.length; i++) {
+        const entry = meta.tx[i];
+        const [slot, parts] = entry;
+        const raw = entry[2] === 1;
+        const [parentPath, beforeIndex] = slot;
+        const parent = parentPath.length > 0 ? this.$resolve(root, parentPath) : root;
+        if (!parent || parent.nodeType !== 1 && parent.nodeType !== 11) continue;
+        textRefs.push({ parent, ref: parent.childNodes[beforeIndex] || null, parts, raw });
+      }
+    }
+    const condRefs = [];
+    if (meta.c) {
+      for (let i = 0; i < meta.c.length; i++) {
+        const [condition, blockIndex, slotMeta] = meta.c[i];
+        const [parentPath, beforeIndex] = slotMeta;
+        const parent = parentPath.length > 0 ? this.$resolve(root, parentPath) : root;
+        if (!parent || parent.nodeType !== 1 && parent.nodeType !== 11) continue;
+        condRefs.push({ parent, ref: parent.childNodes[beforeIndex] || null, condition, blockIndex });
+      }
+    }
+    const repRefs = [];
+    if (meta.r) {
+      for (let i = 0; i < meta.r.length; i++) {
+        const [collection, itemVar, blockIndex, slotMeta] = meta.r[i];
+        const [parentPath, beforeIndex] = slotMeta;
+        const parent = parentPath.length > 0 ? this.$resolve(root, parentPath) : root;
+        if (!parent || parent.nodeType !== 1 && parent.nodeType !== 11) continue;
+        repRefs.push({ parent, ref: parent.childNodes[beforeIndex] || null, collection, itemVar, blockIndex });
+      }
+    }
+    this.$wireAttrs(instance, meta, scope, (p) => this.$resolve(root, p));
+    this.$finalize(root, meta, (r, p) => this.$resolve(r, p));
+    for (const t of textRefs) {
+      const anchor = document.createComment("");
+      t.parent.insertBefore(anchor, t.ref);
+      if (t.raw) {
+        const container = document.createElement("span");
+        t.parent.insertBefore(container, anchor);
+        const textNode = document.createTextNode("");
+        instance.texts.push({ node: textNode, parts: t.parts, scope, raw: true, rawParent: container });
+      } else {
+        const textNode = document.createTextNode("");
+        t.parent.insertBefore(textNode, anchor);
+        instance.texts.push({ node: textNode, parts: t.parts, scope });
+      }
+    }
+    for (const c of condRefs) {
+      const anchor = document.createComment("");
+      c.parent.insertBefore(anchor, c.ref);
+      instance.conds.push({ condition: c.condition, blockIndex: c.blockIndex, anchor, scope, instance: null });
+    }
+    for (let i = 0; i < repRefs.length; i++) {
+      const r = repRefs[i];
+      const anchor = document.createComment("");
+      r.parent.insertBefore(anchor, r.ref);
+      const { attrMap, rootBindings } = this.$repeatMaps(r.blockIndex, r.itemVar);
+      instance.repeats.push({
+        markerId: i,
+        collection: r.collection,
+        itemVar: r.itemVar,
+        blockIndex: r.blockIndex,
+        container: r.parent,
+        start: anchor,
+        end: null,
+        scope,
+        owner: instance,
+        instances: [],
+        rootTag: null,
+        attrMap,
+        rootBindings
+      });
+    }
+    for (let i = 0; i < instance.conds.length; i++) this.$toggleCond(instance.conds[i]);
+    return instance;
+  }
+  // ═══════════════════════════════════════════════════════════════
+  //  SSR hydration — marker-based in-place DOM matching
+  // ═══════════════════════════════════════════════════════════════
+  /**
+   * Hydrate SSR-rendered DOM against compiled template metadata.
+   *
+   * When pathStart=0 (default): ssrRoot is a container with children
+   * (top-level component hydration).
+   *
+   * When pathStart=1: ssrRoot is a block element itself (repeat item
+   * in-place hydration). The leading [0] wrapper segment is skipped
+   * so compiled paths resolve directly against the element.
+   */
+  $hydrate(ssrRoot, meta, tplDom, scope, pathStart = 0) {
+    const instance = {
+      scope,
+      nodes: pathStart > 0 ? [ssrRoot] : childNodesArray(ssrRoot),
+      texts: [],
+      attrs: [],
+      conds: [],
+      repeats: []
+    };
+    if (meta.tx) {
+      for (let i = 0; i < meta.tx.length; i++) {
+        const entry = meta.tx[i];
+        const [slot, parts] = entry;
+        const raw = entry[2] === 1;
+        const [parentPath, beforeIndex] = slot;
+        const ssrParent = this.$resolveSSR(ssrRoot, tplDom, parentPath, pathStart);
+        if (!ssrParent) continue;
+        const tplParent = this.$resolve(tplDom, parentPath, pathStart);
+        if (!tplParent) continue;
+        if (raw) {
+          const rawParent = ssrParent;
+          const textNode = document.createTextNode("");
+          instance.texts.push({ node: textNode, parts, scope, raw: true, rawParent });
+        } else {
+          const textNode = this.$findSSRText(ssrParent, tplParent, beforeIndex);
+          if (textNode) instance.texts.push({ node: textNode, parts, scope });
+        }
+      }
+    }
+    this.$wireAttrs(
+      instance,
+      meta,
+      scope,
+      (p) => this.$resolveSSR(ssrRoot, tplDom, p, pathStart)
+    );
+    if (meta.c) {
+      let lastCondMarker = null;
+      let lastCondParent = null;
+      for (let i = 0; i < meta.c.length; i++) {
+        const [condition, blockIndex, slotMeta] = meta.c[i];
+        const [parentPath] = slotMeta;
+        const ssrParent = this.$resolveSSR(ssrRoot, tplDom, parentPath, pathStart) ?? ssrRoot;
+        const blockMeta = this.$block(blockIndex);
+        const shown = condition[0](this.$resolver, scope);
+        let condInstance = null;
+        if (ssrParent !== lastCondParent) {
+          lastCondMarker = null;
+          lastCondParent = ssrParent;
+        }
+        const marker = this.$findMarker(ssrParent, MARKER_COND_START, lastCondMarker);
+        let condAnchor;
+        if (marker) {
+          condAnchor = marker;
+        } else {
+          condAnchor = document.createComment("");
+          const [, beforeIndex] = slotMeta;
+          const insertRef = ssrParent.childNodes[beforeIndex ?? ssrParent.childNodes.length] ?? null;
+          ssrParent.insertBefore(condAnchor, insertRef);
+        }
+        if (marker) lastCondMarker = marker;
+        if (shown && blockMeta && marker) {
+          condInstance = this.$hydrateCondContent(condAnchor, blockMeta, scope);
+        }
+        if (marker) {
+          const lastNode = condInstance ? condInstance.nodes[condInstance.nodes.length - 1] : condAnchor;
+          const endMarker = lastNode?.nextSibling;
+          if (endMarker && endMarker.nodeType === 8 && endMarker.data === MARKER_COND_END) {
+            endMarker.parentNode?.removeChild(endMarker);
+          }
+        }
+        instance.conds.push({
+          condition,
+          blockIndex,
+          anchor: condAnchor,
+          scope,
+          instance: condInstance
+        });
+      }
+    }
+    if (meta.r) {
+      let lastRepMarker = null;
+      let lastRepParent = null;
+      for (let i = 0; i < meta.r.length; i++) {
+        const [collection, itemVar, blockIndex, slotMeta] = meta.r[i];
+        const [parentPath] = slotMeta;
+        const ssrParent = this.$resolveSSR(ssrRoot, tplDom, parentPath, pathStart) ?? ssrRoot;
+        if (ssrParent !== lastRepParent) {
+          lastRepMarker = null;
+          lastRepParent = ssrParent;
+        }
+        const blockMeta = this.$block(blockIndex);
+        const { attrMap, rootBindings } = this.$repeatMaps(blockIndex, itemVar);
+        const rootTag = blockMeta ? this.$rootTag(blockMeta) : null;
+        const marker = this.$findMarker(ssrParent, MARKER_REPEAT_START, lastRepMarker);
+        let anchor;
+        if (marker) {
+          anchor = marker;
+        } else {
+          anchor = document.createComment("");
+          const [, beforeIndex] = slotMeta;
+          const tplParent = this.$resolve(tplDom, parentPath, pathStart);
+          const staticCount = tplParent ? tplParent.childNodes.length : 0;
+          const insertRef = ssrParent.childNodes[Math.min(beforeIndex ?? staticCount, ssrParent.childNodes.length)] ?? null;
+          ssrParent.insertBefore(anchor, insertRef);
+        }
+        lastRepMarker = anchor;
+        const repeatInsts = [];
+        const itemsArr = this.$resolveValue(collection, scope);
+        const items = Array.isArray(itemsArr) ? itemsArr : [];
+        const { items: itemMarkers, end: endMarker } = marker ? collectItemMarkers(anchor) : { items: [], end: null };
+        if (blockMeta && items.length > 0 && anchor.parentNode && itemMarkers.length > 0) {
+          if (itemMarkers.length !== items.length) {
+            console.warn(
+              `[webui] hydration: repeat marker count (${itemMarkers.length}) \u2260 data length (${items.length}) for "${collection}"`
+            );
+          }
+          const firstKey = Object.keys(attrMap)[0];
+          const blockTplDom = getTemplateDom(blockMeta);
+          const limit = Math.min(itemMarkers.length, items.length);
+          for (let j = 0; j < limit; j++) {
+            const itemValue = items[j];
+            const itemScope = { name: itemVar, value: itemValue, parent: scope };
+            if (rootTag) {
+              const itemEl = nextElement(itemMarkers[j]);
+              if (itemEl) {
+                const key = firstKey !== void 0 ? itemEl.getAttribute(firstKey) : String(j);
+                const childInstance = this.$hydrate(itemEl, blockMeta, blockTplDom, itemScope, 1);
+                repeatInsts.push({ key, value: itemValue, instance: childInstance });
+              }
+            } else {
+              const inst = {
+                scope: itemScope,
+                nodes: [],
+                texts: EMPTY_ARR,
+                attrs: EMPTY_ARR,
+                conds: [],
+                repeats: EMPTY_ARR
+              };
+              if (blockMeta.c) {
+                let cursor = itemMarkers[j].nextSibling;
+                const nextBound = j + 1 < itemMarkers.length ? itemMarkers[j + 1] : endMarker;
+                const itemParent = itemMarkers[j].parentNode;
+                for (let ci = 0; ci < blockMeta.c.length; ci++) {
+                  const [condCond, condBlockIndex] = blockMeta.c[ci];
+                  let condAnchor = null;
+                  while (cursor && cursor !== nextBound) {
+                    if (cursor.nodeType === 8 && cursor.data === MARKER_COND_START) {
+                      condAnchor = cursor;
+                      cursor = cursor.nextSibling;
+                      break;
+                    }
+                    cursor = cursor.nextSibling;
+                  }
+                  if (!condAnchor) {
+                    condAnchor = document.createComment("");
+                    if (itemParent) itemParent.insertBefore(condAnchor, cursor ?? null);
+                  }
+                  const condMet = condCond[0](this.$resolver, itemScope);
+                  let condInstance = null;
+                  if (condMet) {
+                    const condBlockMeta = this.$block(condBlockIndex);
+                    if (condBlockMeta) {
+                      condInstance = this.$hydrateCondContent(condAnchor, condBlockMeta, itemScope);
+                    }
+                  }
+                  const lastNode = condInstance ? condInstance.nodes[condInstance.nodes.length - 1] : condAnchor;
+                  const endM = lastNode?.nextSibling;
+                  if (endM && endM.nodeType === 8 && endM.data === MARKER_COND_END) {
+                    cursor = endM.nextSibling;
+                    endM.parentNode?.removeChild(endM);
+                  } else {
+                    cursor = lastNode?.nextSibling ?? null;
+                  }
+                  inst.conds.push({
+                    condition: condCond,
+                    blockIndex: condBlockIndex,
+                    anchor: condAnchor,
+                    scope: itemScope,
+                    instance: condInstance
+                  });
+                }
+              }
+              repeatInsts.push({ key: String(j), value: itemValue, instance: inst });
+            }
+          }
+          for (let m = 0; m < itemMarkers.length; m++) {
+            itemMarkers[m].parentNode?.removeChild(itemMarkers[m]);
+          }
+        }
+        if (endMarker) endMarker.parentNode?.removeChild(endMarker);
+        instance.repeats.push({
+          markerId: i,
+          collection,
+          itemVar,
+          blockIndex,
+          container: anchor.parentNode ?? ssrRoot,
+          start: anchor,
+          end: null,
+          scope,
+          owner: instance,
+          instances: repeatInsts,
+          rootTag,
+          attrMap,
+          rootBindings,
+          synced: true
+        });
+      }
+    }
+    this.$finalize(ssrRoot, meta, (r, p) => this.$resolveSSR(r, tplDom, p, pathStart));
+    return instance;
+  }
+  // ── SSR helpers ───────────────────────────────────────────────
+  /** Collect sibling nodes between a start marker and an end marker comment. */
+  $collectBetween(start, endData) {
+    const nodes = [];
+    let node = start.nextSibling;
+    while (node) {
+      if (node.nodeType === 8 && node.data === endData) break;
+      nodes.push(node);
+      node = node.nextSibling;
+    }
+    return nodes;
+  }
+  /**
+   * Hydrate a conditional block's content — shared by top-level and
+   * repeat-item conditional hydration paths.
+   */
+  $hydrateCondContent(condAnchor, blockMeta, scope) {
+    const rootTag = this.$rootTag(blockMeta);
+    if (rootTag) {
+      const el = nextElement(condAnchor);
+      if (el) {
+        const inst2 = this.$hydrate(el, blockMeta, getTemplateDom(blockMeta), scope, 1);
+        this.$updateInstance(inst2);
+        return inst2;
+      }
+      return null;
+    }
+    const condNodes = this.$collectBetween(condAnchor, MARKER_COND_END);
+    if (condNodes.length === 0) return null;
+    const wrapper = document.createElement("div");
+    for (let cn = 0; cn < condNodes.length; cn++) wrapper.appendChild(condNodes[cn]);
+    const inst = this.$hydrate(wrapper, blockMeta, getTemplateDom(blockMeta), scope);
+    inst.nodes = childNodesArray(wrapper);
+    let afterNode = condAnchor;
+    for (let cn = 0; cn < inst.nodes.length; cn++) {
+      condAnchor.parentNode?.insertBefore(inst.nodes[cn], afterNode.nextSibling);
+      afterNode = inst.nodes[cn];
+    }
+    this.$updateInstance(inst);
+    return inst;
+  }
+  /**
+   * Find the next marker comment with the given data among a parent's children.
+   * Starts searching from `after` (exclusive) if provided, or from firstChild.
+   */
+  $findMarker(parent, data, after) {
+    let child = after ? after.nextSibling : parent.firstChild;
+    while (child) {
+      if (child.nodeType === 8 && child.data === data) {
+        return child;
+      }
+      child = child.nextSibling;
+    }
+    return null;
+  }
+  /** Find existing SSR text node by mapping template text-node ordinal. */
+  $findSSRText(ssrParent, tplParent, beforeIndex) {
+    const ordinals = getTplOrdinals(tplParent);
+    let textOrd = 0;
+    for (let k = 0; k < beforeIndex; k++) {
+      const entry = ordinals.get(k);
+      if (entry && entry[0] === 3) textOrd++;
+    }
+    let count = 0;
+    let child = ssrParent.firstChild;
+    while (child) {
+      if (child.nodeType === 3) {
+        if (count === textOrd) return child;
+        count++;
+      }
+      child = child.nextSibling;
+    }
+    child = ssrParent.firstChild;
+    while (child) {
+      if (child.nodeType === 3 && child.data && child.data.trim()) {
+        return child;
+      }
+      child = child.nextSibling;
+    }
+    return null;
+  }
+  /** Extract root tag name from block metadata. */
+  $rootTag(meta) {
+    const h = meta.h;
+    if (!h || h.charCodeAt(0) !== 60) return null;
+    let end = 1;
+    while (end < h.length) {
+      const c = h.charCodeAt(end);
+      if (c === 32 || c === 62 || c === 47) break;
+      end++;
+    }
+    return h.slice(1, end).toLowerCase();
+  }
+  // ═══════════════════════════════════════════════════════════════
+  //  Shared: binding wiring, event wiring, refs
+  // ═══════════════════════════════════════════════════════════════
+  /** Wire attribute bindings using a resolver (shared by $wire and $hydrate). */
+  $wireAttrs(instance, meta, scope, resolve) {
+    if (!meta.a || !meta.ag) return;
+    for (let g = 0; g < meta.ag.length; g++) {
+      const [targetPath, start, count] = meta.ag[g];
+      const el = resolve(targetPath);
+      if (!el || el.nodeType !== 1) continue;
+      for (let j = 0; j < count; j++) {
+        const entry = meta.a[start + j];
+        if (entry) instance.attrs.push(this.$makeAttr(el, entry, scope));
+      }
+    }
+  }
+  /** Wire events + root events + refs (shared by $wire and $hydrate). */
+  $finalize(root, meta, resolver) {
+    this.$wireEvents(root, meta, resolver);
+    if (meta.re) this.$wireRoot(meta.re);
+    this.$wireRefs(root);
+  }
+  /** Wire events using a resolver function (works for both client and SSR). */
+  $wireEvents(root, meta, resolver) {
+    if (!meta.e) return;
+    for (let i = 0; i < meta.e.length; i++) {
+      const [eventName, handlerName, needsEvent, target] = meta.e[i];
+      const el = resolver(root, target);
+      if (!el || el.nodeType !== 1) continue;
+      this.$addEvent(el, eventName, handlerName, needsEvent);
+    }
+  }
+  /** Wire root-level events on the host element (or shadow root when present). */
+  $wireRoot(re) {
+    const target = this.shadowRoot ?? this;
+    for (let i = 0; i < re.length; i++) {
+      this.$addEvent(target, re[i][0], re[i][1], re[i][2]);
+    }
+  }
+  /** Attach a single event listener. */
+  $addEvent(target, eventName, handlerName, needsEvent) {
+    const method = this[handlerName];
+    if (typeof method !== "function") return;
+    const self = this;
+    target.addEventListener(
+      eventName,
+      needsEvent ? (e) => method.call(self, e) : () => method.call(self)
+    );
+  }
+  /** Find w-ref attributes and assign to component properties. */
+  $wireRefs(root) {
+    if (root.nodeType !== 1 && root.nodeType !== 11) return;
+    const refs = root.querySelectorAll("[w-ref]");
+    for (let i = 0; i < refs.length; i++) {
+      const raw = refs[i].getAttribute("w-ref");
+      if (!raw || raw.charCodeAt(0) !== 123) continue;
+      const name = raw.slice(1, -1);
+      if (name) this[name] = refs[i];
+    }
+  }
+  /** Create an AttrBinding from compiled metadata. */
+  $makeAttr(el, entry, scope) {
+    const name = entry[0];
+    const kind = entry[1];
+    if (kind === ATTR_KIND_BOOLEAN) return { element: el, name, kind, condition: entry[2], scope };
+    if (kind === ATTR_KIND_TEMPLATE) return { element: el, name, kind, parts: entry[2], scope };
+    return { element: el, name, kind, path: entry[2] || "", scope };
+  }
+  /** Build attrMap and rootBindings for a repeat block. */
+  $repeatMaps(blockIndex, itemVar) {
+    const attrMap = {};
+    const rootBindings = [];
+    const bm = this.$block(blockIndex);
+    if (bm?.a && bm.ag) {
+      for (let g = 0; g < bm.ag.length; g++) {
+        const [tp, s, c] = bm.ag[g];
+        const isRoot = tp.length === 0 || tp.length === 1 && tp[0] === 0;
+        if (isRoot) {
+          for (let j = 0; j < c; j++) {
+            const entry = bm.a[s + j];
+            if (entry) {
+              rootBindings.push(entry);
+              if (entry[1] === 0 || entry[1] === 3) {
+                const dp = this.$singleDynamic(
+                  entry[1] === 3 ? entry[2] : [[entry[2]]]
+                );
+                if (dp && dp.path.startsWith(itemVar + ".")) {
+                  attrMap[entry[0]] = dp.path.slice(itemVar.length + 1);
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+    return { attrMap, rootBindings };
+  }
+  // ═══════════════════════════════════════════════════════════════
+  //  Reactive update system
+  // ═══════════════════════════════════════════════════════════════
+  $buildPathIndex() {
+    if (!this.$root) return;
+    const observableNames = getObservableNames(this.constructor);
+    const index = /* @__PURE__ */ new Map();
+    const ensure = (key) => {
+      let e = index.get(key);
+      if (!e) {
+        e = { texts: [], attrs: [], conds: [], repeats: [] };
+        index.set(key, e);
+      }
+      return e;
+    };
+    const keyFor = (path) => {
+      const dot = path.indexOf(".");
+      const root = dot > -1 ? path.slice(0, dot) : path;
+      return observableNames.has(root) ? root : "*";
+    };
+    const r = this.$root;
+    for (const t of r.texts) {
+      if (t.parts) {
+        for (const p of t.parts) {
+          if (typeof p !== "string") ensure(keyFor(p[0])).texts.push(t);
+        }
+      }
+    }
+    for (const a of r.attrs) {
+      if (a.path) ensure(keyFor(a.path)).attrs.push(a);
+      if (a.parts) {
+        for (const p of a.parts) {
+          if (typeof p !== "string") ensure(keyFor(p[0])).attrs.push(a);
+        }
+      }
+      if (a.condition) {
+        for (const p of a.condition[1]) ensure(keyFor(p)).attrs.push(a);
+      }
+    }
+    for (const c of r.conds) {
+      for (const p of c.condition[1]) ensure(keyFor(p)).conds.push(c);
+    }
+    for (const rep of r.repeats) {
+      ensure(keyFor(rep.collection)).repeats.push(rep);
+    }
+    const wc = index.get("*");
+    if (wc) {
+      index.delete("*");
+      this.$wildcardBindings = wc;
+    } else {
+      this.$wildcardBindings = null;
+    }
+    this.$pathIndex = index;
+  }
+  $updateBindings(texts, attrs, conds, repeats) {
+    for (let i = 0; i < texts.length; i++) this.$patchText(texts[i]);
+    for (let i = 0; i < attrs.length; i++) this.$patchAttr(attrs[i]);
+    for (let i = 0; i < conds.length; i++) this.$toggleCond(conds[i]);
+    for (let i = 0; i < repeats.length; i++) {
+      syncRepeat(this, repeats[i]);
+    }
+  }
+  $updateInstance(instance) {
+    this.$updateBindings(instance.texts, instance.attrs, instance.conds, instance.repeats);
+  }
+  $patchText(b) {
+    let val;
+    if (b.parts) {
+      val = this.$resolveParts(b.parts, b.scope);
+    } else if (b.path) {
+      const raw = this.$resolveValue(b.path, b.scope);
+      val = raw == null ? "" : String(raw);
+    } else {
+      return;
+    }
+    if (b.raw && b.rawParent) {
+      if (b.rawParent.innerHTML !== val) b.rawParent.innerHTML = val;
+    } else {
+      if (b.node.data !== val) b.node.data = val;
+    }
+  }
+  $patchAttr(b) {
+    const el = b.element;
+    switch (b.kind) {
+      case ATTR_KIND_COMPLEX: {
+        const v = this.$resolveValue(b.path, b.scope);
+        el[b.name] = v;
+        break;
+      }
+      case ATTR_KIND_BOOLEAN: {
+        const show = b.condition[0](this.$resolver, b.scope);
+        if (show) el.setAttribute(b.name, "");
+        else el.removeAttribute(b.name);
+        if (b.name === "checked" || b.name === "selected" || b.name === "disabled") {
+          el[b.name] = show;
+        }
+        break;
+      }
+      case ATTR_KIND_TEMPLATE: {
+        const v = this.$resolveParts(b.parts, b.scope);
+        if (el.getAttribute(b.name) !== v) el.setAttribute(b.name, v);
+        break;
+      }
+      default: {
+        const v = this.$resolveValue(b.path, b.scope);
+        const s = v == null ? "" : String(v);
+        if (b.name === "checked" || b.name === "selected") {
+          el[b.name] = !!v && v !== "false" && v !== "0";
+        } else if (b.name === "value") {
+          if (el.value !== s) el.value = s;
+        } else {
+          if (el.getAttribute(b.name) !== s) el.setAttribute(b.name, s);
+        }
+        break;
+      }
+    }
+  }
+  $toggleCond(c) {
+    const show = c.condition[0](this.$resolver, c.scope);
+    if (show) {
+      if (!c.instance) {
+        c.instance = this.$createBlockInstance(c.blockIndex, c.scope);
+        if (c.instance) {
+          const frag = document.createDocumentFragment();
+          for (const n of c.instance.nodes) frag.appendChild(n);
+          c.anchor.parentNode?.insertBefore(frag, c.anchor.nextSibling);
+        }
+      }
+      if (c.instance) this.$updateInstance(c.instance);
+    } else if (c.instance) {
+      this.$removeInstance(c.instance);
+      c.instance = null;
+    }
+  }
+  // ── Value resolution ──────────────────────────────────────────
+  $resolveValue(path, scope) {
+    let frame = scope;
+    while (frame) {
+      if (path === frame.name) return frame.value;
+      if (path.length > frame.name.length && path.charCodeAt(frame.name.length) === 46 && path.startsWith(frame.name)) {
+        return dotWalk(frame.value, path, frame.name.length + 1);
+      }
+      frame = frame.parent;
+    }
+    const dot = path.indexOf(".");
+    if (dot === -1) return this[path];
+    return dotWalk(this[path.substring(0, dot)], path, dot + 1);
+  }
+  $resolveParts(parts, scope) {
+    let result = "";
+    for (let i = 0; i < parts.length; i++) {
+      const p = parts[i];
+      if (typeof p === "string") {
+        result += p;
+        continue;
+      }
+      const v = this.$resolveValue(p[0], scope);
+      result += v == null ? "" : String(v);
+    }
+    return result;
+  }
+  // ── Block instance management ─────────────────────────────────
+  $block(blockIndex) {
+    return this.$meta?.b?.[blockIndex];
+  }
+  $createBlockInstance(blockIndex, scope) {
+    const bm = this.$block(blockIndex);
+    if (!bm) return null;
+    const frag = this.$parseTemplate(bm);
+    const wrapper = document.createElement("div");
+    wrapper.appendChild(frag);
+    const inst = this.$wire(wrapper, bm, scope);
+    inst.nodes = childNodesArray(wrapper);
+    return inst;
+  }
+  $removeInstance(instance) {
+    for (const n of instance.nodes) n.parentNode?.removeChild(n);
+    for (const c of instance.conds) {
+      if (c.instance) this.$removeInstance(c.instance);
+    }
+    for (const r of instance.repeats) {
+      for (const item of r.instances) this.$removeInstance(item.instance);
+    }
+  }
+  $insertInstanceAfter(cursor, container, instance) {
+    const nodes = instance.nodes;
+    if (nodes.length === 0) return cursor;
+    const ref = cursor ? cursor.nextSibling : container.firstChild;
+    if (nodes[0] === ref) return nodes[nodes.length - 1];
+    const frag = document.createDocumentFragment();
+    for (let i = 0; i < nodes.length; i++) frag.appendChild(nodes[i]);
+    container.insertBefore(frag, ref);
+    return nodes[nodes.length - 1];
+  }
+  /** Extract the single dynamic path from a compiled attr parts array. */
+  $singleDynamic(parts) {
+    let path = "";
+    let prefix = "";
+    let suffix = "";
+    let seen = false;
+    for (const p of parts) {
+      if (typeof p === "string") {
+        if (seen) suffix += p;
+        else prefix += p;
+        continue;
+      }
+      if (seen) return null;
+      path = p[0];
+      seen = true;
+    }
+    return seen ? { path, prefix, suffix } : null;
+  }
+}
+export {
+  WebUIElement
+};