@ruledwdl/dom 0.1.0 → 0.1.1

package/README.md

@@ -136,9 +136,17 @@ hero.registry.addRule({
 
 ### Instance Methods
 - `dom.remount()`: Rebuild the entire DOM from state snapshot.
-- `dom.getLiveMap()`: Returns a snapshot copy of `Map<semanticId, HTMLElement>`.
+- `dom.getLiveMap()`: Returns a snapshot copy of `Map<semanticId, HTMLElement>` (first element per semantic ID).
+- `dom.getLiveNodes(semanticId)`: Returns an array of all live elements matching `semanticId` (e.g. repeated loop rows).
+- `dom.getNode(semanticId, index = 0)`: Returns the live element at the specified index for `semanticId`.
 - `dom.destroy()`: Removes event listeners, empties container, and cleans up style tags.
 
+### Repeated Loops & Surgical Data Reconciliation
+`@ruledwdl/dom` natively reconciles repeated WDL loop layers (e.g. `li.feature*features`) without remounting or wiping `innerHTML`:
+- Materializes all items on initial mount with `data-wdl-index="0"`, `data-wdl-index="1"`, etc.
+- Resolves per-item attribute templates (e.g. `${text}`, `${_index}`).
+- On `component.data.set('features', nextItems)`, surgically updates retained rows, appends added rows, and removes deleted rows.
+
 ---
 
 ## License

package/dist/wdl-dom.min.js

@@ -1,2 +1,2 @@
-var f=new Set(["text","class","html"]);function p(l){if(typeof l!="string"){if(l&&typeof l=="object")return{tag:String(l.tag||"div").toLowerCase(),semanticId:String(l.semanticId||l.id||"").replace(/^\./,"")};throw new Error("[wdl-dom] invalid layer expression")}let e=l.trim(),i=e.match(/^([a-zA-Z][a-zA-Z0-9_-]*)(?:\.([a-zA-Z0-9_-]+))?$/);return i?{tag:i[1].toLowerCase(),semanticId:(i[2]||"").replace(/^\./,"")}:{tag:e.toLowerCase()||"div",semanticId:""}}function g(l){if(Array.isArray(l))return structuredClone(l);if(typeof l!="string"||!l.trim())return[];let e={tag:"__root__",semanticId:"",children:[]},i=[e],s=0,a=()=>i[i.length-1];for(;s<l.length;){let t=l[s];if(/\s/.test(t)){s++;continue}if(t===">"){let r=a().children[a().children.length-1];r&&i.push(r),s++;continue}if(t==="+"){s++;continue}if(t==="<"){s++,i.length>1&&i.pop();continue}let n="";for(;s<l.length&&/[a-zA-Z0-9_-]/.test(l[s]);)n+=l[s++];let o="";if(l[s]===".")for(s++;s<l.length&&/[a-zA-Z0-9_-]/.test(l[s]);)o+=l[s++];a().children.push({tag:n.toLowerCase()||"div",semanticId:o,children:[]})}return e.children}function h(l){return l==null?"":String(l).replace(/^\./,"")}var m=class{constructor(e={}){let{container:i,component:s,onDataBind:a=null,styleTarget:t=typeof document<"u"?document.head:null,debug:n=!1}=e;if(!i)throw new Error("[wdl-dom] container is required");if(!s)throw new Error("[wdl-dom] component (ComponentState) is required");if(this.container=typeof i=="string"?document.querySelector(i):i,!this.container)throw new Error("[wdl-dom] container not found");this.component=s,this.onDataBind=a,this.styleTarget=t,this.debug=n,this.liveMap=new Map,this._unsubs=[],this._styleEl=null,this._mount(),this._bindStateEvents()}remount(){this._mount()}getLiveMap(){return new Map(this.liveMap)}destroy(){this._unsubs.forEach(e=>{try{e()}catch{}}),this._unsubs=[],this.container.replaceChildren(),this.liveMap.clear(),this._styleEl&&this._styleEl.parentNode&&this._styleEl.parentNode.removeChild(this._styleEl),this._styleEl=null}_mount(){this.container.replaceChildren(),this.liveMap.clear();let e;try{e=typeof this.component.layers?.tree=="function"?this.component.layers.tree():g(this.component.layers?.list?.()??this.component.getSnapshot?.()?.layers)}catch(s){this._log("warn","tree() failed, falling back to simple parse",s);let a=this.component.getSnapshot?.()?.layers??"";e=g(a)}Array.isArray(e)||(e=[]);for(let s of e){let a=this._createElementFromNode(s);this.container.appendChild(a)}let i=this.component.attr?.list?.()??this.component.getSnapshot?.()?.attr??{};for(let[s,a]of Object.entries(i))this._applyAttrs(h(s),a);this._applyRootVariant(),this._syncRegistryStyles(),this._log("mount",`mounted ${this.liveMap.size} nodes`)}_createElementFromNode(e){let i=(e.tag||"div").toLowerCase(),s=h(e.semanticId||e.id||""),a=document.createElement(i);if(s&&(a.classList.add(s),a.setAttribute("wdl-comp",s),this.liveMap.set(s,a)),Array.isArray(e.children))for(let t of e.children)a.appendChild(this._createElementFromNode(t));return a}_bindStateEvents(){let e=this.component;if(typeof e.on!="function"){this._log("warn","component has no .on() \u2014 events will not be applied");return}let i=a=>this._onStateEvent(a),s=["layers:change","attr:change","data:change","variant:change","registry:change"];for(let a of s){let t=e.on(a,i);typeof t=="function"?this._unsubs.push(t):this._unsubs.push(()=>e.off?.(a,i))}}_onStateEvent(e){if(!(!e||!e.type))switch(this._log("event",e.type,e.action,e.targetId,e.payload),e.type){case"layers:change":this._handleLayers(e);break;case"attr:change":this._handleAttr(e);break;case"data:change":this._handleData(e);break;case"variant:change":this._handleVariant(e);break;case"registry:change":this._handleRegistry(e);break;default:this._log("warn","unknown event type",e.type)}}_handleLayers(e){let{action:i,targetId:s,payload:a}=e,t=h(s);switch(i){case"set":{this._mount();break}case"append":{let n=this.liveMap.get(t);if(!n){this._log("warn",`append: parent "${t}" not in liveMap \u2014 remounting`),this._mount();return}let o=p(a),r=this._createElementFromNode({tag:o.tag,semanticId:o.semanticId,children:[]});n.appendChild(r),this._log("op",`append <${o.tag}.${o.semanticId}> \u2192 #${t}`);break}case"prepend":{let n=this.liveMap.get(t);if(!n){this._log("warn",`prepend: parent "${t}" not in liveMap \u2014 remounting`),this._mount();return}let o=p(a),r=this._createElementFromNode({tag:o.tag,semanticId:o.semanticId,children:[]});n.insertBefore(r,n.firstChild),this._log("op",`prepend <${o.tag}.${o.semanticId}> \u2192 #${t}`);break}case"before":case"after":{let n=this.liveMap.get(t);if(!n||!n.parentNode){this._log("warn",`${i}: target "${t}" missing \u2014 remounting`),this._mount();return}let o=p(a),r=this._createElementFromNode({tag:o.tag,semanticId:o.semanticId,children:[]});i==="before"?n.parentNode.insertBefore(r,n):n.parentNode.insertBefore(r,n.nextSibling),this._log("op",`${i} <${o.tag}.${o.semanticId}> relative to #${t}`);break}case"wrap":{let n=this.liveMap.get(t);if(!n||!n.parentNode){this._log("warn",`wrap: target "${t}" missing \u2014 remounting`),this._mount();return}let o=p(a),r=this._createElementFromNode({tag:o.tag,semanticId:o.semanticId,children:[]});n.parentNode.insertBefore(r,n),r.appendChild(n),this._log("op",`wrap #${t} with <${o.tag}.${o.semanticId}>`);break}case"unwrap":{let n=this.liveMap.get(t);if(!n||!n.parentNode){this._log("warn",`unwrap: target "${t}" missing \u2014 remounting`),this._mount();return}let o=n.parentNode;for(;n.firstChild;)o.insertBefore(n.firstChild,n);n.remove(),this.liveMap.delete(t),this._log("op",`unwrap #${t}`);break}case"move":{let n=this.liveMap.get(t),{targetSemanticId:o,position:r}=a||{},c=h(o),d=this.liveMap.get(c);if(!n||!d){this._log("warn",`move: source "${t}" or target "${c}" missing \u2014 remounting`),this._mount();return}r==="before"?d.parentNode?.insertBefore(n,d):r==="after"?d.parentNode?.insertBefore(n,d.nextSibling):d.appendChild(n),this._log("op",`move #${t} -> ${r} #${c}`);break}case"remove":{let n=this.liveMap.get(t);if(!n){this._log("warn",`remove: #${t} not in liveMap`);return}for(let[o,r]of[...this.liveMap])o!==t&&n.contains(r)&&this.liveMap.delete(o);n.remove(),this.liveMap.delete(t),this._log("op",`remove #${t}`);break}case"update":{let n=this.liveMap.get(t);if(!n){this._log("warn",`update: #${t} missing \u2014 remounting`),this._mount();return}let o=a||{};if(o.tag&&o.tag.toLowerCase()!==n.tagName.toLowerCase()){let r=document.createElement(String(o.tag).toLowerCase());for(let c of n.attributes)r.setAttribute(c.name,c.value);for(;n.firstChild;)r.appendChild(n.firstChild);if(n.parentNode?.replaceChild(r,n),this.liveMap.set(t,r),o.semanticId&&h(o.semanticId)!==t){let c=h(o.semanticId);r.classList.remove(t),r.classList.add(c),r.setAttribute("wdl-comp",c),this.liveMap.delete(t),this.liveMap.set(c,r)}}else if(o.semanticId&&h(o.semanticId)!==t){let r=h(o.semanticId);n.classList.remove(t),n.classList.add(r),n.setAttribute("wdl-comp",r),this.liveMap.delete(t),this.liveMap.set(r,n)}this._log("op",`update #${t}`,o);break}default:this._log("warn",`layers: unknown action "${i}" \u2014 remounting`),this._mount()}}_handleAttr(e){let{action:i,targetId:s,payload:a}=e,t=h(s);if(i==="set"||i==="update"){this._applyAttrs(t,a||{}),this._log("op",`attr.${i} #${t}`,a);return}if(i==="remove"){let n=this.liveMap.get(t);if(!n)return;let o=a;o==null||o===""?(n.textContent="",n.className=t,this._log("op",`attr.remove entire #${t}`)):o==="text"?(n.textContent="",this._log("op",`attr.remove text from #${t}`)):o==="class"?(n.className=t,this._log("op",`attr.remove class from #${t}`)):o==="html"?(n.innerHTML="",this._log("op",`attr.remove html from #${t}`)):(n.removeAttribute(o),this._log("op",`attr.remove ${o} from #${t}`))}}_applyAttrs(e,i){if(!i||typeof i!="object")return;let s=this.liveMap.get(e);if(!s){this._log("warn",`attr: #${e} not in liveMap`);return}if(i.text!==void 0&&(s.textContent=String(i.text)),i.html!==void 0&&(s.innerHTML=String(i.html)),i.class!==void 0){let a=String(i.class).trim();s.className=a?`${e} ${a}`:e}for(let[a,t]of Object.entries(i))if(!f.has(a)){if(a==="style"&&t&&typeof t=="object"){Object.assign(s.style,t);continue}t==null?s.removeAttribute(a):s.setAttribute(a,String(t))}}_handleData(e){let{action:i,targetId:s,payload:a}=e,t=s||"";if(typeof this.onDataBind=="function")try{this.onDataBind(this.container,t,i==="remove"?void 0:a)}catch(n){this._log("warn","onDataBind error",n)}this._log("op",`data.${i} ${t}`,i==="remove"?void 0:a)}_handleVariant(e){let{targetId:i,payload:s}=e,a=h(i)||this._rootSemanticId(),t=this.liveMap.get(a);if(!t){let n=this._rootSemanticId(),o=n?this.liveMap.get(n):null;o&&(s?o.dataset.variant=String(s):delete o.dataset.variant,this._log("op",`variant \u2192 ${s||"(none)"} on #${n}`));return}s?t.dataset.variant=String(s):delete t.dataset.variant,this._log("op",`variant \u2192 ${s||"(none)"} on #${a}`)}_applyRootVariant(){let e=this.component.attr?.list?.()??this.component.getSnapshot?.()?.attr??{},i=this._rootSemanticId();if(!i)return;let s="."+i,a=e[s]?.["data-variant"]??e["."]?.["data-variant"]??null;a&&this.liveMap.has(i)&&(this.liveMap.get(i).dataset.variant=String(a))}_rootSemanticId(){for(let[i,s]of this.liveMap)if(s.parentNode===this.container)return i;let e=this.liveMap.keys().next();return e.done?"":e.value}_handleRegistry(e){this._syncRegistryStyles(),this._log("op",`registry.${e.action}`)}_syncRegistryStyles(){if(!this.styleTarget)return;let e=this.component.registry?.get?.()??this.component.getSnapshot?.()?.registry??null,i=this.component.id||this.component.getSnapshot?.()?.id||"comp";if(this._styleEl||(this._styleEl=document.createElement("style"),this._styleEl.setAttribute("data-wdl-dom",i),this.styleTarget.appendChild(this._styleEl)),!e){this._styleEl.textContent="";return}let s=Array.isArray(e.rules)?e.rules:[],a=[];if(e.vars&&typeof e.vars=="object"){let t=Object.entries(e.vars).map(([n,o])=>`--${n}: ${o};`).join(" ");t&&a.push(`:root, [wdl-comp] { ${t} }`)}for(let t of s){if(!t||!t.selector)continue;let n=typeof t.css=="string"?t.css:t.css&&typeof t.css=="object"?Object.entries(t.css).map(([c,d])=>`${u(c)}: ${d};`).join(" "):"";if(!n)continue;let o=t.selector.startsWith("&")?t.selector.replace("&",`[wdl-comp="${i}"]`):t.selector,r=t.media?`@media ${t.media} { ${o} { ${n} } }`:`${o} { ${n} }`;a.push(r)}this._styleEl.textContent=a.join(`
-`)}_log(e,...i){if(!this.debug&&e!=="warn")return;let s=`[wdl-dom:${e}]`;e==="warn"?console.warn(s,...i):console.log(s,...i)}};function u(l){return String(l).replace(/[A-Z]/g,e=>"-"+e.toLowerCase())}function _(l){return new m(l)}var y=_;export{m as WdlDom,_ as createWdlDom,y as default};
+var N=new Set(["text","class","html","alpine","htmx","attr-ref"]);function g(l,e){return!e||l==null?l??"":String(e).split(".").reduce((i,t)=>i!=null?i[t]:"",l)??""}function S(l,e){return typeof l!="string"?l:l.replace(/\$\{([\w.]+)\}/g,(i,t)=>{let s=g(e,t);return s!=null?String(s):""}).replace(/\{\{([\w.]+)\}\}/g,(i,t)=>{let s=g(e,t);return s!=null?String(s):""})}function f(l,e){return l==null?l:typeof l=="function"?"":typeof l=="string"?S(l,e):Array.isArray(l)?l.map(i=>f(i,e)):typeof l=="object"?Object.fromEntries(Object.entries(l).map(([i,t])=>[i,f(t,e)])):l}function m(l){if(typeof l!="string"){if(l&&typeof l=="object")return{tag:String(l.tag||"div").toLowerCase(),semanticId:String(l.semanticId||l.id||"").replace(/^\./,""),repeator:l.repeator||l.loopKey||null};throw new Error("[wdl-dom] invalid layer expression")}let i=l.trim(),t=null,s=i.indexOf("*");s!==-1&&(t=i.slice(s+1),i=i.slice(0,s));let n=i.match(/^([a-zA-Z][a-zA-Z0-9_-]*)(?:\.([a-zA-Z0-9_-]+))?$/);return n?{tag:n[1].toLowerCase(),semanticId:(n[2]||"").replace(/^\./,""),repeator:t}:{tag:i.toLowerCase()||"div",semanticId:"",repeator:t}}function w(l){if(Array.isArray(l))return structuredClone(l);if(typeof l!="string"||!l.trim())return[];let e={tag:"__root__",semanticId:"",children:[]},i=[e],t=0,s=()=>i[i.length-1];for(;t<l.length;){let n=l[t];if(/\s/.test(n)){t++;continue}if(n===">"){let r=s().children[s().children.length-1];r&&i.push(r),t++;continue}if(n==="+"){t++;continue}if(n==="<"){if(t++,t<l.length&&l[t]==="*"){t++;let r="";for(;t<l.length&&/\d/.test(l[t]);)r+=l[t++];let h=r?parseInt(r,10):1;for(let d=0;d<h;d++)i.length>1&&i.pop()}else if(t<l.length&&l[t]==="@"){t++;let r="";for(;t<l.length&&/\d/.test(l[t]);)r+=l[t++];let d=(r?parseInt(r,10):0)+1;for(;i.length>d&&i.length>1;)i.pop()}else{let r=1;for(;t<l.length&&l[t]==="<";)r++,t++;for(let h=0;h<r;h++)i.length>1&&i.pop()}continue}let c="";for(;t<l.length&&/[a-zA-Z0-9_-]/.test(l[t]);)c+=l[t++];let o="";if(l[t]===".")for(t++;t<l.length&&/[a-zA-Z0-9_-]/.test(l[t]);)o+=l[t++];let a=null;if(l[t]==="*"){t++;let r="";for(;t<l.length&&/[a-zA-Z0-9_.]/.test(l[t]);)r+=l[t++];r&&(a=r)}s().children.push({tag:c.toLowerCase()||"div",semanticId:o,repeator:a,children:[]})}return e.children}function p(l){return l==null?"":String(l).replace(/^\./,"")}var y=class{constructor(e={}){let{container:i,component:t,onDataBind:s=null,styleTarget:n=typeof document<"u"?document.head:null,debug:c=!1}=e;if(!i)throw new Error("[wdl-dom] container is required");if(!t)throw new Error("[wdl-dom] component (ComponentState) is required");if(this.container=typeof i=="string"?document.querySelector(i):i,!this.container)throw new Error("[wdl-dom] container not found");this.component=t,this.onDataBind=s,this.styleTarget=n,this.debug=c,this.liveMap=new Map,this.liveNodes=new Map,this._loopBindings=[],this._unsubs=[],this._styleEl=null,this._mount(),this._bindStateEvents()}remount(){this._mount()}getLiveMap(){return new Map(this.liveMap)}getLiveNodes(e){let i=p(e);return[...this.liveNodes.get(i)||[]]}getNode(e,i=0){return this.getLiveNodes(e)[i]||null}destroy(){this._unsubs.forEach(e=>{try{e()}catch{}}),this._unsubs=[],this.container.replaceChildren(),this.liveMap.clear(),this.liveNodes.clear(),this._loopBindings=[],this._styleEl&&this._styleEl.parentNode&&this._styleEl.parentNode.removeChild(this._styleEl),this._styleEl=null}_registerNode(e,i){if(!e)return;let t=p(e);this.liveNodes.has(t)||this.liveNodes.set(t,[]);let s=this.liveNodes.get(t);s.includes(i)||s.push(i),this.liveMap.set(t,s[0])}_unregisterNode(e,i){if(!e)return;let t=p(e);if(this.liveNodes.has(t)){let s=this.liveNodes.get(t),n=s.indexOf(i);n!==-1&&s.splice(n,1),s.length===0?(this.liveNodes.delete(t),this.liveMap.delete(t)):this.liveMap.set(t,s[0])}else this.liveMap.delete(t)}_unregisterElementHierarchy(e){if(!e)return;let i=e.getAttribute?.("wdl-comp");if(i&&this._unregisterNode(i,e),Array.isArray(e.children))for(let t of e.children)this._unregisterElementHierarchy(t)}_getComponentData(){return this.component.data?.get?.()??this.component.getSnapshot?.()?.data??{}}_getComponentAttrMap(){return this.component.attr?.list?.()??this.component.getSnapshot?.()?.attr??{}}_resolveLoopItems(e,i){if(!e)return[];if(/^\d+$/.test(String(e))){let s=parseInt(e,10);return Array.from({length:Math.max(0,s)},(n,c)=>({_index:c}))}let t=g(i,e);return Array.isArray(t)?t:typeof t=="number"?Array.from({length:Math.max(0,t)},(s,n)=>({_index:n})):[]}_createItemScope(e,i,t){let s=t||this._getComponentData();return typeof e=="object"&&e!==null?{...s,...e,item:e,_index:i}:{...s,value:e,item:e,_index:i}}_mount(){this.container.replaceChildren(),this.liveMap.clear(),this.liveNodes.clear(),this._loopBindings=[];let e;try{e=typeof this.component.layers?.tree=="function"?this.component.layers.tree():w(this.component.layers?.list?.()??this.component.getSnapshot?.()?.layers)}catch(t){this._log("warn","tree() failed, falling back to simple parse",t);let s=this.component.getSnapshot?.()?.layers??"";e=w(s)}Array.isArray(e)||(e=[]);let i=this._getComponentData();for(let t of e)this._mountLayerNode(this.container,t,i);this._applyRootVariant(),this._syncRegistryStyles(),this._log("mount",`mounted ${this.liveMap.size} semantic keys, ${this._loopBindings.length} loops`)}_mountLayerNode(e,i,t){if(i.repeator){let n=this._resolveLoopItems(i.repeator,t),c=[];for(let a=0;a<n.length;a++){let r=this._createItemScope(n[a],a,t),h=this._createSingleElement(i,r,a);e.appendChild(h),c.push(h)}let o=null;typeof document.createComment=="function"&&(o=document.createComment(`wdl-loop:${i.repeator}`),e.appendChild(o)),this._loopBindings.push({parentEl:e,node:i,repeator:i.repeator,elements:c,anchor:o});return}let s=this._createSingleElement(i,t);e.appendChild(s)}_createSingleElement(e,i,t){let s=(e.tag||"div").toLowerCase(),n=p(e.semanticId||e.id||""),c=document.createElement(s);n&&(c.classList.add(n),c.setAttribute("wdl-comp",n),this._registerNode(n,c));let o=t!==void 0?t:i?._index;if(o!==void 0){let a=String(o);c.setAttribute("data-wdl-index",a),c.dataset&&(c.dataset.wdlIndex=a)}if(this._applyNodeAttrs(c,e,i),Array.isArray(e.children))for(let a of e.children)this._mountLayerNode(c,a,i);return c}_applyNodeAttrs(e,i,t){let s=this._getComponentAttrMap(),n=p(i.semanticId||i.id||""),c=(i.tag||"div").toLowerCase(),o=s[c]||{},a=n?s["."+n]||{}:{},r=n?s[n]||{}:{},h={...o,...a,...r},d=f(h,t);this._applyPropsToElement(e,n,d)}_applyPropsToElement(e,i,t){if(!(!t||typeof t!="object")){if(t.text!==void 0&&(e.textContent=String(t.text)),t.html!==void 0&&(e.innerHTML=String(t.html)),t.class!==void 0){let s=String(t.class).trim();e.className=i?s?`${i} ${s}`:i:s}for(let[s,n]of Object.entries(t))if(!N.has(s)){if(s==="style"&&n&&typeof n=="object"){Object.assign(e.style,n);continue}n==null?e.removeAttribute(s):e.setAttribute(s,String(n))}}}_bindStateEvents(){let e=this.component;if(typeof e.on!="function"){this._log("warn","component has no .on() \u2014 events will not be applied");return}let i=s=>this._onStateEvent(s),t=["layers:change","attr:change","data:change","variant:change","registry:change"];for(let s of t){let n=e.on(s,i);typeof n=="function"?this._unsubs.push(n):this._unsubs.push(()=>e.off?.(s,i))}}_onStateEvent(e){if(!(!e||!e.type))switch(this._log("event",e.type,e.action,e.targetId,e.payload),e.type){case"layers:change":this._handleLayers(e);break;case"attr:change":this._handleAttr(e);break;case"data:change":this._handleData(e);break;case"variant:change":this._handleVariant(e);break;case"registry:change":this._handleRegistry(e);break;default:this._log("warn","unknown event type",e.type)}}_handleLayers(e){let{action:i,targetId:t,payload:s}=e,n=p(t),c=this._getComponentData();switch(i){case"set":{this._mount();break}case"append":{let o=this.getNode(n);if(!o){this._log("warn",`append: parent "${n}" not in liveMap \u2014 remounting`),this._mount();return}let a=m(s);this._mountLayerNode(o,a,c),this._log("op",`append <${a.tag}.${a.semanticId}> \u2192 #${n}`);break}case"prepend":{let o=this.getNode(n);if(!o){this._log("warn",`prepend: parent "${n}" not in liveMap \u2014 remounting`),this._mount();return}let a=m(s),r=this._createSingleElement(a,c);o.insertBefore(r,o.firstChild),this._log("op",`prepend <${a.tag}.${a.semanticId}> \u2192 #${n}`);break}case"before":case"after":{let o=this.getNode(n);if(!o||!o.parentNode){this._log("warn",`${i}: target "${n}" missing \u2014 remounting`),this._mount();return}let a=m(s),r=this._createSingleElement(a,c);i==="before"?o.parentNode.insertBefore(r,o):o.parentNode.insertBefore(r,o.nextSibling),this._log("op",`${i} <${a.tag}.${a.semanticId}> relative to #${n}`);break}case"wrap":{let o=this.getNode(n);if(!o||!o.parentNode){this._log("warn",`wrap: target "${n}" missing \u2014 remounting`),this._mount();return}let a=m(s),r=this._createSingleElement(a,c);o.parentNode.insertBefore(r,o),r.appendChild(o),this._log("op",`wrap #${n} with <${a.tag}.${a.semanticId}>`);break}case"unwrap":{let o=this.getNode(n);if(!o||!o.parentNode){this._log("warn",`unwrap: target "${n}" missing \u2014 remounting`),this._mount();return}let a=o.parentNode;for(;o.firstChild;)a.insertBefore(o.firstChild,o);this._unregisterElementHierarchy(o),o.remove(),this._log("op",`unwrap #${n}`);break}case"move":{let o=this.getNode(n),{targetSemanticId:a,position:r}=s||{},h=p(a),d=this.getNode(h);if(!o||!d){this._log("warn",`move: source "${n}" or target "${h}" missing \u2014 remounting`),this._mount();return}r==="before"?d.parentNode?.insertBefore(o,d):r==="after"?d.parentNode?.insertBefore(o,d.nextSibling):d.appendChild(o),this._log("op",`move #${n} -> ${r} #${h}`);break}case"remove":{let o=this.getLiveNodes(n);if(o.length===0){this._log("warn",`remove: #${n} not in liveMap`);return}for(let a of o)this._unregisterElementHierarchy(a),a.remove();this._loopBindings=this._loopBindings.filter(a=>a.node.semanticId!==n),this._log("op",`remove #${n}`);break}case"update":{let o=this.getNode(n);if(!o){this._log("warn",`update: #${n} missing \u2014 remounting`),this._mount();return}let a=s||{};if(a.tag&&a.tag.toLowerCase()!==o.tagName.toLowerCase()){let r=document.createElement(String(a.tag).toLowerCase());for(let d of o.attributes)r.setAttribute(d.name,d.value);for(;o.firstChild;)r.appendChild(o.firstChild);o.parentNode?.replaceChild(r,o),this._unregisterNode(n,o);let h=a.semanticId?p(a.semanticId):n;a.semanticId&&h!==n&&(r.classList.remove(n),r.classList.add(h),r.setAttribute("wdl-comp",h)),this._registerNode(h,r)}else if(a.semanticId&&p(a.semanticId)!==n){let r=p(a.semanticId);o.classList.remove(n),o.classList.add(r),o.setAttribute("wdl-comp",r),this._unregisterNode(n,o),this._registerNode(r,o)}this._log("op",`update #${n}`,a);break}default:this._log("warn",`layers: unknown action "${i}" \u2014 remounting`),this._mount()}}_handleAttr(e){let{action:i,targetId:t,payload:s}=e,n=p(t);if(i==="set"||i==="update"){let c=this.getLiveNodes(n);if(c.length===0){this._log("warn",`attr: #${n} not in liveMap`);return}let o=this._getComponentData();for(let a of c){let r=a.getAttribute("data-wdl-index"),h=o;if(r!=null){let u=parseInt(r,10),v=this._findLoopForElement(a);if(v){let _=g(o,v.repeator);Array.isArray(_)&&_[u]!==void 0?h=this._createItemScope(_[u],u,o):h={...o,_index:u}}else h={...o,_index:u}}let d=f(s||{},h);this._applyPropsToElement(a,n,d)}this._log("op",`attr.${i} #${n}`,s);return}if(i==="remove"){let c=this.getLiveNodes(n);if(c.length===0)return;let o=s;for(let a of c)o==null||o===""?(a.textContent="",a.className=n):o==="text"?a.textContent="":o==="class"?a.className=n:o==="html"?a.innerHTML="":a.removeAttribute(o);this._log("op",`attr.remove ${o||"all"} from #${n}`)}}_applyAttrs(e,i){let t=this.getLiveNodes(e);if(t.length===0){this._log("warn",`attr: #${e} not in liveMap`);return}let s=this._getComponentData();for(let n of t){let c=n.getAttribute("data-wdl-index"),o=s;if(c!=null){let r=parseInt(c,10),h=this._findLoopForElement(n);if(h){let d=g(s,h.repeator);Array.isArray(d)&&d[r]!==void 0?o=this._createItemScope(d[r],r,s):o={...s,_index:r}}}let a=f(i||{},o);this._applyPropsToElement(n,e,a)}}_findLoopForElement(e){return this._loopBindings.find(i=>i.elements.includes(e))||null}_handleData(e){let{action:i,targetId:t,payload:s}=e,n=t||"",c=this._getComponentData();if(this._reconcileLoops(n,c),this._reconcileStaticDataBindings(n,c),typeof this.onDataBind=="function")try{this.onDataBind(this.container,n,i==="remove"?void 0:s)}catch(o){this._log("warn","onDataBind error",o)}this._log("op",`data.${i} ${n}`,i==="remove"?void 0:s)}_reconcileLoops(e,i){for(let t of this._loopBindings){if(!(!e||t.repeator===e||e.startsWith(t.repeator+".")||t.repeator.startsWith(e+".")))continue;let n=this._resolveLoopItems(t.repeator,i),c=n.length,o=t.elements.length,a=Math.min(o,c);for(let r=0;r<a;r++){let h=t.elements[r],d=this._createItemScope(n[r],r,i);h.setAttribute("data-wdl-index",String(r)),h.dataset&&(h.dataset.wdlIndex=String(r)),this._updateElementSubtree(h,t.node,d,r)}if(c>o)for(let r=o;r<c;r++){let h=this._createItemScope(n[r],r,i),d=this._createSingleElement(t.node,h,r);if(t.anchor&&t.anchor.parentNode===t.parentEl)t.parentEl.insertBefore(d,t.anchor);else if(t.elements.length>0){let u=t.elements[t.elements.length-1];t.parentEl.insertBefore(d,u.nextSibling)}else t.parentEl.appendChild(d);t.elements.push(d)}if(c<o)for(let r=o-1;r>=c;r--){let h=t.elements[r];this._unregisterElementHierarchy(h),h.remove(),t.elements.pop()}}}_updateElementSubtree(e,i,t,s){if(this._applyNodeAttrs(e,i,t),Array.isArray(i.children)&&Array.isArray(e.children)){let n=0;for(let c of i.children)if(c.repeator){let o=this._loopBindings.find(a=>a.parentEl===e&&a.node===c);o&&this._reconcileLoops(o.repeator,t)}else e.children[n]&&(this._updateElementSubtree(e.children[n],c,t,s),n++)}}_reconcileStaticDataBindings(e,i){let t=this._getComponentAttrMap();for(let[s,n]of Object.entries(t)){let c=p(s),o=JSON.stringify(n);if(!o.includes("${")&&!o.includes("{{")||e&&!o.includes(e))continue;let a=this.getLiveNodes(c);for(let r of a){if(r.hasAttribute("data-wdl-index")||this._findLoopForElement(r))continue;let h=f(n,i);this._applyPropsToElement(r,c,h)}}}_handleVariant(e){let{targetId:i,payload:t}=e,s=p(i)||this._rootSemanticId(),n=this.getNode(s);if(!n){let c=this._rootSemanticId(),o=c?this.getNode(c):null;o&&(t?o.dataset.variant=String(t):delete o.dataset.variant,this._log("op",`variant \u2192 ${t||"(none)"} on #${c}`));return}t?n.dataset.variant=String(t):delete n.dataset.variant,this._log("op",`variant \u2192 ${t||"(none)"} on #${s}`)}_applyRootVariant(){let e=this._getComponentAttrMap(),i=this._rootSemanticId();if(!i)return;let t="."+i,s=e[t]?.["data-variant"]??e["."]?.["data-variant"]??null;if(s&&this.liveMap.has(i)){let n=this.getNode(i);n&&n.dataset&&(n.dataset.variant=String(s))}}_rootSemanticId(){for(let[i,t]of this.liveMap)if(t.parentNode===this.container)return i;let e=this.liveMap.keys().next();return e.done?"":e.value}_handleRegistry(e){this._syncRegistryStyles(),this._log("op",`registry.${e.action}`)}_syncRegistryStyles(){if(!this.styleTarget)return;let e=this.component.registry?.get?.()??this.component.getSnapshot?.()?.registry??null,i=this.component.id||this.component.getSnapshot?.()?.id||"comp";if(this._styleEl||(this._styleEl=document.createElement("style"),this._styleEl.setAttribute("data-wdl-dom",i),this.styleTarget.appendChild(this._styleEl)),!e){this._styleEl.textContent="";return}let t=Array.isArray(e.rules)?e.rules:[],s=[];if(e.vars&&typeof e.vars=="object"){let n=Object.entries(e.vars).map(([c,o])=>`--${c}: ${o};`).join(" ");n&&s.push(`:root, [wdl-comp] { ${n} }`)}for(let n of t){if(!n||!n.selector)continue;let c=typeof n.css=="string"?n.css:n.css&&typeof n.css=="object"?Object.entries(n.css).map(([r,h])=>`${$(r)}: ${h};`).join(" "):"";if(!c)continue;let o=n.selector.startsWith("&")?n.selector.replace("&",`[wdl-comp="${i}"]`):n.selector,a=n.media?`@media ${n.media} { ${o} { ${c} } }`:`${o} { ${c} }`;s.push(a)}this._styleEl.textContent=s.join(`
+`)}_log(e,...i){if(!this.debug&&e!=="warn")return;let t=`[wdl-dom:${e}]`;e==="warn"?console.warn(t,...i):console.log(t,...i)}};function $(l){return String(l).replace(/[A-Z]/g,e=>"-"+e.toLowerCase())}function E(l){return new y(l)}var A=E;export{y as WdlDom,E as createWdlDom,A as default,p as normalizeId,m as parseLayerToken,w as parseLayersSimple,f as resolveAll,g as resolvePath,S as resolveStr};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ruledwdl/dom",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Native DOM runtime for @ruledwdl/state with surgical element updates driven by state events.",
   "main": "src/index.js",
   "type": "module",

package/src/index.js

@@ -6,9 +6,9 @@
  * No innerHTML on updates.
  *
  * State events handled (from @ruledwdl/state):
- *   layers:change   actions: set | append | before | after | wrap | remove | update
+ *   layers:change   actions: set | append | prepend | before | after | wrap | unwrap | move | remove | update
  *   attr:change     actions: set | update | remove
- *   data:change     actions: set | remove          (optional data-* / text binding)
+ *   data:change     actions: set | update | remove (surgical loop child reconciliation & item-scoped binding)
  *   variant:change  actions: set
  *   registry:change actions: set | update | addRule | removeRule
  *
@@ -23,59 +23,109 @@
  *   }
  *
  * Usage:
- *   import { createWdlDom } from './wdl-dom.js';
+ *   import { createWdlDom } from '@ruledwdl/dom';
  *   // or: import { ComponentManager } from '@ruledwdl/state';
  *
- *   const hero = manager.create('hero', { layers: '...', attr: {...} });
+ *   const comp = manager.create('pricing-card', {
+ *     layers: 'ul.features > li.feature*features',
+ *     attr: { '.feature': { text: '${text}' } },
+ *     data: { features: [{ text: 'First' }, { text: 'Second' }] }
+ *   });
  *   const dom = createWdlDom({
  *     container: document.getElementById('app'),
- *     component: hero,          // ComponentState instance
- *     // optional:
- *     // onDataBind: (el, path, value) => { ... },
- *     // styleTarget: document.head,
+ *     component: comp
  *   });
  *
- *   // later: hero.attr.set('title', { text: 'Hi' });  // → surgical update
+ *   // later: comp.data.set('features', [{ text: 'Updated' }]); // → surgical row reconciliation
  *   // destroy: dom.destroy();
  */
 
 // ---------------------------------------------------------------------------
-// Helpers
+// Helpers & Data Resolvers
 // ---------------------------------------------------------------------------
 
-const ATTR_SKIP = new Set(['text', 'class', 'html']);
+const ATTR_SKIP = new Set(['text', 'class', 'html', 'alpine', 'htmx', 'attr-ref']);
+
+/**
+ * Resolve dot-notated path on an object (e.g. "user.name" or "text")
+ */
+export function resolvePath(obj, path) {
+  if (!path || obj == null) return obj ?? '';
+  return String(path).split('.').reduce((a, k) => (a != null ? a[k] : ''), obj) ?? '';
+}
+
+/**
+ * Resolve template strings with ${path} or {{path}} expressions
+ */
+export function resolveStr(str, data) {
+  if (typeof str !== 'string') return str;
+  return str
+    .replace(/\$\{([\w.]+)\}/g, (_, p) => {
+      const val = resolvePath(data, p);
+      return val != null ? String(val) : '';
+    })
+    .replace(/\{\{([\w.]+)\}\}/g, (_, p) => {
+      const val = resolvePath(data, p);
+      return val != null ? String(val) : '';
+    });
+}
+
+/**
+ * Deeply resolve string templates within objects/arrays
+ */
+export function resolveAll(obj, data) {
+  if (obj == null) return obj;
+  if (typeof obj === 'function') return '';
+  if (typeof obj === 'string') return resolveStr(obj, data);
+  if (Array.isArray(obj)) return obj.map((v) => resolveAll(v, data));
+  if (typeof obj === 'object') {
+    return Object.fromEntries(
+      Object.entries(obj).map(([k, v]) => [k, resolveAll(v, data)])
+    );
+  }
+  return obj;
+}
 
 /**
- * Parse a single layer token: "button.cta" | "div" | "h1.title"
- * @returns {{ tag: string, semanticId: string }}
+ * Parse a single layer token: "button.cta" | "li.feature*features" | "div.card*3"
+ * @returns {{ tag: string, semanticId: string, repeator: string | null }}
  */
-function parseLayerToken(expr) {
+export function parseLayerToken(expr) {
   if (typeof expr !== 'string') {
     if (expr && typeof expr === 'object') {
       return {
         tag: String(expr.tag || 'div').toLowerCase(),
         semanticId: String(expr.semanticId || expr.id || '').replace(/^\./, ''),
+        repeator: expr.repeator || expr.loopKey || null,
       };
     }
     throw new Error('[wdl-dom] invalid layer expression');
   }
   const trimmed = expr.trim();
-  const m = trimmed.match(/^([a-zA-Z][a-zA-Z0-9_-]*)(?:\.([a-zA-Z0-9_-]+))?$/);
+  let str = trimmed;
+  let repeator = null;
+  const multIdx = str.indexOf('*');
+  if (multIdx !== -1) {
+    repeator = str.slice(multIdx + 1);
+    str = str.slice(0, multIdx);
+  }
+  const m = str.match(/^([a-zA-Z][a-zA-Z0-9_-]*)(?:\.([a-zA-Z0-9_-]+))?$/);
   if (!m) {
     // fallback: treat whole string as tag
-    return { tag: trimmed.toLowerCase() || 'div', semanticId: '' };
+    return { tag: str.toLowerCase() || 'div', semanticId: '', repeator };
   }
   return {
     tag: m[1].toLowerCase(),
     semanticId: (m[2] || '').replace(/^\./, ''),
+    repeator,
   };
 }
 
 /**
- * Very small layers string → tree (supports > and + only).
+ * Simple layers string → tree parser (supports >, +, <, <*N, <@N, and *repeator).
  * For full WDL grammar prefer tree from component.layers.tree().
  */
-function parseLayersSimple(str) {
+export function parseLayersSimple(str) {
   if (Array.isArray(str)) return structuredClone(str);
   if (typeof str !== 'string' || !str.trim()) return [];
 
@@ -87,20 +137,57 @@ function parseLayersSimple(str) {
 
   while (i < str.length) {
     const ch = str[i];
-    if (/\s/.test(ch)) { i++; continue; }
+    if (/\s/.test(ch)) {
+      i++;
+      continue;
+    }
     if (ch === '>') {
       const last = top().children[top().children.length - 1];
       if (last) stack.push(last);
       i++;
       continue;
     }
-    if (ch === '+') { i++; continue; }
+    if (ch === '+') {
+      i++;
+      continue;
+    }
     if (ch === '<') {
       i++;
-      if (stack.length > 1) stack.pop();
+      if (i < str.length && str[i] === '*') {
+        i++;
+        let numStr = '';
+        while (i < str.length && /\d/.test(str[i])) {
+          numStr += str[i++];
+        }
+        const count = numStr ? parseInt(numStr, 10) : 1;
+        for (let k = 0; k < count; k++) {
+          if (stack.length > 1) stack.pop();
+        }
+      } else if (i < str.length && str[i] === '@') {
+        i++;
+        let numStr = '';
+        while (i < str.length && /\d/.test(str[i])) {
+          numStr += str[i++];
+        }
+        const targetDepth = numStr ? parseInt(numStr, 10) : 0;
+        const targetStackLen = targetDepth + 1;
+        while (stack.length > targetStackLen && stack.length > 1) {
+          stack.pop();
+        }
+      } else {
+        let count = 1;
+        while (i < str.length && str[i] === '<') {
+          count++;
+          i++;
+        }
+        for (let k = 0; k < count; k++) {
+          if (stack.length > 1) stack.pop();
+        }
+      }
       continue;
     }
-    // element token
+
+    // Element token
     let tag = '';
     while (i < str.length && /[a-zA-Z0-9_-]/.test(str[i])) tag += str[i++];
     let semanticId = '';
@@ -108,12 +195,24 @@ function parseLayersSimple(str) {
       i++;
       while (i < str.length && /[a-zA-Z0-9_-]/.test(str[i])) semanticId += str[i++];
     }
-    top().children.push({ tag: tag.toLowerCase() || 'div', semanticId, children: [] });
+    let repeator = null;
+    if (str[i] === '*') {
+      i++;
+      let rep = '';
+      while (i < str.length && /[a-zA-Z0-9_.]/.test(str[i])) rep += str[i++];
+      if (rep) repeator = rep;
+    }
+    top().children.push({
+      tag: tag.toLowerCase() || 'div',
+      semanticId,
+      repeator,
+      children: [],
+    });
   }
   return root.children;
 }
 
-function normalizeId(id) {
+export function normalizeId(id) {
   if (id == null) return '';
   return String(id).replace(/^\./, '');
 }
@@ -126,7 +225,7 @@ export class WdlDom {
   /**
    * @param {object} options
    * @param {HTMLElement|string} options.container
-   * @param {object} options.component   ComponentState instance (has .on, .layers, .attr, .getSnapshot)
+   * @param {object} options.component   ComponentState instance (has .on, .layers, .attr, .data, .getSnapshot)
    * @param {(el: HTMLElement, path: string, value: any) => void} [options.onDataBind]
    * @param {HTMLElement|Document} [options.styleTarget=document.head]
    * @param {boolean} [options.debug=false]
@@ -154,9 +253,18 @@ export class WdlDom {
     this.styleTarget = styleTarget;
     this.debug = debug;
 
-    /** @type {Map<string, HTMLElement>} semanticId → element */
+    /** @type {Map<string, HTMLElement>} semanticId → first live element (backward compatible) */
     this.liveMap = new Map();
 
+    /** @type {Map<string, HTMLElement[]>} semanticId → all live elements */
+    this.liveNodes = new Map();
+
+    /**
+     * Active loop bindings for surgical reconciliation
+     * @type {Array<{ parentEl: HTMLElement, node: any, repeator: string, elements: HTMLElement[], anchor: any }>}
+     */
+    this._loopBindings = [];
+
     /** @type {Array<() => void>} */
     this._unsubs = [];
 
@@ -176,25 +284,131 @@ export class WdlDom {
     this._mount();
   }
 
-  /** Current live map (read-only view) */
+  /** Current live map of first elements (read-only view) */
   getLiveMap() {
     return new Map(this.liveMap);
   }
 
+  /** Get all live elements matching a semantic ID */
+  getLiveNodes(semanticId) {
+    const id = normalizeId(semanticId);
+    return [...(this.liveNodes.get(id) || [])];
+  }
+
+  /** Get single element by semantic ID and optional index */
+  getNode(semanticId, index = 0) {
+    const list = this.getLiveNodes(semanticId);
+    return list[index] || null;
+  }
+
   /** Clean up listeners and DOM */
   destroy() {
     this._unsubs.forEach((u) => {
-      try { u(); } catch (_) {}
+      try {
+        u();
+      } catch (_) {}
     });
     this._unsubs = [];
     this.container.replaceChildren();
     this.liveMap.clear();
+    this.liveNodes.clear();
+    this._loopBindings = [];
     if (this._styleEl && this._styleEl.parentNode) {
       this._styleEl.parentNode.removeChild(this._styleEl);
     }
     this._styleEl = null;
   }
 
+  // -----------------------------------------------------------------------
+  // Node Registry Management
+  // -----------------------------------------------------------------------
+
+  _registerNode(id, el) {
+    if (!id) return;
+    const norm = normalizeId(id);
+    if (!this.liveNodes.has(norm)) {
+      this.liveNodes.set(norm, []);
+    }
+    const list = this.liveNodes.get(norm);
+    if (!list.includes(el)) {
+      list.push(el);
+    }
+    this.liveMap.set(norm, list[0]);
+  }
+
+  _unregisterNode(id, el) {
+    if (!id) return;
+    const norm = normalizeId(id);
+    if (this.liveNodes.has(norm)) {
+      const list = this.liveNodes.get(norm);
+      const idx = list.indexOf(el);
+      if (idx !== -1) list.splice(idx, 1);
+      if (list.length === 0) {
+        this.liveNodes.delete(norm);
+        this.liveMap.delete(norm);
+      } else {
+        this.liveMap.set(norm, list[0]);
+      }
+    } else {
+      this.liveMap.delete(norm);
+    }
+  }
+
+  _unregisterElementHierarchy(el) {
+    if (!el) return;
+    const compId = el.getAttribute?.('wdl-comp');
+    if (compId) {
+      this._unregisterNode(compId, el);
+    }
+    if (Array.isArray(el.children)) {
+      for (const child of el.children) {
+        this._unregisterElementHierarchy(child);
+      }
+    }
+  }
+
+  // -----------------------------------------------------------------------
+  // Data and Scope Helpers
+  // -----------------------------------------------------------------------
+
+  _getComponentData() {
+    return (
+      this.component.data?.get?.() ??
+      this.component.getSnapshot?.()?.data ??
+      {}
+    );
+  }
+
+  _getComponentAttrMap() {
+    return (
+      this.component.attr?.list?.() ??
+      this.component.getSnapshot?.()?.attr ??
+      {}
+    );
+  }
+
+  _resolveLoopItems(repeator, dataScope) {
+    if (!repeator) return [];
+    if (/^\d+$/.test(String(repeator))) {
+      const count = parseInt(repeator, 10);
+      return Array.from({ length: Math.max(0, count) }, (_, idx) => ({ _index: idx }));
+    }
+    const resolved = resolvePath(dataScope, repeator);
+    if (Array.isArray(resolved)) return resolved;
+    if (typeof resolved === 'number') {
+      return Array.from({ length: Math.max(0, resolved) }, (_, idx) => ({ _index: idx }));
+    }
+    return [];
+  }
+
+  _createItemScope(item, index, baseData) {
+    const data = baseData || this._getComponentData();
+    if (typeof item === 'object' && item !== null) {
+      return { ...data, ...item, item, _index: index };
+    }
+    return { ...data, value: item, item, _index: index };
+  }
+
   // -----------------------------------------------------------------------
   // Initial mount
   // -----------------------------------------------------------------------
@@ -202,12 +416,18 @@ export class WdlDom {
   _mount() {
     this.container.replaceChildren();
     this.liveMap.clear();
+    this.liveNodes.clear();
+    this._loopBindings = [];
 
     let tree;
     try {
-      tree = typeof this.component.layers?.tree === 'function'
-        ? this.component.layers.tree()
-        : parseLayersSimple(this.component.layers?.list?.() ?? this.component.getSnapshot?.()?.layers);
+      tree =
+        typeof this.component.layers?.tree === 'function'
+          ? this.component.layers.tree()
+          : parseLayersSimple(
+              this.component.layers?.list?.() ??
+                this.component.getSnapshot?.()?.layers
+            );
     } catch (e) {
       this._log('warn', 'tree() failed, falling back to simple parse', e);
       const layers = this.component.getSnapshot?.()?.layers ?? '';
@@ -216,18 +436,10 @@ export class WdlDom {
 
     if (!Array.isArray(tree)) tree = [];
 
-    for (const node of tree) {
-      const el = this._createElementFromNode(node);
-      this.container.appendChild(el);
-    }
+    const compData = this._getComponentData();
 
-    // Apply all current attributes
-    const attrMap =
-      this.component.attr?.list?.() ??
-      this.component.getSnapshot?.()?.attr ??
-      {};
-    for (const [sel, props] of Object.entries(attrMap)) {
-      this._applyAttrs(normalizeId(sel), props);
+    for (const node of tree) {
+      this._mountLayerNode(this.container, node, compData);
     }
 
     // Apply variant if present on root
@@ -236,13 +448,50 @@ export class WdlDom {
     // Registry styles
     this._syncRegistryStyles();
 
-    this._log('mount', `mounted ${this.liveMap.size} nodes`);
+    this._log('mount', `mounted ${this.liveMap.size} semantic keys, ${this._loopBindings.length} loops`);
   }
 
   /**
-   * @param {{ tag: string, semanticId?: string, id?: string, children?: any[] }} node
+   * Mount a layer node into a parent container/element.
+   * Handles loop expansion vs single element mounting.
    */
-  _createElementFromNode(node) {
+  _mountLayerNode(parentEl, node, dataScope) {
+    if (node.repeator) {
+      const items = this._resolveLoopItems(node.repeator, dataScope);
+      const elements = [];
+
+      for (let i = 0; i < items.length; i++) {
+        const itemScope = this._createItemScope(items[i], i, dataScope);
+        const el = this._createSingleElement(node, itemScope, i);
+        parentEl.appendChild(el);
+        elements.push(el);
+      }
+
+      // Create comment anchor to keep track of loop boundary
+      let anchor = null;
+      if (typeof document.createComment === 'function') {
+        anchor = document.createComment(`wdl-loop:${node.repeator}`);
+        parentEl.appendChild(anchor);
+      }
+
+      this._loopBindings.push({
+        parentEl,
+        node,
+        repeator: node.repeator,
+        elements,
+        anchor,
+      });
+      return;
+    }
+
+    const el = this._createSingleElement(node, dataScope);
+    parentEl.appendChild(el);
+  }
+
+  /**
+   * Create a single DOM element for a layer node with item scope and attributes.
+   */
+  _createSingleElement(node, dataScope, index) {
     const tag = (node.tag || 'div').toLowerCase();
     const id = normalizeId(node.semanticId || node.id || '');
     const el = document.createElement(tag);
@@ -250,17 +499,77 @@ export class WdlDom {
     if (id) {
       el.classList.add(id);
       el.setAttribute('wdl-comp', id);
-      this.liveMap.set(id, el);
+      this._registerNode(id, el);
+    }
+
+    const effectiveIndex = index !== undefined ? index : dataScope?._index;
+    if (effectiveIndex !== undefined) {
+      const idxStr = String(effectiveIndex);
+      el.setAttribute('data-wdl-index', idxStr);
+      if (el.dataset) el.dataset.wdlIndex = idxStr;
     }
 
+    this._applyNodeAttrs(el, node, dataScope);
+
     if (Array.isArray(node.children)) {
       for (const child of node.children) {
-        el.appendChild(this._createElementFromNode(child));
+        this._mountLayerNode(el, child, dataScope);
       }
     }
+
     return el;
   }
 
+  /**
+   * Apply matching attributes to an element using resolved dataScope.
+   */
+  _applyNodeAttrs(el, node, dataScope) {
+    const attrMap = this._getComponentAttrMap();
+    const id = normalizeId(node.semanticId || node.id || '');
+    const tag = (node.tag || 'div').toLowerCase();
+
+    // Priority: tag fallback -> semanticId (.id or id)
+    const tagAttrs = attrMap[tag] || {};
+    const idDotAttrs = id ? attrMap['.' + id] || {} : {};
+    const idAttrs = id ? attrMap[id] || {} : {};
+
+    const merged = { ...tagAttrs, ...idDotAttrs, ...idAttrs };
+    const resolved = resolveAll(merged, dataScope);
+
+    this._applyPropsToElement(el, id, resolved);
+  }
+
+  /**
+   * Directly apply a resolved properties dictionary onto an element.
+   */
+  _applyPropsToElement(el, id, props) {
+    if (!props || typeof props !== 'object') return;
+
+    if (props.text !== undefined) {
+      el.textContent = String(props.text);
+    }
+    if (props.html !== undefined) {
+      el.innerHTML = String(props.html);
+    }
+    if (props.class !== undefined) {
+      const extra = String(props.class).trim();
+      el.className = id ? (extra ? `${id} ${extra}` : id) : extra;
+    }
+
+    for (const [key, value] of Object.entries(props)) {
+      if (ATTR_SKIP.has(key)) continue;
+      if (key === 'style' && value && typeof value === 'object') {
+        Object.assign(el.style, value);
+        continue;
+      }
+      if (value == null) {
+        el.removeAttribute(key);
+      } else {
+        el.setAttribute(key, String(value));
+      }
+    }
+  }
+
   // -----------------------------------------------------------------------
   // State event binding
   // -----------------------------------------------------------------------
@@ -274,7 +583,6 @@ export class WdlDom {
 
     const handler = (event) => this._onStateEvent(event);
 
-    // All events documented by @ruledwdl/state
     const types = [
       'layers:change',
       'attr:change',
@@ -285,7 +593,6 @@ export class WdlDom {
 
     for (const type of types) {
       const off = c.on(type, handler);
-      // state.on may return unsubscribe fn or nothing
       if (typeof off === 'function') this._unsubs.push(off);
       else this._unsubs.push(() => c.off?.(type, handler));
     }
@@ -321,68 +628,54 @@ export class WdlDom {
 
   // -----------------------------------------------------------------------
   // layers:change
-  // actions: set | append | before | after | wrap | remove | update
+  // actions: set | append | prepend | before | after | wrap | unwrap | move | remove | update
   // -----------------------------------------------------------------------
 
   _handleLayers(event) {
     const { action, targetId, payload } = event;
     const id = normalizeId(targetId);
+    const compData = this._getComponentData();
 
     switch (action) {
       case 'set': {
-        // Full layers replacement → remount
         this._mount();
         break;
       }
       case 'append': {
-        // payload = layer expression (string or node-like)
-        const parentEl = this.liveMap.get(id);
+        const parentEl = this.getNode(id);
         if (!parentEl) {
           this._log('warn', `append: parent "${id}" not in liveMap — remounting`);
           this._mount();
           return;
         }
         const token = parseLayerToken(payload);
-        const el = this._createElementFromNode({
-          tag: token.tag,
-          semanticId: token.semanticId,
-          children: [],
-        });
-        parentEl.appendChild(el);
+        this._mountLayerNode(parentEl, token, compData);
         this._log('op', `append <${token.tag}.${token.semanticId}> → #${id}`);
         break;
       }
       case 'prepend': {
-        const parentEl = this.liveMap.get(id);
+        const parentEl = this.getNode(id);
         if (!parentEl) {
           this._log('warn', `prepend: parent "${id}" not in liveMap — remounting`);
           this._mount();
           return;
         }
         const token = parseLayerToken(payload);
-        const el = this._createElementFromNode({
-          tag: token.tag,
-          semanticId: token.semanticId,
-          children: [],
-        });
+        const el = this._createSingleElement(token, compData);
         parentEl.insertBefore(el, parentEl.firstChild);
         this._log('op', `prepend <${token.tag}.${token.semanticId}> → #${id}`);
         break;
       }
       case 'before':
       case 'after': {
-        const targetEl = this.liveMap.get(id);
+        const targetEl = this.getNode(id);
         if (!targetEl || !targetEl.parentNode) {
           this._log('warn', `${action}: target "${id}" missing — remounting`);
           this._mount();
           return;
         }
         const token = parseLayerToken(payload);
-        const el = this._createElementFromNode({
-          tag: token.tag,
-          semanticId: token.semanticId,
-          children: [],
-        });
+        const el = this._createSingleElement(token, compData);
         if (action === 'before') {
           targetEl.parentNode.insertBefore(el, targetEl);
         } else {
@@ -392,26 +685,21 @@ export class WdlDom {
         break;
       }
       case 'wrap': {
-        // payload = wrapper layer expression
-        const targetEl = this.liveMap.get(id);
+        const targetEl = this.getNode(id);
         if (!targetEl || !targetEl.parentNode) {
           this._log('warn', `wrap: target "${id}" missing — remounting`);
           this._mount();
           return;
         }
         const token = parseLayerToken(payload);
-        const wrapper = this._createElementFromNode({
-          tag: token.tag,
-          semanticId: token.semanticId,
-          children: [],
-        });
+        const wrapper = this._createSingleElement(token, compData);
         targetEl.parentNode.insertBefore(wrapper, targetEl);
         wrapper.appendChild(targetEl);
         this._log('op', `wrap #${id} with <${token.tag}.${token.semanticId}>`);
         break;
       }
       case 'unwrap': {
-        const wrapperEl = this.liveMap.get(id);
+        const wrapperEl = this.getNode(id);
         if (!wrapperEl || !wrapperEl.parentNode) {
           this._log('warn', `unwrap: target "${id}" missing — remounting`);
           this._mount();
@@ -421,16 +709,16 @@ export class WdlDom {
         while (wrapperEl.firstChild) {
           parent.insertBefore(wrapperEl.firstChild, wrapperEl);
         }
+        this._unregisterElementHierarchy(wrapperEl);
         wrapperEl.remove();
-        this.liveMap.delete(id);
         this._log('op', `unwrap #${id}`);
         break;
       }
       case 'move': {
-        const sourceEl = this.liveMap.get(id);
+        const sourceEl = this.getNode(id);
         const { targetSemanticId, position } = payload || {};
         const targetId = normalizeId(targetSemanticId);
-        const targetEl = this.liveMap.get(targetId);
+        const targetEl = this.getNode(targetId);
 
         if (!sourceEl || !targetEl) {
           this._log('warn', `move: source "${id}" or target "${targetId}" missing — remounting`);
@@ -449,23 +737,22 @@ export class WdlDom {
         break;
       }
       case 'remove': {
-        const el = this.liveMap.get(id);
-        if (!el) {
+        const nodes = this.getLiveNodes(id);
+        if (nodes.length === 0) {
           this._log('warn', `remove: #${id} not in liveMap`);
           return;
         }
-        // Remove descendants from liveMap first
-        for (const [sid, node] of [...this.liveMap]) {
-          if (sid !== id && el.contains(node)) this.liveMap.delete(sid);
+        for (const el of nodes) {
+          this._unregisterElementHierarchy(el);
+          el.remove();
         }
-        el.remove();
-        this.liveMap.delete(id);
+        // Also cleanup loop bindings associated with this semantic ID
+        this._loopBindings = this._loopBindings.filter((l) => l.node.semanticId !== id);
         this._log('op', `remove #${id}`);
         break;
       }
       case 'update': {
-        // payload = { tag?, semanticId? }
-        const el = this.liveMap.get(id);
+        const el = this.getNode(id);
         if (!el) {
           this._log('warn', `update: #${id} missing — remounting`);
           this._mount();
@@ -473,28 +760,25 @@ export class WdlDom {
         }
         const patch = payload || {};
         if (patch.tag && patch.tag.toLowerCase() !== el.tagName.toLowerCase()) {
-          // Tag change requires recreate
           const next = document.createElement(String(patch.tag).toLowerCase());
-          // copy attributes & children
           for (const attr of el.attributes) next.setAttribute(attr.name, attr.value);
           while (el.firstChild) next.appendChild(el.firstChild);
           el.parentNode?.replaceChild(next, el);
-          this.liveMap.set(id, next);
-          if (patch.semanticId && normalizeId(patch.semanticId) !== id) {
-            const newId = normalizeId(patch.semanticId);
+          this._unregisterNode(id, el);
+          const finalId = patch.semanticId ? normalizeId(patch.semanticId) : id;
+          if (patch.semanticId && finalId !== id) {
             next.classList.remove(id);
-            next.classList.add(newId);
-            next.setAttribute('wdl-comp', newId);
-            this.liveMap.delete(id);
-            this.liveMap.set(newId, next);
+            next.classList.add(finalId);
+            next.setAttribute('wdl-comp', finalId);
           }
+          this._registerNode(finalId, next);
         } else if (patch.semanticId && normalizeId(patch.semanticId) !== id) {
           const newId = normalizeId(patch.semanticId);
           el.classList.remove(id);
           el.classList.add(newId);
           el.setAttribute('wdl-comp', newId);
-          this.liveMap.delete(id);
-          this.liveMap.set(newId, el);
+          this._unregisterNode(id, el);
+          this._registerNode(newId, el);
         }
         this._log('op', `update #${id}`, patch);
         break;
@@ -515,89 +799,114 @@ export class WdlDom {
     const id = normalizeId(targetId);
 
     if (action === 'set' || action === 'update') {
-      // payload = full attrs object (set) or patch (update)
-      this._applyAttrs(id, payload || {});
+      const nodes = this.getLiveNodes(id);
+      if (nodes.length === 0) {
+        this._log('warn', `attr: #${id} not in liveMap`);
+        return;
+      }
+      const compData = this._getComponentData();
+      for (const el of nodes) {
+        const idx = el.getAttribute('data-wdl-index');
+        let scope = compData;
+        if (idx !== null && idx !== undefined) {
+          const indexNum = parseInt(idx, 10);
+          const loop = this._findLoopForElement(el);
+          if (loop) {
+            const items = resolvePath(compData, loop.repeator);
+            if (Array.isArray(items) && items[indexNum] !== undefined) {
+              scope = this._createItemScope(items[indexNum], indexNum, compData);
+            } else {
+              scope = { ...compData, _index: indexNum };
+            }
+          } else {
+            scope = { ...compData, _index: indexNum };
+          }
+        }
+        const resolved = resolveAll(payload || {}, scope);
+        this._applyPropsToElement(el, id, resolved);
+      }
       this._log('op', `attr.${action} #${id}`, payload);
       return;
     }
 
     if (action === 'remove') {
-      const el = this.liveMap.get(id);
-      if (!el) return;
-      const attrKey = payload; // may be undefined → remove whole entry
-      if (attrKey == null || attrKey === '') {
-        el.textContent = '';
-        // keep semantic class
-        el.className = id;
-        this._log('op', `attr.remove entire #${id}`);
-      } else if (attrKey === 'text') {
-        el.textContent = '';
-        this._log('op', `attr.remove text from #${id}`);
-      } else if (attrKey === 'class') {
-        el.className = id;
-        this._log('op', `attr.remove class from #${id}`);
-      } else if (attrKey === 'html') {
-        el.innerHTML = '';
-        this._log('op', `attr.remove html from #${id}`);
-      } else {
-        el.removeAttribute(attrKey);
-        this._log('op', `attr.remove ${attrKey} from #${id}`);
+      const nodes = this.getLiveNodes(id);
+      if (nodes.length === 0) return;
+      const attrKey = payload;
+      for (const el of nodes) {
+        if (attrKey == null || attrKey === '') {
+          el.textContent = '';
+          el.className = id;
+        } else if (attrKey === 'text') {
+          el.textContent = '';
+        } else if (attrKey === 'class') {
+          el.className = id;
+        } else if (attrKey === 'html') {
+          el.innerHTML = '';
+        } else {
+          el.removeAttribute(attrKey);
+        }
       }
+      this._log('op', `attr.remove ${attrKey || 'all'} from #${id}`);
     }
   }
 
-  /**
-   * Apply attribute object onto live element.
-   * Supports: text, class, html, data-*, style object, arbitrary attrs.
-   */
   _applyAttrs(id, props) {
-    if (!props || typeof props !== 'object') return;
-    const el = this.liveMap.get(id);
-    if (!el) {
+    const nodes = this.getLiveNodes(id);
+    if (nodes.length === 0) {
       this._log('warn', `attr: #${id} not in liveMap`);
       return;
     }
-
-    if (props.text !== undefined) {
-      el.textContent = String(props.text);
-    }
-    if (props.html !== undefined) {
-      el.innerHTML = String(props.html);
-    }
-    if (props.class !== undefined) {
-      const extra = String(props.class).trim();
-      el.className = extra ? `${id} ${extra}` : id;
-    }
-
-    for (const [key, value] of Object.entries(props)) {
-      if (ATTR_SKIP.has(key)) continue;
-      if (key === 'style' && value && typeof value === 'object') {
-        Object.assign(el.style, value);
-        continue;
-      }
-      if (value == null) {
-        el.removeAttribute(key);
-      } else {
-        el.setAttribute(key, String(value));
+    const compData = this._getComponentData();
+    for (const el of nodes) {
+      const idx = el.getAttribute('data-wdl-index');
+      let scope = compData;
+      if (idx !== null && idx !== undefined) {
+        const indexNum = parseInt(idx, 10);
+        const loop = this._findLoopForElement(el);
+        if (loop) {
+          const items = resolvePath(compData, loop.repeator);
+          if (Array.isArray(items) && items[indexNum] !== undefined) {
+            scope = this._createItemScope(items[indexNum], indexNum, compData);
+          } else {
+            scope = { ...compData, _index: indexNum };
+          }
+        }
       }
+      const resolved = resolveAll(props || {}, scope);
+      this._applyPropsToElement(el, id, resolved);
     }
   }
 
+  _findLoopForElement(el) {
+    return this._loopBindings.find((l) => l.elements.includes(el)) || null;
+  }
+
   // -----------------------------------------------------------------------
   // data:change
-  // actions: set | remove
-  // Optional: onDataBind callback for custom binding
+  // actions: set | update | remove
+  // Surgically reconciles repeated loop items & per-item template bindings
   // -----------------------------------------------------------------------
 
   _handleData(event) {
     const { action, targetId, payload } = event;
-    // targetId is the path (e.g. "user.name"), payload is the value
     const path = targetId || '';
+    const compData = this._getComponentData();
+
+    // 1. Surgically reconcile all matching loop bindings
+    this._reconcileLoops(path, compData);
+
+    // 2. Reconcile non-loop elements bound to this path or full data
+    this._reconcileStaticDataBindings(path, compData);
+
+    // 3. Optional onDataBind callback hook for external consumers
     if (typeof this.onDataBind === 'function') {
-      // Let consumer decide how data maps to DOM
-      // We pass the root container + path + value
       try {
-        this.onDataBind(this.container, path, action === 'remove' ? undefined : payload);
+        this.onDataBind(
+          this.container,
+          path,
+          action === 'remove' ? undefined : payload
+        );
       } catch (e) {
         this._log('warn', 'onDataBind error', e);
       }
@@ -605,6 +914,113 @@ export class WdlDom {
     this._log('op', `data.${action} ${path}`, action === 'remove' ? undefined : payload);
   }
 
+  /**
+   * Reconcile loop children surgically on data change.
+   */
+  _reconcileLoops(path, compData) {
+    for (const loop of this._loopBindings) {
+      const matches =
+        !path ||
+        loop.repeator === path ||
+        path.startsWith(loop.repeator + '.') ||
+        loop.repeator.startsWith(path + '.');
+
+      if (!matches) continue;
+
+      const items = this._resolveLoopItems(loop.repeator, compData);
+      const nextCount = items.length;
+      const prevCount = loop.elements.length;
+      const minCount = Math.min(prevCount, nextCount);
+
+      // 1. Update retained rows in place
+      for (let i = 0; i < minCount; i++) {
+        const el = loop.elements[i];
+        const itemScope = this._createItemScope(items[i], i, compData);
+        el.setAttribute('data-wdl-index', String(i));
+        if (el.dataset) el.dataset.wdlIndex = String(i);
+        this._updateElementSubtree(el, loop.node, itemScope, i);
+      }
+
+      // 2. Insert newly added rows
+      if (nextCount > prevCount) {
+        for (let i = prevCount; i < nextCount; i++) {
+          const itemScope = this._createItemScope(items[i], i, compData);
+          const newEl = this._createSingleElement(loop.node, itemScope, i);
+          if (loop.anchor && loop.anchor.parentNode === loop.parentEl) {
+            loop.parentEl.insertBefore(newEl, loop.anchor);
+          } else if (loop.elements.length > 0) {
+            const lastEl = loop.elements[loop.elements.length - 1];
+            loop.parentEl.insertBefore(newEl, lastEl.nextSibling);
+          } else {
+            loop.parentEl.appendChild(newEl);
+          }
+          loop.elements.push(newEl);
+        }
+      }
+
+      // 3. Remove deleted rows
+      if (nextCount < prevCount) {
+        for (let i = prevCount - 1; i >= nextCount; i--) {
+          const delEl = loop.elements[i];
+          this._unregisterElementHierarchy(delEl);
+          delEl.remove();
+          loop.elements.pop();
+        }
+      }
+    }
+  }
+
+  /**
+   * Update an element and its non-loop children with new itemScope.
+   */
+  _updateElementSubtree(el, node, itemScope, index) {
+    this._applyNodeAttrs(el, node, itemScope);
+
+    if (Array.isArray(node.children) && Array.isArray(el.children)) {
+      let childElIdx = 0;
+      for (const childNode of node.children) {
+        if (childNode.repeator) {
+          // Nested loop: find its binding and reconcile
+          const childLoop = this._loopBindings.find(
+            (l) => l.parentEl === el && l.node === childNode
+          );
+          if (childLoop) {
+            this._reconcileLoops(childLoop.repeator, itemScope);
+          }
+        } else if (el.children[childElIdx]) {
+          this._updateElementSubtree(
+            el.children[childElIdx],
+            childNode,
+            itemScope,
+            index
+          );
+          childElIdx++;
+        }
+      }
+    }
+  }
+
+  /**
+   * Update non-loop live elements that reference template data bindings.
+   */
+  _reconcileStaticDataBindings(path, compData) {
+    const attrMap = this._getComponentAttrMap();
+    for (const [key, props] of Object.entries(attrMap)) {
+      const id = normalizeId(key);
+      const str = JSON.stringify(props);
+      if (!str.includes('${') && !str.includes('{{')) continue;
+      if (path && !str.includes(path)) continue;
+
+      const nodes = this.getLiveNodes(id);
+      for (const el of nodes) {
+        // Skip elements governed by loops as they are reconciled separately
+        if (el.hasAttribute('data-wdl-index') || this._findLoopForElement(el)) continue;
+        const resolved = resolveAll(props, compData);
+        this._applyPropsToElement(el, id, resolved);
+      }
+    }
+  }
+
   // -----------------------------------------------------------------------
   // variant:change
   // action: set   targetId = semanticId (or component id)  payload = variantName
@@ -613,11 +1029,10 @@ export class WdlDom {
   _handleVariant(event) {
     const { targetId, payload } = event;
     const id = normalizeId(targetId) || this._rootSemanticId();
-    const el = this.liveMap.get(id);
+    const el = this.getNode(id);
     if (!el) {
-      // try root
       const rootId = this._rootSemanticId();
-      const rootEl = rootId ? this.liveMap.get(rootId) : null;
+      const rootEl = rootId ? this.getNode(rootId) : null;
       if (rootEl) {
         if (payload) rootEl.dataset.variant = String(payload);
         else delete rootEl.dataset.variant;
@@ -631,11 +1046,7 @@ export class WdlDom {
   }
 
   _applyRootVariant() {
-    // Read current variant from attr if present
-    const attr =
-      this.component.attr?.list?.() ??
-      this.component.getSnapshot?.()?.attr ??
-      {};
+    const attr = this._getComponentAttrMap();
     const rootId = this._rootSemanticId();
     if (!rootId) return;
     const rootKey = '.' + rootId;
@@ -644,12 +1055,12 @@ export class WdlDom {
       attr['.']?.['data-variant'] ??
       null;
     if (variant && this.liveMap.has(rootId)) {
-      this.liveMap.get(rootId).dataset.variant = String(variant);
+      const el = this.getNode(rootId);
+      if (el && el.dataset) el.dataset.variant = String(variant);
     }
   }
 
   _rootSemanticId() {
-    // First entry in liveMap that is a direct child of container, or first key
     for (const [id, el] of this.liveMap) {
       if (el.parentNode === this.container) return id;
     }
@@ -751,3 +1162,4 @@ export function createWdlDom(options) {
 }
 
 export default createWdlDom;
+