Auto-target by beam-id; normalize server HTML

Switch auto-targeting to use beam-id / beam-item-id (remove plain id auto-detection) and update docs/examples accordingly. Add normalizeHtmlForTarget to unwrap a single-server-root that matches the target's beam-id/beam-item-id to avoid nesting, and propagate that normalization into swap/append/prepend/replace/morph flows. Extend morph to accept a MorphStyle option (innerHTML|outerHTML) and use outerHTML when morphing deduped items. Update TypeScript types and README examples to reflect beam-id usage and clarify target resolution behavior.

Author: BenQoder

README.md

@@ -144,6 +144,8 @@ Use `beam-include` to collect values from input elements and include them in act
   beam-data-source="form"
   beam-target="#result"
 >Save</button>
+
+<div id="result"></div>
 ```
 
 The action receives merged params with proper type conversion:
@@ -251,15 +253,15 @@ export function refreshDashboard(ctx: BeamContext<Env>) {
 }
 ```
 
-**2. Auto-detect by ID (no targets needed)**
+**2. Auto-detect by beam-id / beam-item-id (no targets needed)**
 
 ```tsx
 export function refreshDashboard(ctx: BeamContext<Env>) {
-  // Client automatically finds elements by id, beam-id, or beam-item-id
+  // Client automatically finds elements by beam-id or beam-item-id
   return ctx.render([
-    <div id="stats">Visits: {visits}</div>,
-    <div id="users">Users: {users}</div>,
-    <div id="revenue">Revenue: ${revenue}</div>,
+    <div beam-id="stats">Visits: {visits}</div>,
+    <div beam-id="users">Users: {users}</div>,
+    <div beam-id="revenue">Revenue: ${revenue}</div>,
   ])
 }
 ```
@@ -271,7 +273,7 @@ export function updateDashboard(ctx: BeamContext<Env>) {
   return ctx.render(
     [
       <div>Header content</div>,           // Uses explicit target
-      <div id="content">Main content</div>, // Auto-detected by ID
+      <div beam-id="content">Main content</div>, // Auto-detected by beam-id
     ],
     { target: '#header' }  // Only first item gets explicit target
   )
@@ -280,10 +282,15 @@ export function updateDashboard(ctx: BeamContext<Env>) {
 
 **Target Resolution Order:**
 1. Explicit target from comma-separated list (by index)
-2. ID from the HTML fragment's root element (`id`, `beam-id`, or `beam-item-id`)
+2. Identity from the HTML fragment's root element (`beam-id` or `beam-item-id`)
 3. Frontend fallback (`beam-target` on the triggering element)
 4. Skip if no target found
 
+Notes:
+- `beam-target` accepts any valid CSS selector (e.g. `#id`, `.class`, `[attr=value]`). Using `#id` targets is still fully supported.
+- Auto-targeting (step 2) intentionally does **not** use plain `id="..."` anymore; it uses only `beam-id` / `beam-item-id`.
+- When an explicit target is used and the server returns a single root element that has the same `beam-id`/`beam-item-id` as the target, Beam unwraps it and swaps only the target’s inner content. This prevents accidentally nesting the component inside itself.
+
 **Exclusion:** Use `!selector` to explicitly skip an item:
 ```tsx
 ctx.render(

src/client.ts

@@ -221,12 +221,41 @@ function $$(selector: string): NodeListOf<Element> {
   return document.querySelectorAll(selector)
 }
 
-function morph(target: Element, html: string, options?: { keepElements?: string[] }): void {
+type MorphStyle = 'innerHTML' | 'outerHTML'
+
+function normalizeHtmlForTarget(target: Element, html: string): string {
+  const temp = document.createElement('div')
+  temp.innerHTML = html.trim()
+
+  // If server sent a wrapper that matches the target element, unwrap it.
+  // This avoids nesting <div beam-id="x"> inside <div beam-id="x"> and matches
+  // the intuitive expectation: targeting an element updates its *inner* content.
+  if (temp.childElementCount !== 1) return html
+  const root = temp.firstElementChild
+  if (!root) return html
+
+  const targetBeamId = target.getAttribute('beam-id')
+  const rootBeamId = root.getAttribute('beam-id')
+  if (targetBeamId && rootBeamId && targetBeamId === rootBeamId) return root.innerHTML
+
+  const targetBeamItemId = target.getAttribute('beam-item-id')
+  const rootBeamItemId = root.getAttribute('beam-item-id')
+  if (targetBeamItemId && rootBeamItemId && targetBeamItemId === rootBeamItemId) return root.innerHTML
+
+  return html
+}
+
+function morph(
+  target: Element,
+  html: string,
+  options?: { keepElements?: string[]; style?: MorphStyle }
+): void {
   const keepSelectors = options?.keepElements || []
+  const morphStyle: MorphStyle = options?.style || 'innerHTML'
 
   // @ts-ignore - idiomorph types
   Idiomorph.morph(target, html, {
-    morphStyle: 'innerHTML',
+    morphStyle,
     callbacks: {
       // Skip morphing elements marked with beam-keep (preserves their current value)
       // This only applies when both old and new DOM have a matching element
@@ -560,7 +589,7 @@ function dedupeItems(target: Element, html: string): string {
       // Morph existing item with fresh data
       const existing = target.querySelector(`[beam-item-id="${id}"]`)
       if (existing) {
-        morph(existing, el.outerHTML)
+        morph(existing, el.outerHTML, { style: 'outerHTML' })
       }
       // Remove from incoming HTML (already updated in place)
       el.remove()
@@ -572,25 +601,26 @@ function dedupeItems(target: Element, html: string): string {
 
 function swap(target: Element, html: string, mode: string, trigger?: HTMLElement): void {
   const { main, oob } = parseOobSwaps(html)
+  const normalizedMain = normalizeHtmlForTarget(target, main)
 
   switch (mode) {
     case 'append':
       trigger?.remove()
-      target.insertAdjacentHTML('beforeend', dedupeItems(target, main))
+      target.insertAdjacentHTML('beforeend', dedupeItems(target, normalizedMain))
       break
     case 'prepend':
       trigger?.remove()
-      target.insertAdjacentHTML('afterbegin', dedupeItems(target, main))
+      target.insertAdjacentHTML('afterbegin', dedupeItems(target, normalizedMain))
       break
     case 'replace':
-      target.innerHTML = main
+      target.innerHTML = normalizedMain
       break
     case 'delete':
       target.remove()
       break
     case 'morph':
     default:
-      morph(target, main)
+      morph(target, normalizedMain)
       break
   }
 
@@ -658,17 +688,14 @@ function handleHtmlResponse(
         console.warn(`[beam] Target "${explicitTarget}" not found on page, skipping`)
       }
     } else {
-      // Priority 3: id, beam-id, or beam-item-id on root element
+      // Priority 3: beam-id or beam-item-id on root element
       const temp = document.createElement('div')
       temp.innerHTML = htmlItem.trim()
       const rootEl = temp.firstElementChild
 
-      // Check id first, then beam-id, then beam-item-id
-      const id = rootEl?.id
       const beamId = rootEl?.getAttribute('beam-id')
       const beamItemId = rootEl?.getAttribute('beam-item-id')
-      const selector = id ? `#${id}`
-        : beamId ? `[beam-id="${beamId}"]`
+      const selector = beamId ? `[beam-id="${beamId}"]`
         : beamItemId ? `[beam-item-id="${beamItemId}"]`
         : null
 

src/types.ts

@@ -53,7 +53,7 @@ export interface BeamContext<TEnv = object> {
    * Accepts JSX directly (converts to string), single string, or array for multi-target rendering.
    * @example ctx.render(<ProductList />, { script: 'playSound("ding")' })
    * @example ctx.render([<StatsWidget />, <NotificationList />], { target: '#stats, #notifications' })
-   * @example ctx.render([<div id="stats">...</div>, <div id="notifications">...</div>]) // auto-detects targets by ID
+   * @example ctx.render([<div beam-id="stats">...</div>, <div beam-id="notifications">...</div>]) // auto-detects targets by beam-id / beam-item-id
    */
   render(
     content: string | Promise<string> | (string | Promise<string>)[],