@barefootjs/client 0.1.0

package/src/runtime/reconcile-elements.ts

@@ -0,0 +1,391 @@
+/**
+ * BarefootJS - Element-based List Reconciliation
+ *
+ * Key-based DOM reconciliation for component-based list rendering.
+ * Used when renderItem returns HTMLElement (via createComponent).
+ */
+
+import { hydratedScopes } from './hydration-state'
+import { BF_SCOPE, BF_SLOT, BF_COND, BF_KEY, BF_LOOP_START, BF_LOOP_END, loopStartMarker, loopEndMarker } from '@barefootjs/shared'
+
+/**
+ * Find loop boundary comment markers in a container.
+ *
+ * `markerId` scopes the lookup to `<!--bf-loop:<id>-->` / `<!--bf-/loop:<id>-->`
+ * so sibling loops under the same parent disambiguate (#1087). Without an id,
+ * accepts the legacy unscoped form too — used by tests that build containers
+ * without compiler-emitted markers.
+ */
+function findLoopMarkers(
+  container: HTMLElement,
+  markerId?: string,
+): { startMarker: Comment | null; endMarker: Comment | null } {
+  let startMarker: Comment | null = null
+  let endMarker: Comment | null = null
+  if (markerId) {
+    const startVal = loopStartMarker(markerId)
+    const endVal = loopEndMarker(markerId)
+    for (const node of Array.from(container.childNodes)) {
+      if (node.nodeType !== Node.COMMENT_NODE) continue
+      const value = (node as Comment).nodeValue
+      if (value === startVal) startMarker = node as Comment
+      else if (value === endVal) endMarker = node as Comment
+    }
+  } else {
+    const startPrefix = `${BF_LOOP_START}:`
+    const endPrefix = `${BF_LOOP_END}:`
+    for (const node of Array.from(container.childNodes)) {
+      if (node.nodeType !== Node.COMMENT_NODE) continue
+      const value = (node as Comment).nodeValue ?? ''
+      if (!startMarker && (value === BF_LOOP_START || value.startsWith(startPrefix))) {
+        startMarker = node as Comment
+      } else if (!endMarker && (value === BF_LOOP_END || value.startsWith(endPrefix))) {
+        endMarker = node as Comment
+      }
+    }
+  }
+  if (startMarker && endMarker) return { startMarker, endMarker }
+  return { startMarker: null, endMarker: null }
+}
+
+/** Get all Element nodes between start and end comment markers. */
+function getElementsBetweenMarkers(start: Comment, end: Comment): Element[] {
+  const elements: Element[] = []
+  let node: Node | null = start.nextSibling
+  while (node && node !== end) {
+    if (node.nodeType === Node.ELEMENT_NODE) {
+      elements.push(node as Element)
+    }
+    node = node.nextSibling
+  }
+  return elements
+}
+
+/** Remove all nodes between start and end comment markers (preserves the markers). */
+function removeElementsBetweenMarkers(start: Comment, end: Comment): void {
+  let node: Node | null = start.nextSibling
+  while (node && node !== end) {
+    const next: Node | null = node.nextSibling
+    node.parentNode?.removeChild(node)
+    node = next
+  }
+}
+
+/**
+ * Get loop children from a container, respecting bf-loop boundary markers.
+ * When markers are present, returns only elements between them.
+ * When absent, returns all children (backward compatible).
+ * Exported for use by compiler-generated hydration code.
+ */
+export function getLoopChildren(container: HTMLElement, markerId?: string): HTMLElement[] {
+  const { startMarker, endMarker } = findLoopMarkers(container, markerId)
+  if (startMarker && endMarker) {
+    return getElementsBetweenMarkers(startMarker, endMarker) as HTMLElement[]
+  }
+  return Array.from(container.children) as HTMLElement[]
+}
+
+/**
+ * Like {@link getLoopChildren}, but returns every node between the loop
+ * boundary markers — Comments (per-item `<!--bf-loop-i-->` markers) and
+ * text included. The branch-clearing path needs to remove the per-item
+ * marker comments alongside elements; otherwise stale markers would
+ * accumulate when a branch swap forces mapArray to start over (#1212).
+ */
+export function getLoopNodes(container: HTMLElement, markerId?: string): Node[] {
+  const { startMarker, endMarker } = findLoopMarkers(container, markerId)
+  const nodes: Node[] = []
+  if (startMarker && endMarker) {
+    let node: Node | null = startMarker.nextSibling
+    while (node && node !== endMarker) {
+      nodes.push(node)
+      node = node.nextSibling
+    }
+    return nodes
+  }
+  return Array.from(container.childNodes)
+}
+
+/**
+ * Ensure loop boundary markers exist in a container for SSR-rendered content.
+ * SSR HTML doesn't include markers, so we insert them during hydration.
+ * Uses itemCount to identify the last N children as loop items (rest are siblings).
+ */
+export function ensureLoopMarkers(container: HTMLElement, itemCount: number, markerId?: string): void {
+  // Already has markers
+  const { startMarker } = findLoopMarkers(container, markerId)
+  if (startMarker) return
+
+  const children = Array.from(container.children)
+  if (children.length === 0) return
+
+  // Loop items are the LAST itemCount children (siblings come first in HTML order)
+  const loopStartIdx = Math.max(0, children.length - itemCount)
+  const firstLoopChild = children[loopStartIdx]
+
+  const start = document.createComment(markerId ? loopStartMarker(markerId) : BF_LOOP_START)
+  const end = document.createComment(markerId ? loopEndMarker(markerId) : BF_LOOP_END)
+  container.insertBefore(start, firstLoopChild)
+  container.appendChild(end)
+}
+
+/**
+ * Reconcile a list container using HTMLElement mode (for createComponent).
+ * Reuses existing elements by key, creates new elements as needed.
+ *
+ * @param container - The parent element containing list items
+ * @param items - Array of items to render
+ * @param getKey - Function to extract a unique key from each item (or null to use index)
+ * @param renderItem - Function that returns an HTMLElement for each item
+ * @param firstElement - Pre-created element for first item (avoids duplicate creation when caller already rendered item 0)
+ */
+export function reconcileElements<T>(
+  container: HTMLElement | null,
+  items: T[],
+  getKey: ((item: T, index: number) => string) | null,
+  renderItem: (item: T, index: number) => HTMLElement,
+  firstElement?: HTMLElement,
+  markerId?: string,
+): void {
+  if (!container || !items) return
+
+  // Find loop boundary markers if present.
+  // When markers exist, only elements between <!--bf-loop--> and <!--/bf-loop-->
+  // participate in reconciliation — siblings outside the range are preserved.
+  const { startMarker, endMarker } = findLoopMarkers(container, markerId)
+
+  // Collect existing keyed elements (only within loop range if markers exist)
+  const existingByKey = new Map<string, HTMLElement>()
+  let hasKeyedChildren = false
+  const loopChildren = startMarker
+    ? getElementsBetweenMarkers(startMarker, endMarker!)
+    : Array.from(container.children)
+  for (const child of loopChildren) {
+    const el = child as HTMLElement
+    const key = el.dataset?.key
+    if (key !== undefined) {
+      existingByKey.set(key, el)
+      hasKeyedChildren = true
+    }
+  }
+
+  // When no keyed children exist (initial SSR render or all-unkeyed container),
+  // use the simple clear-and-replace path. Non-keyed children in this case are
+  // SSR-rendered loop items that haven't been through hydration yet.
+  if (!hasKeyedChildren) {
+    if (items.length === 0) {
+      if (startMarker) {
+        removeElementsBetweenMarkers(startMarker, endMarker!)
+      } else {
+        container.innerHTML = ''
+      }
+      return
+    }
+
+    const fragment = document.createDocumentFragment()
+    for (let i = 0; i < items.length; i++) {
+      const el = (i === 0 && firstElement) ? firstElement : renderItem(items[i], i)
+      const key = getKey ? getKey(items[i], i) : String(i)
+      if (!el.dataset.key) el.setAttribute(BF_KEY, key)
+      fragment.appendChild(el)
+    }
+    if (startMarker) {
+      removeElementsBetweenMarkers(startMarker, endMarker!)
+      endMarker!.parentNode!.insertBefore(fragment, endMarker)
+    } else {
+      container.innerHTML = ''
+      container.appendChild(fragment)
+    }
+    return
+  }
+
+  // Insert anchor: end marker (if present) or first non-keyed sibling after keyed region.
+  let insertAnchor: Node | null = endMarker ?? null
+  if (!startMarker) {
+    let foundKeyed = false
+    for (const child of Array.from(container.childNodes)) {
+      if (child.nodeType === Node.ELEMENT_NODE && (child as HTMLElement).dataset.key !== undefined) {
+        foundKeyed = true
+      } else if (foundKeyed) {
+        insertAnchor = child
+        break
+      }
+    }
+  }
+
+  // --- Phase 1: Detect focus (before ANY DOM mutation) ---
+  // Only text inputs have ongoing user state (cursor, selection, typed text)
+  // that must survive reconciliation. Button focus has no state to preserve.
+  let focusedKey: string | null = null
+  const activeEl = document.activeElement
+  if (activeEl && activeEl !== document.body) {
+    const tag = activeEl.tagName
+    if (tag === 'INPUT' || tag === 'TEXTAREA' || tag === 'SELECT'
+        || (activeEl as HTMLElement).isContentEditable) {
+      for (const [key, el] of existingByKey) {
+        if (el.contains(activeEl)) {
+          focusedKey = key
+          break
+        }
+      }
+    }
+  }
+
+  // --- Phase 2: Build desired element list ---
+  // For each item, decide: reuse existing (focus), create new, or skip.
+  // Track old elements to remove explicitly — no bulk remove-all.
+  const desiredElements: HTMLElement[] = []
+  const toRemove: Element[] = []
+  let focusTarget: FocusTransferInfo | null = null
+
+  for (let i = 0; i < items.length; i++) {
+    const item = items[i]
+    const key = getKey ? getKey(item, i) : String(i)
+    const createEl = () => (i === 0 && firstElement) ? firstElement : renderItem(item, i)
+
+    const existing = existingByKey.get(key)
+    if (existing) {
+      existingByKey.delete(key)
+
+      if (existing.getAttribute(BF_SCOPE) && !hydratedScopes.has(existing)) {
+        // Uninitialized SSR element — replace with client-rendered element
+        const newEl = createEl()
+        if (!newEl.dataset.key) newEl.setAttribute(BF_KEY, key)
+        desiredElements.push(newEl)
+        toRemove.push(existing)
+      } else if (focusedKey === key) {
+        // Element contains a focused text input. Create the new element (with
+        // updated inner loops, conditionals, etc.), copy input state now,
+        // defer focus() to after DOM insertion to avoid flicker.
+        const newEl = createEl()
+        if (!newEl.dataset.key) newEl.setAttribute(BF_KEY, key)
+        focusTarget = prepareInputTransfer(existing, newEl)
+        desiredElements.push(newEl)
+        toRemove.push(existing)
+      } else {
+        // Normal update — use new element
+        const newEl = createEl()
+        if (!newEl.dataset.key) newEl.setAttribute(BF_KEY, key)
+        desiredElements.push(newEl)
+        toRemove.push(existing)
+      }
+    } else {
+      // Brand new key
+      const el = createEl()
+      if (!el.dataset.key) el.setAttribute(BF_KEY, key)
+      desiredElements.push(el)
+    }
+  }
+
+  // Remaining entries in existingByKey are orphans (key no longer in items)
+  for (const el of existingByKey.values()) {
+    toRemove.push(el)
+  }
+
+  // --- Phase 3: Remove old elements ---
+  for (const el of toRemove) {
+    if (el.parentNode) el.remove()
+  }
+
+  // --- Phase 4: Insert/move desired elements in correct order ---
+  // insertBefore moves already-connected elements; inserts new ones.
+  for (const el of desiredElements) {
+    container.insertBefore(el, insertAnchor)
+  }
+
+  // --- Phase 5: Restore focus synchronously (element is now in DOM) ---
+  if (focusTarget) {
+    focusTarget.target.focus()
+    if (typeof focusTarget.selectionStart === 'number') {
+      focusTarget.target.selectionStart = focusTarget.selectionStart
+      focusTarget.target.selectionEnd = focusTarget.selectionEnd
+    }
+  }
+}
+
+interface FocusTransferInfo {
+  target: HTMLInputElement
+  selectionStart: number | null
+  selectionEnd: number | null
+}
+
+/**
+ * Prepare focus transfer: copy value + selection state from old focused input
+ * to the matching input in newEl. Returns info needed to call focus() later
+ * (after the new element is inserted into the DOM).
+ */
+function prepareInputTransfer(oldEl: HTMLElement, newEl: HTMLElement): FocusTransferInfo | null {
+  const focused = oldEl.contains(document.activeElement) ? document.activeElement as HTMLInputElement : null
+  if (!focused) return null
+
+  const tag = focused.tagName
+  const oldInputs = Array.from(oldEl.querySelectorAll(tag))
+  const idx = oldInputs.indexOf(focused)
+  if (idx < 0) return null
+
+  const newInputs = Array.from(newEl.querySelectorAll(tag)) as HTMLInputElement[]
+  const target = newInputs[idx]
+  if (!target) return null
+
+  target.value = focused.value
+  return {
+    target,
+    selectionStart: focused.selectionStart,
+    selectionEnd: focused.selectionEnd,
+  }
+}
+
+/**
+ * Sync reactive DOM state from a source element to a target element.
+ * Copies class names, replaces conditional elements, and syncs text content.
+ */
+export function syncElementState(target: HTMLElement, source: HTMLElement): void {
+  // Sync class list (for reactive classes like 'done' on TodoItem)
+  target.className = source.className
+
+  // First, sync conditional elements by replacing them entirely
+  const sourceCondSlots = Array.from(source.querySelectorAll(`[${BF_COND}]`))
+  for (const sourceCondSlot of sourceCondSlots) {
+    const condId = (sourceCondSlot as HTMLElement).getAttribute(BF_COND)
+    if (condId) {
+      const targetCondSlot = target.querySelector(`[${BF_COND}="${condId}"]`)
+      if (targetCondSlot) {
+        targetCondSlot.replaceWith(sourceCondSlot)
+      }
+    }
+  }
+
+  // Then sync text content of bf slots that are NOT inside conditional elements.
+  // Use querySelectorAll on BOTH source and target, then match by position index
+  // within each slot ID group. This handles multiple component instances that share
+  // the same internal slot ID (e.g., multiple Badge components each with bf="s0").
+  const sourceSlots = source.querySelectorAll(`[${BF_SLOT}]`)
+  const targetSlotsByID = new Map<string, Element[]>()
+  const targetAllSlots = target.querySelectorAll(`[${BF_SLOT}]`)
+  for (const targetSlot of Array.from(targetAllSlots)) {
+    const id = (targetSlot as HTMLElement).getAttribute(BF_SLOT)
+    if (id) {
+      if (!targetSlotsByID.has(id)) targetSlotsByID.set(id, [])
+      targetSlotsByID.get(id)!.push(targetSlot)
+    }
+  }
+
+  // Track which index we're at for each slot ID
+  const slotIndexCounters = new Map<string, number>()
+
+  for (const sourceSlot of Array.from(sourceSlots)) {
+    const slotId = (sourceSlot as HTMLElement).getAttribute(BF_SLOT)
+    if (slotId) {
+      if (sourceSlot.closest(`[${BF_COND}]`)) continue
+      const idx = slotIndexCounters.get(slotId) ?? 0
+      slotIndexCounters.set(slotId, idx + 1)
+      const targets = targetSlotsByID.get(slotId)
+      const targetSlot = targets?.[idx]
+      if (targetSlot && sourceSlot.textContent !== null) {
+        if (sourceSlot.children.length === 0) {
+          targetSlot.textContent = sourceSlot.textContent
+        }
+      }
+    }
+  }
+}

package/src/runtime/registry.ts

@@ -0,0 +1,160 @@
+/**
+ * BarefootJS - Component Registry
+ *
+ * Component registry for parent-child communication.
+ * Each component registers its init function so parents can initialize children with props.
+ */
+
+import { BF_SCOPE, BF_HOST } from '@barefootjs/shared'
+import { hydratedScopes } from './hydration-state'
+import { setCurrentScope } from './context'
+import { createComponent } from './component'
+import { findSsrScopeBySlotIn, buildSlotInfo } from './slot-resolver'
+import type { InitFn } from './types'
+
+/**
+ * Component registry for parent-child communication.
+ */
+const componentRegistry = new Map<string, InitFn>()
+
+/**
+ * Queue of pending child initializations waiting for components to register.
+ * Key: component name, Value: array of pending init requests
+ */
+const pendingChildInits = new Map<string, Array<{ scope: Element; props: Record<string, unknown> }>>()
+
+/**
+ * Register a component's init function for parent initialization.
+ * Also processes any pending child initializations for this component.
+ *
+ * @param name - Component name (e.g., 'Counter', 'AddTodoForm')
+ * @param init - Init function that takes (scope, props)
+ */
+export function registerComponent(name: string, init: InitFn): void {
+  componentRegistry.set(name, init)
+
+  // Drain any pending child initializations queued before this component
+  // registered. Re-enter through initChild so the same hydratedScopes
+  // bookkeeping + currentScope wrapping applies to deferred and immediate
+  // calls alike.
+  const pending = pendingChildInits.get(name)
+  if (pending) {
+    pendingChildInits.delete(name)
+    for (const { scope, props } of pending) {
+      initChild(name, scope, props)
+    }
+  }
+}
+
+/**
+ * Get a component's init function from the registry.
+ * Used by createComponent() to initialize dynamically created components.
+ *
+ * @param name - Component name
+ * @returns Init function or undefined if not registered
+ */
+export function getComponentInit(name: string): InitFn | undefined {
+  return componentRegistry.get(name)
+}
+
+/**
+ * Initialize a child component with props from parent.
+ * Used by parent components to pass function props (like onAdd) to children.
+ *
+ * If the child component's script hasn't loaded yet (component not registered),
+ * queues the initialization request. When the component registers via
+ * registerComponent(), pending initializations are processed synchronously.
+ *
+ * @param name - Child component name
+ * @param childScope - The child's scope element (found by parent)
+ * @param props - Props to pass to the child (including function props)
+ */
+export function initChild(
+  name: string,
+  childScope: Element | null,
+  props: Record<string, unknown> = {}
+): void {
+  if (!childScope) return
+
+  const init = componentRegistry.get(name)
+  if (!init) {
+    // Component not registered yet - queue initialization for when it registers
+    // This handles cases where parent script loads before child script
+    if (!pendingChildInits.has(name)) {
+      pendingChildInits.set(name, [])
+    }
+    pendingChildInits.get(name)!.push({ scope: childScope, props })
+    return
+  }
+
+  // Child scopes are owned by their parent's initChild entirely — once
+  // we've run their init, never re-enter. Top-level scopes (no `bf-h`)
+  // reach this path through `upsertChild` during reconcile, where
+  // re-invoking init is the documented way to deliver fresh
+  // closure-captured callback props to the child.
+  if (hydratedScopes.has(childScope) && childScope.hasAttribute(BF_HOST)) {
+    return
+  }
+
+  const prevScope = setCurrentScope(childScope)
+  try {
+    init(childScope, props)
+  } finally {
+    setCurrentScope(prevScope)
+  }
+
+  // Mark the scope as hydrated AFTER init runs so the doc-order walker in
+  // hydrate.ts knows to skip this element on its later pass — the parent
+  // has just claimed responsibility for it. This is what lets the walker
+  // get away with a single `hydratedScopes.has(el)` check instead of an
+  // ancestor-name guard.
+  hydratedScopes.add(childScope)
+}
+
+/**
+ * Upsert a child component at a slot inside `parent`. Resolves the SSR vs
+ * CSR shape at runtime in one place — so the compiler doesn't need a
+ * `mode: 'csr' | 'ssr'` argument for child component emission.
+ *
+ *   1. SSR: a `[bf-h][bf-m]` element exists for this (parent,
+ *      slot). Initialise it via initChild and return it.
+ *   2. CSR: a `[data-bf-ph="<slotId|name>"]` placeholder exists. Replace it
+ *      with `createComponent(name, props, key)` and return the new element.
+ *   3. Neither matches (already initialised on a previous reconcile pass) —
+ *      no-op, return null.
+ *
+ * The returned element is the live component scope element — callers can
+ * use it for follow-up effects (e.g. a children-textContent createEffect).
+ */
+export function upsertChild(
+  parent: Element,
+  name: string,
+  slotId: string | null,
+  props: Record<string, unknown>,
+  key?: string | number,
+  anchorScope?: Element | null,
+): HTMLElement | null {
+  // SSR: scope element is already in the tree.
+  // With slotId: (bf-h, bf-m) primary lookup (unique by construction).
+  // Without slotId: name-prefix bf-s scan for top-level component lookup.
+  let ssr: HTMLElement | null = null
+  if (slotId) {
+    ssr = findSsrScopeBySlotIn(parent, slotId, anchorScope, /* selfMatch */ false)
+  } else {
+    ssr = parent.querySelector(`[${BF_SCOPE}^="${name}_"]`) as HTMLElement | null
+  }
+  if (ssr) {
+    initChild(name, ssr, props)
+    return ssr
+  }
+  // CSR: replace placeholder with a freshly-created component.
+  const phId = slotId ?? name
+  const ph = parent.querySelector(`[data-bf-ph="${phId}"]`) as HTMLElement | null
+  if (ph) {
+    const slot = slotId ? buildSlotInfo(parent, slotId, anchorScope) : undefined
+    const comp = createComponent(name, props, key, slot)
+    ph.replaceWith(comp)
+    return comp
+  }
+  return null
+}

package/src/runtime/render.ts

@@ -0,0 +1,105 @@
+/**
+ * BarefootJS - Client-Side Rendering
+ *
+ * CSR entry point for rendering components directly in the browser
+ * without server-side rendering. Tree-shakeable: SSR-only apps
+ * never import this module.
+ */
+
+import { BF_SCOPE } from '@barefootjs/shared'
+import { setParentScopeId } from './component'
+import { hydratedScopes } from './hydration-state'
+import { getComponentInit } from './registry'
+import { getTemplate, type TemplateFn } from './template'
+import type { ComponentDef, InitFn } from './types'
+
+/**
+ * Render a component into a container element (CSR mode).
+ *
+ * Accepts either:
+ * - A registered component name (string) — looks up `init` and `template` from the registry
+ *   (the component must be registered first by importing its `.client.js` file).
+ * - A `ComponentDef` — uses the def's `init` and `template` directly, bypassing the registry.
+ *
+ * Generates DOM from the template, mounts it into the container, and initializes it
+ * with the given props. Unlike hydrate(), no pre-rendered HTML is required; the
+ * container's content is replaced entirely.
+ *
+ * @param container - Target DOM element to render into
+ * @param nameOrDef - Registered component name or a ComponentDef
+ * @param props - Props to pass to the component
+ *
+ * @example
+ * // By name (registry-based)
+ * await import('/static/components/Counter.client.js')
+ * render(document.getElementById('app')!, 'Counter', { initialCount: 0 })
+ *
+ * @example
+ * // By ComponentDef (registry-free)
+ * render(container, { name: 'MyNode', init, template }, { id: 'n1' })
+ */
+export function render(
+  container: HTMLElement,
+  nameOrDef: string | ComponentDef,
+  props: Record<string, unknown> = {}
+): void {
+  let name: string
+  let init: InitFn | undefined
+  let template: TemplateFn | undefined
+
+  if (typeof nameOrDef === 'string') {
+    name = nameOrDef
+    init = getComponentInit(name)
+    template = getTemplate(name)
+
+    if (!init || !template) {
+      throw new Error(
+        `[BarefootJS] Component "${name}" is not registered. ` +
+        `Did you import its .client.js file before calling render()?`
+      )
+    }
+  } else {
+    init = nameOrDef.init
+    template = nameOrDef.template
+    name = nameOrDef.name || init.name?.replace(/^init/, '') || 'Component'
+
+    if (!template) {
+      throw new Error(
+        '[BarefootJS] render(): ComponentDef requires a template function'
+      )
+    }
+  }
+
+  // Generate the parent scope ID up front so renderChild calls inside
+  // template() can stamp `bf-s="${parentScopeId}_sN"` on child scopes,
+  // matching what the compiler-emitted `$c(__scope, 'sN')` lookup later
+  // expects. Without this, renderChild falls back to `${childName}_${randomId}`
+  // and `$c` returns null, silently breaking child hydration. (#1160)
+  const scopeId = `${name}_${Math.random().toString(36).slice(2, 8)}`
+  setParentScopeId(scopeId)
+  let html: string
+  try {
+    html = template(props).trim()
+  } finally {
+    setParentScopeId(null)
+  }
+
+  const tpl = document.createElement('template')
+  tpl.innerHTML = html
+  const element = tpl.content.firstChild as HTMLElement
+
+  if (!element) {
+    throw new Error('[BarefootJS] render(): template returned empty HTML')
+  }
+
+  if (!element.getAttribute(BF_SCOPE)) {
+    element.setAttribute(BF_SCOPE, scopeId)
+  }
+
+  container.innerHTML = ''
+  container.appendChild(element)
+
+  init(element, props)
+
+  hydratedScopes.add(element)
+}

package/src/runtime/scope.ts

@@ -0,0 +1,46 @@
+/**
+ * BarefootJS - Comment Scope Registry
+ *
+ * Registry for elements that serve as scope proxies for comment-based scopes.
+ * Maps an element to its comment node and the sibling range boundary.
+ */
+
+import { BF_SCOPE_COMMENT_PREFIX } from '@barefootjs/shared'
+
+/**
+ * Information about a comment-based scope.
+ */
+export interface CommentScopeInfo {
+  commentNode: Comment
+  scopeId: string
+}
+
+/**
+ * Registry mapping elements to their comment scope info.
+ */
+export const commentScopeRegistry = new WeakMap<Element, CommentScopeInfo>()
+
+/**
+ * Get the scope ID for an element from the comment scope registry.
+ * Used by createPortal to resolve scope IDs for comment-based scopes.
+ */
+export function getPortalScopeId(element: Element): string | null {
+  const info = commentScopeRegistry.get(element)
+  return info?.scopeId ?? null
+}
+
+/**
+ * Find the end boundary for a comment-based scope.
+ * The boundary is the next bf-scope: comment or the end of the parent's children.
+ */
+export function getCommentScopeBoundary(commentNode: Comment): Node | null {
+  let node: Node | null = commentNode.nextSibling
+  while (node) {
+    if (node.nodeType === Node.COMMENT_NODE &&
+        (node as Comment).nodeValue?.startsWith(BF_SCOPE_COMMENT_PREFIX)) {
+      return node
+    }
+    node = node.nextSibling
+  }
+  return null // End of parent's children
+}