@symbo.ls/element 3.14.0

package/src/create.js

@@ -0,0 +1,1705 @@
+'use strict'
+
+import { createStore, isStore } from '@symbo.ls/signal'
+import { createEffect, batch } from '@symbo.ls/signal'
+import { cacheNode, detectTag } from './cache.js'
+import { REGISTRY, LIFECYCLE_EVENTS } from './registry.js'
+import { registerEvent } from './delegate.js'
+import { applyExtends } from './extends.js'
+import { addMethods } from './methods.js'
+import { dispose } from './dispose.js'
+import { replaceLiteralsWithObjectFields, exec } from '@symbo.ls/utils'
+import { runPluginHook } from '@symbo.ls/utils/function.js'
+import { applyStateMethods } from '@symbo.ls/state'
+import { CSS_PROPS_REGISTRY } from 'css-in-props/src/props'
+import { DEFAULT_CSS_PROPERTIES_LIST } from 'css-in-props/src/props/defaults'
+import { css as atomicCss } from '@symbo.ls/css'
+import { pushConfig, popConfig } from '@symbo.ls/scratch'
+import { checkAttributeByTagName, applyAttrTransforms } from 'attrs-in-props'
+
+let _uniqId = 1
+
+// Detect onXxx event handler pattern
+function isEventHandler(key) {
+  return key.length > 2 &&
+    key.charCodeAt(0) === 111 && // 'o'
+    key.charCodeAt(1) === 110 && // 'n'
+    key.charCodeAt(2) >= 65 && key.charCodeAt(2) <= 90 // A-Z
+}
+
+// Extract event name from onXxx key (onClick -> click, onMouseDown -> mouseDown)
+function eventNameFrom(key) {
+  return key.charAt(2).toLowerCase() + key.slice(3)
+}
+
+// Convert camelCase event name to lowercase DOM event (mouseDown -> mousedown)
+function toDomEventName(name) {
+  return name.toLowerCase()
+}
+
+// Deep merge for child component definitions — override wins, but nested objects are recursively merged
+function deepMergeChild(base, override) {
+  const result = { ...base }
+  for (const key in override) {
+    const baseVal = result[key]
+    const overVal = override[key]
+    if (baseVal && overVal &&
+        typeof baseVal === 'object' && typeof overVal === 'object' &&
+        !Array.isArray(baseVal) && !Array.isArray(overVal) &&
+        typeof baseVal !== 'function' && typeof overVal !== 'function') {
+      result[key] = deepMergeChild(baseVal, overVal)
+    } else {
+      result[key] = overVal
+    }
+  }
+  return result
+}
+
+// --- Create Element ---
+
+export function create(definition, parent, key, options = {}, attachOptions) {
+  // Normalize definition
+  if (definition == null || definition === false) return null
+  if (typeof definition === 'string' || typeof definition === 'number') {
+    definition = { text: definition }
+  }
+
+
+  const element = Object.create(null)
+  element.key = key || definition.key || `_${_uniqId++}`
+  element.parent = parent || null
+  element.context = definition.context || parent?.context || options.context || {}
+  if (!element.context.__create) element.context.__create = create
+
+  // Internal ref
+  const ref = element.__ref = {
+    __if: true,
+    __children: [],
+    __exec: {},
+    __effects: [],
+    __eventCleanup: [],
+    root: parent?.__ref?.root || element,
+    path: parent?.__ref?.path ? [...parent.__ref.path, element.key] : [element.key]
+  }
+
+  // Auto-extend from key name: Key_suffix -> extends Key component
+  if (key && !definition.extends && !definition.extend) {
+    const underscoreIdx = key.indexOf('_')
+    if (underscoreIdx > 0) {
+      const baseName = key.substring(0, underscoreIdx)
+      const components = element.context?.components
+      if (components && (components[baseName] || components['smbls.' + baseName])) {
+        definition = { extends: baseName, ...definition }
+      }
+    }
+  }
+
+  // Merge extends chain
+  applyExtends(element, definition, options)
+
+  // Copy properties from definition — deep merge child overrides, shallow merge known keys, override rest
+  const MERGE_KEYS = new Set(['childProps', 'attr', 'style', 'scope', 'data'])
+
+  // Capture props set by the extends chain before they get merged flat
+  const inheritedProps = (element.props && typeof element.props === 'object')
+    ? element.props
+    : null
+
+  for (const prop in definition) {
+    if (prop === 'parent' || prop === 'node' || prop === '__ref' || prop === 'extends' || prop === 'context' || prop === 'props') continue
+    const val = definition[prop]
+    const existing = element[prop]
+    const bothObjects = existing && val &&
+        typeof existing === 'object' && typeof val === 'object' &&
+        !Array.isArray(existing) && !Array.isArray(val) &&
+        typeof existing !== 'function' && typeof val !== 'function'
+    if (bothObjects && (prop.charCodeAt(0) >= 65 && prop.charCodeAt(0) <= 90)) {
+      // Deep merge for uppercase child component overrides (definition wins)
+      element[prop] = deepMergeChild(existing, val)
+    } else if (bothObjects && MERGE_KEYS.has(prop)) {
+      element[prop] = { ...existing, ...val }
+    } else {
+      element[prop] = val
+    }
+  }
+
+  // Helper to merge a props-like object onto element directly
+  function mergePropsOntoElement (propsObj) {
+    for (const prop in propsObj) {
+      const val = propsObj[prop]
+      const existing = element[prop]
+      const bothObjects = existing && val &&
+          typeof existing === 'object' && typeof val === 'object' &&
+          !Array.isArray(existing) && !Array.isArray(val) &&
+          typeof existing !== 'function' && typeof val !== 'function'
+      if (bothObjects && (prop.charCodeAt(0) >= 65 && prop.charCodeAt(0) <= 90)) {
+        element[prop] = deepMergeChild(existing, val)
+      } else if (bothObjects && MERGE_KEYS.has(prop)) {
+        element[prop] = { ...existing, ...val }
+      } else {
+        element[prop] = val
+      }
+    }
+  }
+
+  // Merge inherited props from extends chain flat onto element
+  if (inheritedProps) mergePropsOntoElement(inheritedProps)
+
+  // Merge definition.props flat onto element (definition overrides inherited)
+  if (definition.props && typeof definition.props === 'object') {
+    mergePropsOntoElement(definition.props)
+  }
+
+  if (definition.data !== undefined) element.data = definition.data
+
+  if (definition.classlist !== undefined) element.classlist = definition.classlist
+  if (definition.text !== undefined) element.text = definition.text
+  if (definition.html !== undefined) element.html = definition.html
+  if (definition.scope !== undefined) {
+    element.scope = parent?.scope
+      ? Object.assign(Object.create(parent.scope), definition.scope)
+      : definition.scope
+  } else if (parent?.scope) {
+    element.scope = Object.create(parent.scope)
+  }
+  if (definition.if !== undefined) element.if = definition.if
+
+
+  // Add methods
+  addMethods(element)
+
+  // Create state (reactive store)
+  createElementState(element, parent, definition)
+
+  // Evaluate `if` condition
+  if (element.if != null) {
+    const ifResult = typeof element.if === 'function'
+      ? element.if(element, element.state, element.context)
+      : element.if
+    ref.__if = !!ifResult
+  }
+
+  if (!ref.__if) {
+    if (parent) parent[element.key] = element
+    // Register only the `if` effect so the element can appear later when the
+    // condition becomes true. Other effects will be registered inside the
+    // effect's first-time activation branch.
+    if (typeof definition.if === 'function') {
+      registerEffects(element, { if: definition.if })
+    }
+    return element
+  } else if (typeof definition.if === 'function') {
+    // Element starts visible — mark as initialized so the `if` effect's
+    // re-activation branch (false→true) doesn't re-run full creation.
+    ref.__ifInitialized = true
+  }
+
+  // Detect tag
+  if (!element.tag) element.tag = detectTag(element)
+
+  // Fire onInit
+  triggerLifecycle('Init', element, options)
+
+  // Create DOM node
+  const node = element.node = cacheNode(element)
+  if (!node) return element
+
+  triggerLifecycle('AttachNode', element, options)
+
+  // Set key as data attribute for dev debugging
+  if (node.setAttribute && element.key) {
+    node.setAttribute('data-key', element.key)
+  }
+
+  // Stamp data-smbls-app on the app's root node so its design-system CSS
+  // variables (scoped to `[data-smbls-app="<key>"]`) cascade through its
+  // subtree without leaking to sibling apps in the same document.
+  if (
+    node.setAttribute &&
+    element.context?.scopeSelector &&
+    element.context.scopeSelector !== ':root' &&
+    element.context.key &&
+    element.key === element.context.key
+  ) {
+    node.setAttribute('data-smbls-app', element.context.key)
+  }
+
+  // Apply id attribute
+  if (element.id && node.setAttribute) {
+    node.id = element.id
+  }
+
+  // Register reactive effects for dynamic properties
+  registerEffects(element, definition)
+
+  // Apply static mixins (text, html, style, attr, data, classlist)
+  applyStaticMixins(element)
+
+  // Apply attrs-in-props (src, href, etc. from element properties)
+  applyAttrsInProps(element)
+
+  // Register events (onXxx handlers directly on element)
+  registerEvents(element, options)
+
+  // FB-render-runtime: previously a thrown error inside createChildren()
+  // would silently abort the element-mount walk, leaving the page with a
+  // 0-child root div and no console output. Wrap with try/catch + log so
+  // operators can see what crashed.
+  try {
+    createChildren(element, options)
+  } catch (childErr) {
+    if (typeof console !== 'undefined' && console.error) {
+      const elPath = element.__ref?.path?.join('.') || element.key || '<root>'
+      console.error(
+        `[smbls] createChildren failed at ${elPath}:`,
+        childErr?.message || childErr,
+        childErr?.stack ? '\n' + childErr.stack.split('\n').slice(0, 6).join('\n') : ''
+      )
+    }
+  }
+
+  // Assign node to DOM
+  assignNode(element, parent, attachOptions)
+
+  // Track in parent
+  if (parent) {
+    parent[element.key] = element
+    if (parent.__ref?.__children) {
+      if (!parent.__ref.__children.includes(element.key)) {
+        parent.__ref.__children.push(element.key)
+      }
+    }
+  }
+
+  // Evaluate extends-inherited html functions (e.g. Svg component).
+  // Guard: if the function returns a function (e.g. an extended component
+  // forwards `value` which itself is a function getter), skip setting
+  // innerHTML — otherwise we'd serialize the function source into the DOM
+  // (visible as `(el, s) => …` text inside textareas / inputs).
+  if (typeof element.html === 'function' && element.node && !element.node.innerHTML) {
+    try {
+      const val = element.html(element, element.state, element.context)
+      if (val != null && typeof val !== 'function') element.node.innerHTML = val
+    } catch (e) { /* skip if html function errors */ }
+  }
+
+  triggerLifecycle('Create', element, options)
+  triggerLifecycle('Complete', element, options)
+  triggerLifecycle('Render', element, options)
+  triggerLifecycle('RenderRouter', element, options)
+
+  // Start onFrame loop if defined
+  if (typeof element.onFrame === 'function') {
+    const frameHandler = element.onFrame
+    const frameDsConfig = element.context?.designSystem
+    const tick = () => {
+      if (!element.node || !element.node.isConnected) return
+      if (frameDsConfig) pushConfig(frameDsConfig)
+      try { frameHandler(element, element.state, element.context) } catch (e) { console.error('[DOMQL] onFrame error:', e) }
+      finally {
+        if (frameDsConfig) popConfig()
+      }
+      requestAnimationFrame(tick)
+    }
+    requestAnimationFrame(tick)
+  }
+
+  return element
+}
+
+// --- State Creation ---
+
+function createElementState(element, parent, definition) {
+  // Prefer the local definition's `state`, but fall back to anything that
+  // applyExtends already merged onto element.state from the extends chain.
+  // Without this fallback, a component like `{ extends: 'Dashboard' }` where
+  // Dashboard defines `state: { useJson: true }` would lose its state because
+  // the local definition has no `state` field, and we'd silently inherit
+  // parent state instead.
+  const stateDef = definition.state !== undefined
+    ? definition.state
+    : (element.state && !isStore(element.state) ? element.state : undefined)
+
+  if (stateDef === undefined || stateDef === null) {
+    if (parent?.state) {
+      element.state = parent.state
+      applyStateMethods(element, element.state)
+    } else if (element.context?.state) {
+      // Root element: use prepared state from context
+      const ctxState = element.context.state
+      const stateData = { ...ctxState }
+
+      // Merge polyglot translations for active language into root state
+      const poly = element.context?.polyglot
+      if (poly?.translations) {
+        const lang = ctxState.lang || poly.defaultLang || 'en'
+        const langT = poly.translations[lang]
+        if (langT && typeof langT === 'object') {
+          for (const k in langT) {
+            if (stateData[k] === undefined) stateData[k] = langT[k]
+          }
+        }
+        // Also merge top-level translation keys (skip language code keys)
+        const langs = new Set(poly.languages || [])
+        for (const k in poly.translations) {
+          if (!langs.has(k) && stateData[k] === undefined) {
+            stateData[k] = poly.translations[k]
+          }
+        }
+      }
+
+      element.state = isStore(stateData) ? stateData : createStore(stateData)
+      element.state.__element = element
+      element.state.root = element.state
+      applyStateMethods(element, element.state)
+    } else {
+      element.state = {}
+      // Self-reference root so consumer code can rely on `s.root` always
+      // being defined, matching the root-element branch above. Non-enumerable
+      // so Object.keys / for…in / JSON.stringify skip it (this is a plain
+      // object — unlike a store proxy, which hides root from ownKeys via
+      // the proxy trap).
+      Object.defineProperty(element.state, 'root', {
+        value: element.state, enumerable: false, configurable: true, writable: true
+      })
+      applyStateMethods(element, element.state)
+    }
+    return
+  }
+
+  if (typeof stateDef === 'string') {
+    element.state = resolveStatePath(stateDef, parent)
+    // Propagate root reference to plain sub-state objects (v3 compat: s.root).
+    // Final fallback to self-ref keeps `s.root` defined even for orphan
+    // string-bound state (no parent, or parent has no state).
+    if (element.state && typeof element.state === 'object' && !isStore(element.state)) {
+      const rootRef = parent?.state?.root || parent?.state || element.state
+      Object.defineProperty(element.state, 'root', {
+        value: rootRef, enumerable: false, configurable: true, writable: true
+      })
+    }
+    applyStateMethods(element, element.state)
+    return
+  }
+
+  if (typeof stateDef === 'function') {
+    const resolved = stateDef(element, parent?.state)
+    element.state = createStore(resolved || {})
+  } else {
+    element.state = createStore({ ...stateDef })
+  }
+
+  element.state.__element = element
+  if (parent?.state) {
+    element.state.parent = parent.state
+    // Inherit root reference from parent chain
+    element.state.root = parent.state.root || parent.state
+  } else {
+    // Root element: self-reference for v3 compat (state.root === state)
+    element.state.root = element.state
+  }
+  applyStateMethods(element, element.state)
+}
+
+function resolvePath(obj, path) {
+  if (!path) return obj
+  const parts = path.split('/')
+  let result = obj
+  for (const part of parts) {
+    if (result === undefined || result === null) return {}
+    result = result[part]
+  }
+  return result ?? {}
+}
+
+function resolveStatePath(path, parent) {
+  if (!parent) return {}
+  if (path === '.') return parent.state || {}
+  if (path.startsWith('../')) {
+    const key = path.slice(3)
+    return key ? resolvePath(parent.state, key) : parent.state ?? {}
+  }
+  if (path.startsWith('~/')) {
+    const rootState = parent.state?.root || parent.state
+    const key = path.slice(2)
+    return key ? resolvePath(rootState, key) : rootState ?? {}
+  }
+  // Check parent state first (supports nested paths like 'product/0')
+  if (parent.state?.[path] !== undefined) return parent.state[path]
+  const nested = resolvePath(parent.state, path)
+  if (nested !== undefined && nested !== null && Object.keys(nested).length > 0) return nested
+
+  // Fall back to polyglot translations for current language
+  const poly = parent.context?.polyglot
+  if (poly?.translations) {
+    const lang = parent.state?.root?.lang || poly.defaultLang || 'en'
+    const langTranslations = poly.translations[lang]
+    if (langTranslations?.[path] !== undefined) return langTranslations[path]
+    // Check top-level translations
+    if (poly.translations[path] !== undefined) return poly.translations[path]
+  }
+
+  return {}
+}
+
+// --- Reactive Effects ---
+
+function registerEffects(element, definition) {
+  const ref = element.__ref
+
+  // Text effect
+  if (typeof element.text === 'function') {
+    const fn = element.text
+    const effect = createEffect(() => {
+      try {
+        let val = fn(element, element.state, element.context)
+        if (element.node && val != null && typeof val !== 'function' && typeof val !== 'object') {
+          // Resolve {{ }} templates in function return values
+          if (typeof val === 'string' && val.includes('{{')) {
+            val = replaceLiteralsWithObjectFields.call(element, val, element.state)
+          }
+          if (element.tag === 'string') {
+            element.node.nodeValue = val
+          } else {
+            element.node.textContent = val
+          }
+        }
+      } catch (e) { /* text effect may fail before state is populated */ }
+    }, { depth: ref.path.length })
+    ref.__effects.push(effect)
+    ref.__exec.text = fn
+  } else if (typeof element.text === 'string' && element.text.includes('{{')) {
+    const template = element.text
+    const effect = createEffect(() => {
+      const val = replaceLiteralsWithObjectFields.call(element, template, element.state)
+      if (val != null) element.text = val // Update element.text with resolved value
+      if (element.node) {
+        if (element.tag === 'string') {
+          element.node.nodeValue = val ?? ''
+        } else {
+          element.node.textContent = val ?? ''
+        }
+      }
+    }, { depth: ref.path.length })
+    ref.__effects.push(effect)
+    ref.__exec.text = template
+  }
+
+  // Reactive effects for function-valued CSS properties (CSS_PROPS_REGISTRY and DEFAULT_CSS)
+  for (const prop in element) {
+    if (!Object.prototype.hasOwnProperty.call(element, prop)) continue
+    if (typeof element[prop] !== 'function') continue
+    if (REGISTRY.has(prop)) continue
+    if (isEventHandler(prop)) continue
+    if (ref.__exec[prop]) continue
+
+    if (CSS_PROPS_REGISTRY[prop]) {
+      const fn = element[prop]
+      const cssProp = prop
+      const effect = createEffect(() => {
+        // Push this element's design system config so CSS_PROPS_REGISTRY
+        // handlers (which internally call getActiveConfig() for token resolution)
+        // see the right config in multi-app setups (canvas editor vs. iframe project).
+        // The document is on the config, so getActiveDocument() resolves it too.
+        const ds = element.context?.designSystem
+        if (ds) pushConfig(ds)
+        try {
+          const val = fn(element, element.state, element.context)
+          const cssResult = CSS_PROPS_REGISTRY[cssProp](val, element, element.state, element.context)
+          if (cssResult && element.node) {
+            applyStyles(element.node, cssResult)
+          } else if (element.node && (cssProp === 'show' || cssProp === 'hide')) {
+            element.node.style.display = ''
+          }
+        } finally {
+          if (ds) popConfig()
+        }
+      }, { depth: ref.path.length })
+      ref.__effects.push(effect)
+      ref.__exec[prop] = fn
+    } else if (DEFAULT_CSS_PROPERTIES_LIST && DEFAULT_CSS_PROPERTIES_LIST.has(prop)) {
+      const fn = element[prop]
+      const cssProp = prop
+      const effect = createEffect(() => {
+        const ds = element.context?.designSystem
+        if (ds) pushConfig(ds)
+        try {
+          const val = fn(element, element.state, element.context)
+          if (element.node) {
+            if (val != null) applyStyles(element.node, { [cssProp]: val })
+            else element.node.style[cssProp] = ''
+          }
+        } finally {
+          if (ds) popConfig()
+        }
+      }, { depth: ref.path.length })
+      ref.__effects.push(effect)
+      ref.__exec[prop] = fn
+    }
+  }
+
+
+  // HTML effect.
+  // Guard: skip when the html function returns a function (forwarded reactive
+  // getter from an extended component). Avoids serializing the function source
+  // into innerHTML — see same guard in the eager-pass block above.
+  if (typeof definition.html === 'function') {
+    const fn = definition.html
+    const effect = createEffect(() => {
+      const val = fn(element, element.state, element.context)
+      if (element.node && val != null && typeof val !== 'function') {
+        element.node.innerHTML = val
+      }
+    }, { depth: ref.path.length })
+    ref.__effects.push(effect)
+    ref.__exec.html = fn
+  }
+
+  // Value effect — reactively set node.value on input/textarea/select.
+  // Preserves cursor position for the currently focused input so a re-render
+  // mid-typing does not yank the caret to the end.
+  if (typeof definition.value === 'function') {
+    const fn = definition.value
+    const effect = createEffect(() => {
+      try {
+        const val = fn(element, element.state, element.context)
+        if (!element.node || !('value' in element.node)) return
+        const next = (val == null) ? '' : String(val)
+        if (element.node.value === next) return
+        const focused = (typeof document !== 'undefined') && document.activeElement === element.node
+        const selStart = focused && typeof element.node.selectionStart === 'number'
+          ? element.node.selectionStart : null
+        const selEnd = focused && typeof element.node.selectionEnd === 'number'
+          ? element.node.selectionEnd : null
+        element.node.value = next
+        if (focused && selStart != null && selEnd != null) {
+          try { element.node.setSelectionRange(selStart, selEnd) } catch (e) {}
+        }
+      } catch (e) { /* value effect may fail before state is populated */ }
+    }, { depth: ref.path.length })
+    ref.__effects.push(effect)
+    ref.__exec.value = fn
+  }
+
+  // Style effect
+  if (typeof definition.style === 'function') {
+    const fn = definition.style
+    const effect = createEffect(() => {
+      const styles = fn(element, element.state, element.context)
+      applyStyles(element.node, styles)
+    }, { depth: ref.path.length })
+    ref.__effects.push(effect)
+    ref.__exec.style = fn
+  }
+
+  // Attribute effects for function-valued attrs (check element.attr which includes extends)
+  if (element.attr && typeof element.attr === 'object') {
+    for (const attrName in element.attr) {
+      if (typeof element.attr[attrName] === 'function') {
+        const fn = element.attr[attrName]
+        const name = attrName
+        const effect = createEffect(() => {
+          try {
+            const val = fn(element, element.state, element.context)
+            if (element.node?.setAttribute) {
+              if (val == null || val === false) {
+                element.node.removeAttribute(name)
+              } else if (typeof val !== 'function' && typeof val !== 'object') {
+                element.node.setAttribute(name, val === true ? '' : val)
+              }
+            }
+          } catch (e) {
+            // Attr function may fail if element properties aren't ready yet
+          }
+        }, { depth: ref.path.length })
+        ref.__effects.push(effect)
+      }
+    }
+  }
+
+  // If condition effect
+  if (typeof definition.if === 'function') {
+    const fn = definition.if
+    const effect = createEffect(() => {
+      const ifResult = fn(element, element.state, element.context)
+      const wasVisible = ref.__if
+      ref.__if = !!ifResult
+
+      if (wasVisible && !ref.__if && element.node) {
+        element.node.remove()
+      } else if (!wasVisible && ref.__if) {
+        // First-time activation: run the full creation steps that were skipped
+        // when initial `if` was false. This builds the element's node, children,
+        // attrs, and events the first time the condition becomes true.
+        if (!ref.__ifInitialized) {
+          ref.__ifInitialized = true
+          if (!element.tag) element.tag = detectTag(element)
+          triggerLifecycle('Init', element, {})
+          if (!element.node) element.node = cacheNode(element)
+          if (!element.node) return
+          triggerLifecycle('AttachNode', element, {})
+          if (element.node.setAttribute && element.key) {
+            element.node.setAttribute('data-key', element.key)
+          }
+          if (element.id && element.node.setAttribute) {
+            element.node.id = element.id
+          }
+          // Register reactive effects for dynamic props (excluding `if` to avoid recursion)
+          const prevIf = definition.if
+          delete definition.if
+          try { registerEffects(element, definition) } finally { definition.if = prevIf }
+          applyStaticMixins(element)
+          applyAttrsInProps(element)
+          registerEvents(element, {})
+          createChildren(element, {})
+          assignNode(element, element.parent)
+        } else {
+          // Subsequent re-activations: just re-attach existing node
+          if (!element.node) element.node = cacheNode(element)
+          // Find the next sibling in DOMQL tree that has a node, to insert before it
+          const parent = element.parent
+          const parentNode = parent?.node
+          if (parentNode && element.node) {
+            let nextSibNode = null
+            const keys = Object.keys(parent)
+            const myIdx = keys.indexOf(element.key)
+            for (let i = myIdx + 1; i < keys.length; i++) {
+              const sib = parent[keys[i]]
+              if (sib?.node?.parentNode === parentNode) {
+                nextSibNode = sib.node
+                break
+              }
+            }
+            if (nextSibNode) {
+              parentNode.insertBefore(element.node, nextSibNode)
+            } else {
+              parentNode.appendChild(element.node)
+            }
+          } else {
+            assignNode(element, element.parent)
+          }
+          applyStaticMixins(element)
+        }
+      }
+    }, { depth: ref.path.length })
+    ref.__effects.push(effect)
+  }
+
+  // CSS-in-props effects (dynamic CSS properties as functions)
+  for (const prop in element) {
+    if (!Object.prototype.hasOwnProperty.call(element, prop)) continue
+    if (REGISTRY.has(prop)) continue
+    if (typeof element[prop] !== 'function') continue
+
+    // Skip child components (Uppercase)
+    const firstChar = prop.charCodeAt(0)
+    if (firstChar >= 65 && firstChar <= 90) continue
+
+    // Skip onXxx event handlers
+    if (isEventHandler(prop)) continue
+
+    const fn = element[prop]
+    ref.__exec[prop] = fn
+
+    // Reactive effects for function-valued HTML attributes (src, href, etc.)
+    // Skip props already handled as CSS properties
+    const tag = element.tag || 'div'
+    if (checkAttributeByTagName(tag, prop) && !CSS_PROPS_REGISTRY[prop] && !(DEFAULT_CSS_PROPERTIES_LIST && DEFAULT_CSS_PROPERTIES_LIST.has(prop))) {
+      const attrName = prop
+      const effect = createEffect(() => {
+        try {
+          const val = fn(element, element.state, element.context)
+          if (element.node?.setAttribute) {
+            if (val == null || val === false) {
+              element.node.removeAttribute(attrName)
+            } else if (typeof val !== 'function' && typeof val !== 'object') {
+              // Use property setter for src on iframes/media to trigger navigation
+              if (attrName === 'src' && 'src' in element.node) {
+                element.node.src = val
+              } else {
+                element.node.setAttribute(attrName, val === true ? '' : val)
+              }
+            }
+          }
+        } catch (e) { /* attr function may fail before state is populated */ }
+      }, { depth: ref.path.length })
+      ref.__effects.push(effect)
+    }
+  }
+
+  // Reactive conditionals (.prop / !prop blocks)
+  registerConditionalEffects(element)
+}
+
+// --- Static Mixin Application ---
+
+function applyStaticMixins(element) {
+  const { node } = element
+  if (!node) return
+
+  // Text (skip template literals — handled by reactive effect)
+  if (typeof element.text === 'string' && !element.text.includes('{{')) {
+    if (element.tag === 'string') {
+      node.nodeValue = element.text
+    } else {
+      node.textContent = element.text
+    }
+  } else if (typeof element.text === 'number') {
+    node.textContent = element.text
+  }
+
+  // CSS-in-props static transforms (show, hide, padding, flexAlign, etc.)
+  // Conditionals (.prop / !prop) are handled reactively in registerConditionalEffects
+  applyCssInProps(element)
+
+  // HTML
+  if (typeof element.html === 'string') {
+    node.innerHTML = element.html
+  }
+
+  // Static value for input/textarea/select. The reactive effect path
+  // (see registerEffects) handles function-valued `value:` props.
+  if (
+    element.value != null &&
+    typeof element.value !== 'function' &&
+    'value' in node
+  ) {
+    const next = String(element.value)
+    if (node.value !== next) node.value = next
+  }
+
+  // Style
+  if (element.style && typeof element.style === 'object') {
+    applyStyles(node, element.style)
+  }
+
+  // Attributes
+  if (element.attr && typeof element.attr === 'object') {
+    for (const key in element.attr) {
+      const val = element.attr[key]
+      if (typeof val === 'function' || typeof val === 'object') continue
+      if (val == null || val === false) continue
+      if (node.setAttribute) {
+        node.setAttribute(key, val === true ? '' : val)
+      }
+    }
+  }
+
+  // Data attributes
+  if (element.data && typeof element.data === 'object') {
+    for (const key in element.data) {
+      if (node.dataset) node.dataset[key] = element.data[key]
+    }
+  }
+
+  // Classlist
+  if (element.classlist || element.class) {
+    const cls = element.classlist || element.class
+    if (typeof cls === 'string') {
+      cls.split(' ').forEach(c => c && node.classList.add(c))
+    } else if (typeof cls === 'object') {
+      for (const name in cls) {
+        const val = typeof cls[name] === 'function'
+          ? cls[name](element, element.state, element.context)
+          : cls[name]
+        if (val) node.classList.add(typeof val === 'string' ? val : name)
+      }
+    }
+  }
+}
+
+function applyStyles(node, styles) {
+  if (!node || !styles || !node.style) return
+
+  let cssRules = null
+
+  for (const prop in styles) {
+    const val = styles[prop]
+    if (val == null) continue
+
+    // Handle &: selectors — generate CSS rules
+    if (prop.charAt(0) === '&' && typeof val === 'object') {
+      if (!cssRules) cssRules = {}
+      cssRules[prop] = val
+      continue
+    }
+
+    try {
+      const str = String(val)
+      if (str.includes('!important')) {
+        const cssProp = prop.replace(/[A-Z]/g, m => '-' + m.toLowerCase())
+        node.style.setProperty(cssProp, str.replace(/\s*!important\s*$/, ''), 'important')
+      } else {
+        node.style[prop] = val
+      }
+    } catch (e) {
+      // Invalid style value
+    }
+  }
+
+  // Inject CSS rules for &: selectors
+  if (cssRules) {
+    injectScopedCSS(node, cssRules)
+  }
+}
+
+let _scopedStyleId = 0
+
+function injectScopedCSS(node, rules) {
+  const id = `_ds${_scopedStyleId++}`
+  node.classList.add(id)
+
+  const doc = node.ownerDocument
+  let styleEl = doc.querySelector('style[data-smbls-scoped]')
+  if (!styleEl) {
+    styleEl = doc.createElement('style')
+    styleEl.setAttribute('data-smbls-scoped', '')
+    doc.head.appendChild(styleEl)
+  }
+
+  let css = ''
+  for (const selector in rules) {
+    // Replace & with scoped class, and auto-scope unscoped comma-separated parts
+    const scopedClass = '.' + id
+    const resolvedSelector = selector.replace(/&/g, scopedClass)
+      .split(',')
+      .map(s => {
+        const t = s.trim()
+        return t.includes(scopedClass) ? t : scopedClass + t
+      })
+      .join(', ')
+    const val = rules[selector]
+
+    if (typeof val === 'object') {
+      // Check for nested selectors (e.g. '& [dropdown]' inside '&:focus-within')
+      let props = ''
+      let nested = ''
+      for (const k in val) {
+        const v = val[k]
+        if (typeof v === 'object') {
+          const nestedSelector = k.replace(/&/g, '.' + id)
+          const nestedSuffix = ' ' + nestedSelector.replace('.' + id, '')
+          const fullSelector = resolvedSelector.split(', ').map(s => s + nestedSuffix).join(', ')
+          let nestedProps = ''
+          for (const nk in v) {
+            nestedProps += `${nk.replace(/[A-Z]/g, m => '-' + m.toLowerCase())}: ${v[nk]};`
+          }
+          nested += `${fullSelector} { ${nestedProps} }\n`
+        } else {
+          props += `${k.replace(/[A-Z]/g, m => '-' + m.toLowerCase())}: ${v};`
+        }
+      }
+      if (props) css += `${resolvedSelector} { ${props} }\n`
+      if (nested) css += nested
+    }
+  }
+
+  if (css) styleEl.textContent += css
+}
+
+// --- Conditionals ---
+// Reactive `.propName` (truthy) and `!propName` (falsy) blocks.
+//
+// Each conditional becomes its own `createEffect` so signal-driven predicates
+// (state reads inside a function-valued prop) re-fire it. Block values are
+// applied via inline styles (with CSS_PROPS_REGISTRY token resolution) and
+// reverted by clearing the inline keys when the predicate flips off — the
+// static class never bakes in the conditional values, so there is nothing to
+// unmerge on revert.
+//
+// Imperative updates to a non-signal predicate (e.g. `element.update({ isActive })`
+// where `isActive` is a plain element prop, not in state) re-run via
+// `__conditionalRunners`, which `update.js` invokes after applying the prop.
+
+function registerConditionalEffects(element) {
+  const ref = element.__ref
+  ref.__conditionalRunners = []
+
+  for (const key in element) {
+    if (!Object.prototype.hasOwnProperty.call(element, key)) continue
+    const c0 = key.charAt(0)
+    if (c0 !== '.' && c0 !== '!') continue
+
+    const propName = key.slice(1)
+    if (!propName) continue
+
+    const block = element[key]
+    if (!block || typeof block !== 'object') continue
+
+    const negate = c0 === '!'
+    const local = { lastMatch: false, appliedKeys: null }
+
+    const evaluate = () => {
+      if (!element.node) return
+
+      // Resolution order matches css-in-props transformer
+      // (`applyConditionalCaseProps`): element prop → state → context.cases.
+      // Reading `element.state[propName]` inside the effect subscribes to the
+      // signal so state-only predicates re-fire on `state.update`.
+      let resolved
+      const propVal = element[propName]
+      if (propVal === undefined) {
+        if (element.state && propName in element.state) {
+          resolved = element.state[propName]
+        } else {
+          const caseFn = element.context?.cases?.[propName]
+          if (caseFn === undefined) return
+          resolved = typeof caseFn === 'function' ? caseFn.call(element, element) : caseFn
+        }
+      } else if (typeof propVal === 'function') {
+        resolved = propVal(element, element.state, element.context)
+      } else {
+        resolved = propVal
+      }
+
+      const match = negate ? !resolved : !!resolved
+
+      if (match === local.lastMatch) return
+      local.lastMatch = match
+
+      const ds = element.context?.designSystem
+      if (ds) pushConfig(ds)
+      try {
+        if (match) {
+          const styles = {}
+          for (const prop in block) {
+            if (!Object.prototype.hasOwnProperty.call(block, prop)) continue
+            const raw = typeof block[prop] === 'function'
+              ? block[prop](element, element.state, element.context)
+              : block[prop]
+            if (raw == null) continue
+
+            if (CSS_PROPS_REGISTRY[prop]) {
+              const r = CSS_PROPS_REGISTRY[prop](raw, element, element.state, element.context)
+              if (r) {
+                const arr = Array.isArray(r) ? r : [r]
+                for (const o of arr) if (o) Object.assign(styles, o)
+              }
+            } else if (DEFAULT_CSS_PROPERTIES_LIST && DEFAULT_CSS_PROPERTIES_LIST.has(prop)) {
+              styles[prop] = raw
+            }
+          }
+          const keys = Object.keys(styles)
+          if (keys.length) {
+            applyStyles(element.node, styles)
+            local.appliedKeys = keys
+          } else {
+            local.appliedKeys = null
+          }
+        } else if (local.appliedKeys) {
+          for (const k of local.appliedKeys) element.node.style[k] = ''
+          local.appliedKeys = null
+        }
+      } finally {
+        if (ds) popConfig()
+      }
+    }
+
+    ref.__conditionalRunners.push(evaluate)
+
+    const effect = createEffect(evaluate, { depth: ref.path.length })
+    ref.__effects.push(effect)
+  }
+}
+
+// --- CSS-in-props ---
+// Processes element properties through CSS_PROPS_REGISTRY transforms
+
+const __APPLY_CSS_STACK = new WeakSet()
+function applyCssInProps(element) {
+  const { node } = element
+  if (!node) return
+
+  if (__APPLY_CSS_STACK.has(element)) {
+    console.error('[applyCssInProps] re-entry detected for element', element.key, 'prop path:', element.__ref?.path)
+    return
+  }
+  __APPLY_CSS_STACK.add(element)
+
+  const ds = element.context?.designSystem
+  if (ds) pushConfig(ds)
+
+  try {
+  const cssStyles = {}
+  let hasStyles = false
+
+  for (const prop in element) {
+    if (!Object.prototype.hasOwnProperty.call(element, prop)) continue
+    if (typeof element[prop] === 'function') continue
+    if (REGISTRY.has(prop)) continue
+
+    const firstChar = prop.charCodeAt(0)
+    if (firstChar >= 65 && firstChar <= 90) continue
+    if (isEventHandler(prop)) continue
+
+    if (CSS_PROPS_REGISTRY[prop]) {
+      const val = element[prop]
+      const cssResult = CSS_PROPS_REGISTRY[prop](val, element, element.state, element.context)
+      if (cssResult) {
+        if (Array.isArray(cssResult)) {
+          for (const r of cssResult) if (r) Object.assign(cssStyles, r)
+        } else {
+          Object.assign(cssStyles, cssResult)
+        }
+        hasStyles = true
+      }
+    } else if (DEFAULT_CSS_PROPERTIES_LIST && DEFAULT_CSS_PROPERTIES_LIST.has(prop)) {
+      const val = element[prop]
+      if (val != null && typeof val !== 'object') {
+        cssStyles[prop] = val
+        hasStyles = true
+      }
+    } else if (prop.charCodeAt(0) === 45 && prop.charCodeAt(1) === 45) {
+      // CSS custom properties (--var-name): apply as inline style
+      const val = element[prop]
+      if (val != null && typeof val !== 'object') {
+        cssStyles[prop] = val
+        hasStyles = true
+      }
+    } else if (prop.charAt(0) === '@' || prop.charAt(0) === ':') {
+      // Selector-based CSS: @dark, @media, :hover
+      const val = element[prop]
+      if (val && typeof val === 'object') {
+        const resolved = {}
+        for (const k in val) {
+          let v = val[k]
+          // Evaluate function-valued CSS within selector blocks (e.g. @dark background)
+          if (typeof v === 'function') v = v(element, element.state, element.context)
+          if (v == null || typeof v === 'function') continue
+          if (CSS_PROPS_REGISTRY[k]) {
+            const result = CSS_PROPS_REGISTRY[k](v, element, element.state, element.context)
+            if (result) {
+              if (Array.isArray(result)) { for (const r of result) if (r) Object.assign(resolved, r) }
+              else Object.assign(resolved, result)
+            }
+          } else {
+            resolved[k] = v
+          }
+        }
+        if (Object.keys(resolved).length) {
+          // Per-element theme selectors (`@dark`, `@light`, or any custom
+          // scheme `@name`) all compile to a single
+          //   `[data-theme="<scheme>"] &`
+          // rule. The !important marker ensures the themed value wins over
+          // the default (the unconditional property on the same element —
+          // e.g. `background: 'neutral100'`).
+          //
+          // `globalTheme: 'auto'` is handled outside the CSS: `scratch.set`
+          // watches `prefers-color-scheme` and writes `data-theme` on the
+          // scope root to follow OS changes live. That keeps a single CSS
+          // selector pattern — no `@media` duplicates to parse — and lets
+          // custom themes like `@ocean` use the same mechanism.
+          //
+          // We intentionally treat `@dark`/`@light` as theme selectors even
+          // if `designSystem.media.dark` / `.light` is defined — projects
+          // historically mapped them to `[data-theme="…"]` there, and
+          // routing through the media-shortcut branch would emit invalid
+          // `@media [data-theme="…"]` rules.
+          const isThemeSelector = prop.length > 1 && prop.charAt(0) === '@' &&
+            !prop.startsWith('@media') && !prop.startsWith('@keyframes') && !prop.startsWith('@supports') &&
+            (prop === '@dark' || prop === '@light' ||
+              !element.context?.designSystem?.media?.[prop.slice(1)])
+          if (isThemeSelector) {
+            const important = {}
+            for (const rk in resolved) {
+              const rv = resolved[rk]
+              important[rk] = typeof rv === 'string' && !rv.includes('!important') ? rv + ' !important' : rv
+            }
+            const scheme = prop.slice(1)
+            cssStyles[`[data-theme="${scheme}"] &`] = important
+          } else {
+            // Resolve design system media shortcuts (@mobileL -> @media (max-width: 768px))
+            let cssProp = prop
+            if (prop.charAt(0) === '@' && !prop.startsWith('@media') && !prop.startsWith('@keyframes')) {
+              const mediaKey = prop.slice(1)
+              const mediaVal = element.context?.designSystem?.media?.[mediaKey] ||
+                               element.context?.designSystem?.media?.[mediaKey]
+              if (mediaVal) cssProp = `@media ${mediaVal}`
+            }
+            // Separate flat CSS props from nested selector objects
+            const flat = {}
+            for (const rk in resolved) {
+              const rv = resolved[rk]
+              if (rv && typeof rv === 'object' && !Array.isArray(rv)) {
+                // Nested selector (e.g. '> hgroup > h6': { color: 'blue' })
+                // Resolve CSS tokens in nested values
+                const nestedResolved = {}
+                for (const nk in rv) {
+                  if (CSS_PROPS_REGISTRY[nk]) {
+                    const nr = CSS_PROPS_REGISTRY[nk](rv[nk], element, element.state, element.context)
+                    if (nr) {
+                      if (Array.isArray(nr)) { for (const r of nr) if (r) Object.assign(nestedResolved, r) }
+                      else Object.assign(nestedResolved, nr)
+                    }
+                  } else {
+                    nestedResolved[nk] = rv[nk]
+                  }
+                }
+                // Pseudo-selectors attach directly, combinators need space
+                const sep = rk.startsWith(':') ? '' : ' '
+                // Distribute nested selector across comma-separated parts
+                if (cssProp.includes(',')) {
+                  const distributed = cssProp.split(',').map(s => `${s.trim()}${sep}${rk}`).join(', ')
+                  cssStyles[distributed] = nestedResolved
+                } else {
+                  cssStyles[`${cssProp}${sep}${rk}`] = nestedResolved
+                }
+              } else {
+                flat[rk] = rv
+              }
+            }
+            if (Object.keys(flat).length) cssStyles[cssProp] = flat
+          }
+          hasStyles = true
+        }
+        hasStyles = true
+      }
+    }
+  }
+
+  if (hasStyles) {
+    // Document already set by the outer push at the top of applyCssInProps
+
+    // Apply display:none !important as inline style (for show/hide to work reliably)
+    if (cssStyles.display && String(cssStyles.display).includes('!important')) {
+      node.style.setProperty('display', String(cssStyles.display).replace(/\s*!important\s*$/, ''), 'important')
+      delete cssStyles.display
+    }
+
+    const className = atomicCss(cssStyles, null, element.context?.cssPrefix)
+    if (className && node.classList) {
+      className.split(' ').forEach(c => c && node.classList.add(c))
+    }
+
+    // Enforce explicit display when it conflicts with generated display from flow/align
+    // Also handle hide:true / show:false (which set display:none via CSS_PROPS_REGISTRY)
+    const effectiveDisplay = element.display != null && typeof element.display !== 'function'
+      ? element.display
+      : (element.hide === true || element.show === false) ? 'none' : null
+    if (effectiveDisplay != null) {
+      const generatedDisplay = cssStyles.display
+      if (generatedDisplay && generatedDisplay !== effectiveDisplay) {
+        if (effectiveDisplay === 'none') {
+          // For display:none, remove conflicting atomic display classes instead of inline style
+          // (inline style would block conditional show/hide from updating later)
+          const toRemove = []
+          for (const cls of node.classList) {
+            if (cls.startsWith('_d-') && cls !== '_d-none') toRemove.push(cls)
+          }
+          for (const cls of toRemove) node.classList.remove(cls)
+          node.classList.add('_d-none')
+        } else {
+          // For grid/block/inline, inline style is safe
+          node.style.display = element.display
+        }
+      }
+    }
+  }
+  } finally {
+    if (ds) popConfig()
+    __APPLY_CSS_STACK.delete(element)
+  }
+}
+
+// --- Attrs-in-props ---
+// Applies HTML attributes from element properties based on tag
+
+function applyAttrsInProps(element) {
+  const { node } = element
+  if (!node || !node.setAttribute) return
+
+  // Apply attribute transforms (src, href, poster, etc. with file/template resolution)
+  const transformed = applyAttrTransforms(element)
+  for (const attr in transformed) {
+    const val = transformed[attr]
+    if (val != null && val !== false && typeof val !== 'function' && typeof val !== 'object') {
+      node.setAttribute(attr, val === true ? '' : val)
+    }
+  }
+
+  const tag = element.tag || 'div'
+  for (const prop in element) {
+    if (!Object.prototype.hasOwnProperty.call(element, prop)) continue
+    if (typeof element[prop] === 'function') continue
+    if (REGISTRY.has(prop)) continue
+    if (prop === 'on') continue
+    if (transformed[prop] !== undefined) continue
+
+    const firstChar = prop.charCodeAt(0)
+    if (firstChar >= 65 && firstChar <= 90) continue
+    if (isEventHandler(prop)) continue
+
+    // Skip CSS properties — already handled by applyCssInProps via CSS.
+    // Setting design system tokens (e.g. 'A') as SVG/HTML attributes causes browser errors.
+    if (CSS_PROPS_REGISTRY[prop] || (DEFAULT_CSS_PROPERTIES_LIST && DEFAULT_CSS_PROPERTIES_LIST.has(prop))) continue
+
+    // Check if this prop is a valid HTML attribute for this tag.
+    // Note: do NOT pre-guard with `HTML_ATTRIBUTES[prop]` — that map is keyed
+    // by tag name, not attribute name, so the guard would only ever pass for
+    // props whose name happens to also be a tag (e.g. `a`, `div`). The proper
+    // check is checkAttributeByTagName, which inspects the tag's attribute list.
+    if (checkAttributeByTagName(tag, prop)) {
+      let val = element[prop]
+      if (val == null || val === false) continue
+
+      // Resolve {{ }} template literals
+      if (typeof val === 'string' && val.includes('{{')) {
+        val = replaceLiteralsWithObjectFields(val, element, element.state, element.context)
+        element[prop] = val
+      }
+
+      if (val == null || val === false || typeof val === 'function' || typeof val === 'object') continue
+      node.setAttribute(prop, val === true ? '' : val)
+    }
+  }
+}
+
+// --- Events ---
+// v3 syntax: onXxx handlers directly on the component (no `on: {}` wrapper)
+
+function registerEvents(element, options) {
+  for (const key in element) {
+    if (!Object.prototype.hasOwnProperty.call(element, key)) continue
+    if (!isEventHandler(key)) continue
+
+    let handler = element[key]
+
+    // String shortcut: onClick: 'fnName' → el.call('fnName', ev)
+    if (typeof handler === 'string') {
+      const fnName = handler
+      handler = function stringHandlerShortcut (ev) {
+        return element.call(fnName, ev)
+      }
+    }
+
+    if (typeof handler !== 'function') continue
+
+    const eventName = eventNameFrom(key)
+    if (LIFECYCLE_EVENTS.has(eventName)) continue
+
+    registerEvent(toDomEventName(eventName), element, handler)
+  }
+}
+
+// --- Children ---
+
+// Deep merge childProps with childDef — nested objects are merged, not replaced
+function deepMergeChildProps(base, override) {
+  const result = { ...base }
+  for (const key in override) {
+    const bVal = result[key]
+    const oVal = override[key]
+    if (bVal && oVal && typeof bVal === 'object' && typeof oVal === 'object' &&
+        !Array.isArray(bVal) && !Array.isArray(oVal) &&
+        typeof bVal !== 'function' && typeof oVal !== 'function') {
+      result[key] = deepMergeChildProps(bVal, oVal)
+    } else {
+      result[key] = oVal
+    }
+  }
+  return result
+}
+
+// Renders resolved children (array, object, or string state ref) into the element's DOM
+function renderChildren(element, children, options) {
+  if (!children || !element.node) return
+
+  const childExtends = element.childExtends
+
+  if (Array.isArray(children)) {
+    const doc = element.context?.document || globalThis.document
+    const fragment = doc?.createDocumentFragment()
+    if (!fragment) return
+
+    const childPropsRaw = element.childProps
+    const childrenAs = element.childrenAs
+
+    for (let i = 0; i < children.length; i++) {
+      let childDef = children[i]
+      const rawChild = childDef
+
+      if (typeof childDef === 'string' || typeof childDef === 'number') {
+        childDef = { text: childDef }
+      }
+
+      // Resolve function-valued childProps per child
+      let childProps = childPropsRaw
+      if (typeof childPropsRaw === 'function') {
+        try {
+          childProps = childPropsRaw(element, childDef)
+        } catch (e) {
+          childProps = null
+        }
+      }
+
+      if (childrenAs === 'state') {
+        // For string/number children, create state with both value and text for v3 compat
+        let stateVal = rawChild
+        if (typeof rawChild === 'string' || typeof rawChild === 'number') {
+          stateVal = { value: rawChild, text: rawChild }
+        }
+        childDef = childProps ? { ...childProps, state: stateVal } : { state: stateVal }
+      } else if (childProps) {
+        childDef = deepMergeChildProps(childProps, childDef)
+      }
+
+      if (childExtends && !childDef.ignoreChildExtends) {
+        if (childDef.extends) {
+          const own = Array.isArray(childDef.extends) ? childDef.extends : [childDef.extends]
+          const parent = Array.isArray(childExtends) ? childExtends : [childExtends]
+          childDef = { ...childDef, extends: [...parent, ...own] }
+        } else {
+          childDef = { extends: childExtends, ...childDef }
+        }
+      }
+
+      const childKey = childDef?.key || `${i}`
+      const child = create(childDef, element, childKey, options)
+      if (child?.node) fragment.appendChild(child.node)
+    }
+
+    element.node.appendChild(fragment)
+    return
+  }
+
+  if (typeof children === 'string') {
+    const stateVal = resolveStatePath(children, element)
+    if (Array.isArray(stateVal)) {
+      renderChildren(element, stateVal, options)
+      return
+    }
+  }
+
+  if (typeof children === 'object') {
+    for (const childKey in children) {
+      if (REGISTRY.has(childKey)) continue
+
+      let childDef = children[childKey]
+      if (childDef == null || childDef === false) continue
+
+      if (typeof childDef === 'string' || typeof childDef === 'number') {
+        childDef = { text: childDef }
+      }
+
+      if (element.childProps) {
+        childDef = deepMergeChildProps(element.childProps, childDef)
+      }
+
+      if (childExtends && !childDef.ignoreChildExtends) {
+        if (childDef.extends) {
+          const own = Array.isArray(childDef.extends) ? childDef.extends : [childDef.extends]
+          const parent = Array.isArray(childExtends) ? childExtends : [childExtends]
+          childDef = { ...childDef, extends: [...parent, ...own] }
+        } else {
+          childDef = { extends: childExtends, ...childDef }
+        }
+      }
+
+      create(childDef, element, childKey, options)
+    }
+  }
+}
+
+function createChildren(element, options) {
+  let { children, content } = element
+  const childExtends = element.childExtends
+
+  // Resolve function-valued children with reactive tracking
+  if (typeof children === 'function') {
+    const childrenFn = children
+    children = childrenFn(element, element.state, element.context)
+    element.children = children
+
+    // Reactive effect: keyed reconciliation on update.
+    //
+    // Previously we wiped every child and rebuilt from scratch whenever
+    // the children factory produced a new result. That destroyed any
+    // DOM state inside the subtree — most visibly, an `<input>` being
+    // typed into would lose focus after every keystroke because its
+    // node was detached and replaced.
+    //
+    // Now we diff the incoming array against `ref.__children`:
+    //   • keys still present   → update the child's reactive state in
+    //                            place so its subscribers re-render,
+    //                            but the DOM node (and its focus /
+    //                            selection state) is preserved.
+    //   • keys gone            → remove + delete.
+    //   • new keys             → create and append.
+    //
+    // Non-array results and non-`childrenAs: 'state'` children still
+    // fall through to the full rebuild path since we can't safely
+    // update their internals in place.
+    const ref = element.__ref
+    let initialized = false
+    const effect = createEffect(() => {
+      const result = childrenFn(element, element.state, element.context)
+      if (!initialized) { initialized = true; return }
+      if (result === element.children) return
+
+      element.children = result
+
+      // Fast path: keyed reconciliation for array children + childrenAs=state.
+      // This is the only case where we can safely update in place, because
+      // each child owns a reactive store whose fields we can patch.
+      const isArr = Array.isArray(result)
+      const canReconcile = isArr && element.childrenAs === 'state'
+
+      if (canReconcile) {
+        // Compute the new key order. Key resolution mirrors renderChildren:
+        // a `childProps` factory can lift `key` to the top level of the
+        // synthesized childDef; otherwise fall back to `rawChild.key`,
+        // finally falling back to the positional index.
+        const childPropsRaw = element.childProps
+        const newOrder = []
+        const itemByKey = new Map()
+        for (let i = 0; i < result.length; i++) {
+          const rawChild = result[i]
+          let childProps = childPropsRaw
+          if (typeof childPropsRaw === 'function') {
+            try { childProps = childPropsRaw(element, rawChild) } catch { childProps = null }
+          }
+          const key = (childProps && childProps.key) || (rawChild && rawChild.key) || `${i}`
+          newOrder.push(key)
+          itemByKey.set(key, { rawChild, childProps })
+        }
+
+        const newKeySet = new Set(newOrder)
+        // Remove children whose keys are no longer present.
+        for (let i = ref.__children.length - 1; i >= 0; i--) {
+          const k = ref.__children[i]
+          if (!newKeySet.has(k)) {
+            const child = element[k]
+            if (child?.remove) child.remove()
+            delete element[k]
+            ref.__children.splice(i, 1)
+          }
+        }
+
+        // Upsert children in order. Existing keys reuse their node and
+        // patch their state; new keys are created and appended.
+        const childExtends = element.childExtends
+        const doc = element.context?.document || globalThis.document
+        const fragment = doc?.createDocumentFragment()
+        for (const key of newOrder) {
+          const entry = itemByKey.get(key)
+          const rawChild = entry.rawChild
+          const existing = element[key]
+
+          if (existing && existing.state) {
+            // Patch the existing store with the new item's fields via
+            // `state.replace(obj)` — unlike `update` (which only merges
+            // new keys) `replace` also REMOVES any prior keys that
+            // aren't on the new object. Critical for list reconcilers:
+            // without replace semantics, a row that went from parent
+            // summary → sub-row would inherit the old `_isParent: true`
+            // flag and render both roles simultaneously.
+            //
+            // Signals fire for added / changed / removed keys, so the
+            // child's `text` / `hide` / `style` gates re-evaluate and
+            // the DOM node (+ any focused input inside) stays untouched.
+            if (rawChild && typeof rawChild === 'object') {
+              const st = existing.state
+              if (typeof st.replace === 'function') {
+                st.replace(rawChild)
+              } else if (typeof st.update === 'function') {
+                // Fallback for stores without replace(): emulate it by
+                // nulling keys not in the new object, then update().
+                for (const k2 in st) {
+                  if (k2 === '__element' || k2 === 'root' || k2 === 'parent' || k2 === 'update') continue
+                  if (!Object.prototype.hasOwnProperty.call(rawChild, k2)) {
+                    try { st[k2] = undefined } catch {}
+                  }
+                }
+                st.update(rawChild)
+              } else {
+                for (const k2 in rawChild) st[k2] = rawChild[k2]
+              }
+            }
+            continue
+          }
+
+          // New child — build the childDef the same way renderChildren does,
+          // then create + append.
+          let stateVal = rawChild
+          if (typeof rawChild === 'string' || typeof rawChild === 'number') {
+            stateVal = { value: rawChild, text: rawChild }
+          }
+          const childProps = entry.childProps
+          let childDef = childProps ? { ...childProps, state: stateVal } : { state: stateVal }
+
+          if (childExtends && !childDef.ignoreChildExtends) {
+            if (childDef.extends) {
+              const own = Array.isArray(childDef.extends) ? childDef.extends : [childDef.extends]
+              const parent = Array.isArray(childExtends) ? childExtends : [childExtends]
+              childDef = { ...childDef, extends: [...parent, ...own] }
+            } else {
+              childDef = { extends: childExtends, ...childDef }
+            }
+          }
+
+          const child = create(childDef, element, key, options)
+          if (child?.node && fragment) fragment.appendChild(child.node)
+        }
+        if (fragment && fragment.childNodes.length && element.node) {
+          element.node.appendChild(fragment)
+        }
+
+        // Keep __children in the new order for stable future reconciliations.
+        ref.__children = newOrder
+        return
+      }
+
+      // Fallback: full rebuild (non-array results, or childrenAs not set).
+      for (const key of [...ref.__children]) {
+        const child = element[key]
+        if (child?.remove) child.remove()
+        delete element[key]
+      }
+      ref.__children = []
+      renderChildren(element, result, options)
+    }, { depth: ref.path.length })
+    ref.__effects.push(effect)
+  }
+
+  renderChildren(element, children || content, options)
+
+  if (children || content) return
+
+  // Iterate element properties for child components (Uppercase keys)
+  const components = element.context?.components || {}
+
+  // v3 compat: resolve XxxExtends shorthand
+  // Pattern: StarIconExtends: 'Icon', name: 'star', fontSize: 'X2'
+  // Becomes: StarIcon: { extends: 'Icon', name: 'star', fontSize: 'X2' }
+  {
+    const keys = Object.keys(element)
+    for (let i = 0; i < keys.length; i++) {
+      const prop = keys[i]
+      if (!prop.endsWith('Extends') || typeof element[prop] !== 'string') continue
+      const childName = prop.slice(0, -7)
+      if (!childName || childName.charCodeAt(0) < 65 || childName.charCodeAt(0) > 90) continue
+
+      const childDef = { extends: element[prop] }
+      delete element[prop]
+
+      // Collect subsequent lowercase properties until next Uppercase key or end
+      for (let j = i + 1; j < keys.length; j++) {
+        const nextKey = keys[j]
+        const fc = nextKey.charCodeAt(0)
+        if (fc >= 65 && fc <= 90) break // Stop at next child/component key
+        if (REGISTRY.has(nextKey)) break // Stop at framework keys
+        if (typeof element[nextKey] === 'function' && (nextKey.startsWith('on') || nextKey.startsWith('.'))) break
+        const val = element[nextKey]
+        if (val !== undefined) {
+          childDef[nextKey] = val
+          delete element[nextKey]
+        }
+      }
+
+      // Merge with existing child def if present
+      if (element[childName] && typeof element[childName] === 'object') {
+        element[childName] = { ...childDef, ...element[childName] }
+      } else {
+        element[childName] = childDef
+      }
+    }
+  }
+
+  for (const prop in element) {
+    if (!Object.prototype.hasOwnProperty.call(element, prop)) continue
+    if (REGISTRY.has(prop)) continue
+    if (typeof element[prop] !== 'object' || element[prop] === null) continue
+
+    const firstChar = prop.charCodeAt(0)
+    if (firstChar < 65 || firstChar > 90) continue
+
+    let childDef = element[prop]
+    if (childDef.__ref) continue // Already created
+
+    // Auto-extend from context component if key matches and no extends set
+    if (!childDef.extends && !childDef.extend) {
+      const comp = components[prop] || components[`smbls.${prop}`]
+      if (comp) {
+        childDef = { extends: comp, ...childDef }
+      }
+    }
+
+    // Apply childProps (e.g. fontSize, padding from parent's childProps)
+    if (element.childProps) {
+      childDef = { ...element.childProps, ...childDef }
+    }
+
+    if (childExtends && !childDef.ignoreChildExtends) {
+      if (childDef.extends) {
+        const own = Array.isArray(childDef.extends) ? childDef.extends : [childDef.extends]
+        const parent = Array.isArray(childExtends) ? childExtends : [childExtends]
+        childDef = { ...childDef, extends: [...parent, ...own] }
+      } else {
+        childDef = { extends: childExtends, ...childDef }
+      }
+    }
+
+    create(childDef, element, prop, options)
+  }
+}
+
+// --- DOM Assignment ---
+
+function assignNode(element, parent, attachOptions) {
+  const { node } = element
+  if (!node) return
+
+  // Expose DOMQL ref on DOM node in dev mode (use $0.ref in DevTools)
+  if (process.env.NODE_ENV !== 'production') {
+    node.ref = element
+  }
+
+  // Support both DOMQL elements (.node) and raw DOM nodes (root case)
+  const parentNode = parent?.node || (parent?.nodeType ? parent : null)
+  if (!parentNode) return
+
+  if (attachOptions?.position === 'before' && attachOptions.node) {
+    parentNode.insertBefore(node, attachOptions.node)
+  } else if (attachOptions?.position === 'after' && attachOptions.node) {
+    const nextSib = attachOptions.node.nextSibling
+    if (nextSib) {
+      parentNode.insertBefore(node, nextSib)
+    } else {
+      parentNode.appendChild(node)
+    }
+  } else {
+    parentNode.appendChild(node)
+  }
+}
+
+function triggerLifecycle(eventSuffix, element, options) {
+  const hookName = eventSuffix.charAt(0).toLowerCase() + eventSuffix.slice(1)
+  if (element.context?.plugins?.length) runPluginHook(hookName, element, options)
+
+  const key = 'on' + eventSuffix
+  const handler = element[key]
+  if (typeof handler === 'function') {
+    // Scope config to this element's context so lifecycle handlers that
+    // inject CSS or resolve tokens use the right app. The document is
+    // stored on the config, so getActiveDocument() resolves it too.
+    const ds = element.context?.designSystem
+    if (ds) pushConfig(ds)
+    try {
+      const result = handler(element, element.state, element.context, options)
+      if (result === false) return false
+    } catch (err) {
+      // Route the error through the plugin error hook so observers
+      // (e.g. the analyze plugin) see it with full element context.
+      // Falls back to console.error when no plugin captures it.
+      const handled = element.context?.plugins?.length &&
+        runPluginHook('error', element, { hook: key, error: err })
+      if (!handled) console.error(`[DOMQL] Lifecycle "${key}" error:`, err)
+      if (element.context?.strictMode) throw err
+    } finally {
+      if (ds) popConfig()
+    }
+  }
+  return true
+}
+
+export default create