@jay-framework/runtime 0.13.0 → 0.15.0

package/dist/index.d.ts

@@ -18,6 +18,7 @@ declare class Kindergarten {
     private groups;
     constructor(parentNode: Element);
     newGroup(): KindergartenGroup;
+    getGroups(): ReadonlyArray<KindergartenGroup>;
     getOffsetFor(group: KindergartenGroup): number;
 }
 
@@ -567,14 +568,156 @@ declare class ConstructContext<ViewState> {
     private readonly data;
     readonly forStaticElements: boolean;
     private readonly coordinateBase;
-    constructor(data: ViewState, forStaticElements?: boolean, coordinateBase?: Coordinate);
+    private readonly _coordinateMap?;
+    private readonly _rootElement?;
+    private readonly _dataIds;
+    constructor(data: ViewState, forStaticElements?: boolean, coordinateBase?: Coordinate, coordinateMap?: Map<string, Element[]>, rootElement?: Element, dataIds?: Coordinate);
     get currData(): ViewState;
-    /** The accumulated coordinate base (trackBy values from ancestor forEach loops) */
+    /** The accumulated trackBy values from ancestor forEach loops (for __headlessInstances key lookup) */
     get dataIds(): Coordinate;
     coordinate: (refName: string) => Coordinate;
     forItem<ChildViewState>(childViewState: ChildViewState, id: string): ConstructContext<ChildViewState>;
+    /**
+     * Create a child context scoped to a headless instance's coordinate prefix.
+     * Extends coordinateBase for coordinate resolution but does NOT add to dataIds
+     * (instance segments are not trackBy values).
+     */
+    forInstance(instanceCoordinate: string): ConstructContext<ViewState>;
     forAsync<ChildViewState>(childViewState: ChildViewState): ConstructContext<ChildViewState>;
+    /** Whether this context is in hydration mode (adopting existing DOM). */
+    get isHydrating(): boolean;
+    /** The root element being hydrated (undefined in non-hydration mode). */
+    get rootElement(): Element | undefined;
+    /**
+     * Resolve an element by its coordinate key from the hydration map.
+     * The key is scoped by the current coordinateBase — e.g., inside a forEach
+     * item with trackBy "item-1", resolveCoordinate("addBtn") looks up "item-1/addBtn".
+     *
+     * When multiple elements share the same coordinate (e.g., duplicate ref names),
+     * each call returns the next element in document order.
+     */
+    resolveCoordinate(key: string): Element | undefined;
+    /**
+     * Peek at an element by its coordinate key without consuming it.
+     * Used by hydrateForEach to resolve the container element — the same element
+     * is also consumed by the parent adoptElement call (which evaluates after
+     * hydrateForEach due to JavaScript argument evaluation order).
+     */
+    peekCoordinate(key: string): Element | undefined;
     static withRootContext<ViewState, Refs>(viewState: ViewState, refManager: ReferencesManager, elementConstructor: () => BaseJayElement<ViewState>): JayElement<ViewState, Refs>;
+    /**
+     * Hydrate a child component's inline template within the parent's coordinate scope.
+     *
+     * Like withRootContext, but inherits the coordinateBase and coordinateMap from
+     * the current (parent) ConstructContext. This allows adoptElement/adoptText calls
+     * inside the child to resolve coordinates scoped to the child's prefix.
+     *
+     * Used by headless component instances during hydration: the parent pushes a
+     * scoped context (via childCompHydrate), and the child's preRender calls this
+     * method which inherits the scoped coordinateBase.
+     */
+    static withHydrationChildContext<ViewState, Refs>(viewState: ViewState, refManager: ReferencesManager, elementConstructor: () => BaseJayElement<ViewState>): JayElement<ViewState, Refs>;
+    /**
+     * Hydrate existing server-rendered DOM.
+     *
+     * Builds a coordinate→element map from all [jay-coordinate] attributes
+     * inside rootElement, creates a ConstructContext in hydration mode,
+     * pushes it onto the context stack, then calls hydrateConstructor.
+     *
+     * The hydrateConstructor calls adoptText(), adoptElement(), etc. which
+     * read from the context stack — same pattern as element(), dynamicText().
+     * It returns a BaseJayElement whose update/mount/unmount are composed
+     * from all adopted children — same as withRootContext's elementConstructor.
+     */
+    static withHydrationRootContext<ViewState, Refs>(viewState: ViewState, refManager: ReferencesManager, rootElement: Element, hydrateConstructor: () => BaseJayElement<ViewState>): JayElement<ViewState, Refs>;
 }
 
-export { type Attribute, type Attributes, type BaseJayElement, BaseReferencesManager, type ComponentCollectionProxy, ComponentCollectionRefImpl, type ComponentProxy, ComponentRefImpl, ComponentRefsImpl, type Conditional, ConstructContext, type ContextMarker, type Coordinate, type DynamicAttributeOrProperty, EVENT_TRAP, type ElementFrom, type EventEmitter, type EventTypeFrom, type ExtractFastViewState, type ExtractInteractiveViewState, type ExtractProps, type ExtractRefs, type ExtractSlowViewState, type ExtractViewState, type ForEach, GetTrapProxy, type GlobalJayEvents, type HTMLElementCollectionProxy, type HTMLElementCollectionProxyTarget, type HTMLElementProxy, type HTMLElementProxyTarget, type HTMLNativeExec, type HeadLink, type JayComponent, type JayComponentConstructor, type JayContract, type JayElement, type JayEvent, type JayEventHandler, type JayEventHandlerWrapper, type JayLog, type JayNativeEventBuilder, type JayNativeFunction, LogType, type ManagedRefConstructor, ManagedRefType, type ManagedRefs, type MapEventEmitterViewState, type MountFunc, type OnlyEventEmitters, type PreRenderElement, type PrivateRef, type PrivateRefConstructor, PrivateRefs, type PropsFrom, ReferencesManager, type RenderElement, type RenderElementOptions, type TextElement, VIEW_STATE_CHANGE_EVENT, type ViewStateFrom, type When, WhenRole, type WithData, booleanAttribute, childComp, clearGlobalContextRegistry, conditional, createJayContext, currentConstructionContext, defaultEventWrapper, dynamicAttribute, dynamicElement, dynamicElementNS, dynamicProperty, dynamicText, element, findContext, forEach, injectHeadLinks, isCondition, isForEach, isWhen, isWithData, jayLog, mathMLDynamicElement, mathMLElement, mkUpdateCollection, noop, noopMount, noopUpdate, normalizeMount, normalizeUpdates, pending, registerGlobalContext, rejected, resolved, restoreContext, saveContext, slowForEachItem, svgDynamicElement, svgElement, type updateFunc, useContext, useGlobalContext, withContext, withData };
+/**
+ * Sentinel value for static children in adoptDynamicElement.
+ * Represents a child position occupied by a pre-existing DOM node
+ * that has no hydration code (no dynamic text, no dynamic attributes, no refs).
+ */
+declare const STATIC: unique symbol;
+/** Element returned by hydrateForEach/hydrateConditional that needs a group assigned later. */
+type DynamicChild<ViewState> = BaseJayElement<ViewState> & {
+    _setGroup: (group: KindergartenGroup) => void;
+};
+/**
+ * Adopt an existing text node inside the element at the given coordinate.
+ *
+ * Reads the current ConstructContext from the stack (via currentConstructionContext())
+ * to resolve the coordinate to an existing DOM element. Finds the text child at
+ * the given index (by significant-child position) and connects a dynamic text updater.
+ *
+ * - coordinate: element containing the text (or parent in mixed content)
+ * - accessor: (vs) => string | number | boolean
+ * - ref?: optional ref for the element
+ * - childIndex?: index among significant children (default 0). Use when parent has
+ *   mixed content (text + elements); matches element target's positional dynamicText.
+ */
+declare function adoptText<ViewState>(coordinate: string, accessor: (vs: ViewState) => string | number | boolean, ref?: PrivateRef<ViewState, BaseJayElement<ViewState>>, childIndex?: number): BaseJayElement<ViewState>;
+/**
+ * Adopt an existing element at the given coordinate, connecting dynamic
+ * attributes and adopted children to it.
+ *
+ * Hydration counterpart to element() — adopts server-rendered HTML and wires
+ * up dynamic attribute bindings and children.
+ */
+declare function adoptElement<ViewState>(coordinate: string, attributes: Attributes<ViewState>, children?: BaseJayElement<ViewState>[], ref?: PrivateRef<ViewState, BaseJayElement<ViewState>>): BaseJayElement<ViewState>;
+/**
+ * Adopt an existing element that has interactive children (forEach/conditional).
+ *
+ * Creates one Kindergarten per parent, one group per child position.
+ * STATIC sentinels represent children with no hydrate code.
+ * Children with `_setGroup` (forEach/conditional) receive their group via callback.
+ */
+declare function adoptDynamicElement<ViewState>(coordinate: string, attributes: Attributes<ViewState>, children?: (BaseJayElement<ViewState> | typeof STATIC)[], ref?: PrivateRef<ViewState, BaseJayElement<ViewState>>): BaseJayElement<ViewState>;
+/**
+ * Hydration-aware conditional.
+ *
+ * Returns an element with `_setGroup` callback. The parent `adoptDynamicElement`
+ * calls `_setGroup` to assign a KindergartenGroup, which is used for DOM
+ * positioning (ensureNode/removeNode) instead of anchor comments.
+ *
+ * Handles two cases:
+ * - **True at SSR**: Element exists in DOM. Adopt it, register in group, wire toggle.
+ * - **False at SSR**: Element absent. Use createFallback to lazily create when true.
+ */
+declare function hydrateConditional<ViewState>(condition: (vs: ViewState) => boolean, adoptExisting: () => BaseJayElement<ViewState>, createFallback?: () => BaseJayElement<ViewState>): DynamicChild<ViewState>;
+/**
+ * Hydration-aware forEach.
+ *
+ * Adopts existing items that were server-rendered, and creates new items via
+ * the regular element creation path when the list changes.
+ *
+ * Returns an element with `_setGroup` callback. The parent `adoptDynamicElement`
+ * calls `_setGroup` to assign a KindergartenGroup from the parent's Kindergarten,
+ * ensuring correct DOM positioning relative to siblings.
+ *
+ * @param accessor - Function to get the array from the ViewState
+ * @param trackBy - Property name used for item identity (reconciliation key)
+ * @param adoptItem - Called per existing item during hydration (should use adoptText/adoptElement)
+ * @param createItem - Called per new item (regular element()/dynamicText() from generated-element.ts)
+ */
+declare function hydrateForEach<ViewState, Item>(accessor: (vs: ViewState) => Item[], trackBy: string, adoptItem: () => BaseJayElement<Item>[], createItem: (item: Item, id: string) => BaseJayElement<Item>): DynamicChild<ViewState>;
+/**
+ * Hydration-aware child component instantiation.
+ *
+ * Like childComp, but extends the current ConstructContext's coordinateBase
+ * with the instance's coordinate key before calling the component factory.
+ * This scopes coordinate resolution so that adoptElement('0') inside the
+ * child's inline template resolves to '{instanceCoordinate}/0' in the
+ * page's coordinate map.
+ *
+ * Used for headless component instances during hydration. The child
+ * component's preRender calls ConstructContext.withHydrationChildContext()
+ * which inherits the scoped coordinateBase.
+ *
+ * @param compCreator - Component factory (from makeHeadlessInstanceComponent)
+ * @param getProps - Extracts component props from parent ViewState
+ * @param instanceCoordinate - The instance's coordinate key (e.g., 'product-card:0')
+ * @param ref - Optional ref for the component instance
+ */
+declare function childCompHydrate<ParentVS, Props, ChildT, ChildElement extends BaseJayElement<ChildT>, ChildComp extends JayComponent<Props, ChildT, ChildElement>>(compCreator: JayComponentConstructor<Props>, getProps: (t: ParentVS) => Props, instanceCoordinate: string, ref?: PrivateRef<ParentVS, ChildComp>): BaseJayElement<ParentVS>;
+
+export { type Attribute, type Attributes, type BaseJayElement, BaseReferencesManager, type ComponentCollectionProxy, ComponentCollectionRefImpl, type ComponentProxy, ComponentRefImpl, ComponentRefsImpl, type Conditional, ConstructContext, type ContextMarker, type Coordinate, type DynamicAttributeOrProperty, EVENT_TRAP, type ElementFrom, type EventEmitter, type EventTypeFrom, type ExtractFastViewState, type ExtractInteractiveViewState, type ExtractProps, type ExtractRefs, type ExtractSlowViewState, type ExtractViewState, type ForEach, GetTrapProxy, type GlobalJayEvents, type HTMLElementCollectionProxy, type HTMLElementCollectionProxyTarget, type HTMLElementProxy, type HTMLElementProxyTarget, type HTMLNativeExec, type HeadLink, type JayComponent, type JayComponentConstructor, type JayContract, type JayElement, type JayEvent, type JayEventHandler, type JayEventHandlerWrapper, type JayLog, type JayNativeEventBuilder, type JayNativeFunction, LogType, type ManagedRefConstructor, ManagedRefType, type ManagedRefs, type MapEventEmitterViewState, type MountFunc, type OnlyEventEmitters, type PreRenderElement, type PrivateRef, type PrivateRefConstructor, PrivateRefs, type PropsFrom, ReferencesManager, type RenderElement, type RenderElementOptions, STATIC, type TextElement, VIEW_STATE_CHANGE_EVENT, type ViewStateFrom, type When, WhenRole, type WithData, adoptDynamicElement, adoptElement, adoptText, booleanAttribute, childComp, childCompHydrate, clearGlobalContextRegistry, conditional, createJayContext, currentConstructionContext, defaultEventWrapper, dynamicAttribute, dynamicElement, dynamicElementNS, dynamicProperty, dynamicText, element, findContext, forEach, hydrateConditional, hydrateForEach, injectHeadLinks, isCondition, isForEach, isWhen, isWithData, jayLog, mathMLDynamicElement, mathMLElement, mkUpdateCollection, noop, noopMount, noopUpdate, normalizeMount, normalizeUpdates, pending, registerGlobalContext, rejected, resolved, restoreContext, saveContext, slowForEachItem, svgDynamicElement, svgElement, type updateFunc, useContext, useGlobalContext, withContext, withData };

package/dist/index.js

@@ -70,11 +70,18 @@ class Kindergarten {
     this.groups.push(kindergartenGroup);
     return kindergartenGroup;
   }
+  getGroups() {
+    return this.groups;
+  }
   getOffsetFor(group) {
     let index = 0;
     let offset = 0;
     while (index < this.groups.length && this.groups[index] !== group) {
-      offset += this.groups[index].children.size;
+      for (const child of this.groups[index].children) {
+        if (child.parentNode === this.parentNode) {
+          offset++;
+        }
+      }
       index = index + 1;
     }
     return offset;
@@ -168,26 +175,104 @@ function wrapWithModifiedCheck(initialData, baseJayElement) {
   return baseJayElement;
 }
 class ConstructContext {
-  constructor(data, forStaticElements = true, coordinateBase = []) {
+  constructor(data, forStaticElements = true, coordinateBase = [], coordinateMap, rootElement, dataIds) {
+    __publicField(this, "_coordinateMap");
+    __publicField(this, "_rootElement");
+    __publicField(this, "_dataIds");
     __publicField(this, "coordinate", (refName) => {
       return [...this.coordinateBase, refName];
     });
     this.data = data;
     this.forStaticElements = forStaticElements;
     this.coordinateBase = coordinateBase;
+    this._coordinateMap = coordinateMap;
+    this._rootElement = rootElement;
+    this._dataIds = dataIds ?? coordinateBase;
   }
   get currData() {
     return this.data;
   }
-  /** The accumulated coordinate base (trackBy values from ancestor forEach loops) */
+  /** The accumulated trackBy values from ancestor forEach loops (for __headlessInstances key lookup) */
   get dataIds() {
-    return this.coordinateBase;
+    return this._dataIds;
   }
   forItem(childViewState, id) {
-    return new ConstructContext(childViewState, false, [...this.coordinateBase, id]);
+    return new ConstructContext(
+      childViewState,
+      false,
+      [...this.coordinateBase, id],
+      this._coordinateMap,
+      this._rootElement,
+      [...this._dataIds, id]
+    );
+  }
+  /**
+   * Create a child context scoped to a headless instance's coordinate prefix.
+   * Extends coordinateBase for coordinate resolution but does NOT add to dataIds
+   * (instance segments are not trackBy values).
+   */
+  forInstance(instanceCoordinate) {
+    const segments = instanceCoordinate.split("/");
+    return new ConstructContext(
+      this.data,
+      false,
+      [...this.coordinateBase, ...segments],
+      this._coordinateMap,
+      this._rootElement,
+      this._dataIds
+    );
   }
   forAsync(childViewState) {
-    return new ConstructContext(childViewState, false, [...this.coordinateBase]);
+    return new ConstructContext(
+      childViewState,
+      false,
+      [...this.coordinateBase],
+      this._coordinateMap,
+      this._rootElement,
+      this._dataIds
+    );
+  }
+  /** Whether this context is in hydration mode (adopting existing DOM). */
+  get isHydrating() {
+    return this._coordinateMap !== void 0;
+  }
+  /** The root element being hydrated (undefined in non-hydration mode). */
+  get rootElement() {
+    return this._rootElement;
+  }
+  /**
+   * Resolve an element by its coordinate key from the hydration map.
+   * The key is scoped by the current coordinateBase — e.g., inside a forEach
+   * item with trackBy "item-1", resolveCoordinate("addBtn") looks up "item-1/addBtn".
+   *
+   * When multiple elements share the same coordinate (e.g., duplicate ref names),
+   * each call returns the next element in document order.
+   */
+  resolveCoordinate(key) {
+    if (!this._coordinateMap)
+      return void 0;
+    const base = this.coordinateBase.length > 0 ? this.coordinateBase.join("/") : "";
+    const fullKey = base ? key ? base + "/" + key : base : key;
+    const elements = this._coordinateMap.get(fullKey);
+    if (!elements || elements.length === 0)
+      return void 0;
+    return elements.shift();
+  }
+  /**
+   * Peek at an element by its coordinate key without consuming it.
+   * Used by hydrateForEach to resolve the container element — the same element
+   * is also consumed by the parent adoptElement call (which evaluates after
+   * hydrateForEach due to JavaScript argument evaluation order).
+   */
+  peekCoordinate(key) {
+    if (!this._coordinateMap)
+      return void 0;
+    const base = this.coordinateBase.length > 0 ? this.coordinateBase.join("/") : "";
+    const fullKey = base ? key ? base + "/" + key : base : key;
+    const elements = this._coordinateMap.get(fullKey);
+    if (!elements || elements.length === 0)
+      return void 0;
+    return elements[0];
   }
   static withRootContext(viewState, refManager, elementConstructor) {
     let context = new ConstructContext(viewState);
@@ -199,8 +284,82 @@ class ConstructContext {
     element2.mount();
     return refManager.applyToElement(element2);
   }
+  /**
+   * Hydrate a child component's inline template within the parent's coordinate scope.
+   *
+   * Like withRootContext, but inherits the coordinateBase and coordinateMap from
+   * the current (parent) ConstructContext. This allows adoptElement/adoptText calls
+   * inside the child to resolve coordinates scoped to the child's prefix.
+   *
+   * Used by headless component instances during hydration: the parent pushes a
+   * scoped context (via childCompHydrate), and the child's preRender calls this
+   * method which inherits the scoped coordinateBase.
+   */
+  static withHydrationChildContext(viewState, refManager, elementConstructor) {
+    const parentContext = currentConstructionContext();
+    const context = new ConstructContext(
+      viewState,
+      false,
+      parentContext?.coordinateBase || [],
+      parentContext?._coordinateMap,
+      parentContext?._rootElement
+    );
+    const element2 = withContext(
+      CONSTRUCTION_CONTEXT_MARKER,
+      context,
+      () => wrapWithModifiedCheck(currentConstructionContext().currData, elementConstructor())
+    );
+    element2.mount();
+    return refManager.applyToElement(element2);
+  }
+  /**
+   * Hydrate existing server-rendered DOM.
+   *
+   * Builds a coordinate→element map from all [jay-coordinate] attributes
+   * inside rootElement, creates a ConstructContext in hydration mode,
+   * pushes it onto the context stack, then calls hydrateConstructor.
+   *
+   * The hydrateConstructor calls adoptText(), adoptElement(), etc. which
+   * read from the context stack — same pattern as element(), dynamicText().
+   * It returns a BaseJayElement whose update/mount/unmount are composed
+   * from all adopted children — same as withRootContext's elementConstructor.
+   */
+  static withHydrationRootContext(viewState, refManager, rootElement, hydrateConstructor) {
+    const coordinateMap = buildCoordinateMap(rootElement);
+    const context = new ConstructContext(viewState, true, [], coordinateMap, rootElement);
+    const element2 = withContext(CONSTRUCTION_CONTEXT_MARKER, context, () => {
+      const constructed = hydrateConstructor();
+      return wrapWithModifiedCheck(currentConstructionContext().currData, {
+        ...constructed,
+        dom: rootElement
+      });
+    });
+    element2.mount();
+    return refManager.applyToElement(element2);
+  }
 }
-const STYLE = "style";
+function buildCoordinateMap(root) {
+  const map = /* @__PURE__ */ new Map();
+  const addToMap = (key, el) => {
+    const arr = map.get(key);
+    if (arr)
+      arr.push(el);
+    else
+      map.set(key, [el]);
+  };
+  const rootKey = root.getAttribute("jay-coordinate");
+  if (rootKey)
+    addToMap(rootKey, root);
+  const elements = root.querySelectorAll("[jay-coordinate]");
+  for (let i = 0; i < elements.length; i++) {
+    const el = elements[i];
+    const key = el.getAttribute("jay-coordinate");
+    if (key)
+      addToMap(key, el);
+  }
+  return map;
+}
+const STYLE$1 = "style";
 function mkRef(ref, referenced, updates, mounts, unmounts) {
   updates.push(ref.update);
   ref.set(referenced);
@@ -402,7 +561,7 @@ function slowForEachItem(getItems, index, trackByValue, elementCreator) {
 function withData(accessor, elem) {
   return { accessor, elem };
 }
-function applyListChanges(group, instructions) {
+function applyListChanges$1(group, instructions) {
   instructions.forEach((instruction) => {
     if (instruction.action === ITEM_ADDED) {
       group.ensureNode(instruction.elem.dom, instruction.pos);
@@ -447,7 +606,7 @@ function mkUpdateCollection(child, group) {
         }
       );
       lastItemsList = itemsList;
-      applyListChanges(group, instructions);
+      applyListChanges$1(group, instructions);
       itemsList.forEach((value, elem) => elem.update(value));
     }
   };
@@ -624,7 +783,7 @@ function createBaseElement(ns, tagName, attributes, ref) {
   if (ref)
     mkRef(ref, e, updates, mounts, unmounts);
   Object.entries(attributes).forEach(([key, value]) => {
-    if (key === STYLE && e instanceof HTMLElement) {
+    if (key === STYLE$1 && e instanceof HTMLElement) {
       Object.entries(value).forEach(([styleKey, styleValue]) => {
         setAttribute(
           e.style,
@@ -1015,6 +1174,386 @@ class ReferencesManager extends BaseReferencesManager {
     ];
   }
 }
+const STYLE = "style";
+const STATIC = Symbol("STATIC");
+function getSignificantChild(element2, index) {
+  const nodes = element2.childNodes;
+  if (nodes.length <= 1)
+    return nodes[index];
+  let i = 0;
+  for (let j = 0; j < nodes.length; j++) {
+    const node = nodes[j];
+    if (node.nodeType !== Node.TEXT_NODE || (node.textContent || "").trim() !== "") {
+      if (i === index)
+        return node;
+      i++;
+    }
+  }
+  return void 0;
+}
+function adoptText(coordinate, accessor, ref, childIndex) {
+  const context = currentConstructionContext();
+  const element2 = context.peekCoordinate(coordinate);
+  if (!element2) {
+    console.warn(`[jay hydration] adoptText coordinate "${coordinate}" not found in DOM`);
+    return { dom: void 0, update: noopUpdate, mount: noopMount, unmount: noopMount };
+  }
+  const index = childIndex ?? 0;
+  const textNode = getSignificantChild(element2, index);
+  if (!textNode || textNode.nodeType !== Node.TEXT_NODE) {
+    console.warn(
+      `[jay hydration] adoptText(${coordinate}, childIndex=${index}): expected text node`
+    );
+    return { dom: void 0, update: noopUpdate, mount: noopMount, unmount: noopMount };
+  }
+  let content = textNode.textContent ?? "";
+  const updates = [];
+  const mounts = [];
+  const unmounts = [];
+  updates.push((newData) => {
+    const newContent = accessor(newData);
+    if (newContent !== content) {
+      textNode.textContent = String(newContent);
+    }
+    content = newContent;
+  });
+  if (ref) {
+    ref.set(element2);
+    updates.push(ref.update);
+    mounts.push(ref.mount);
+    unmounts.push(ref.unmount);
+  }
+  return {
+    dom: element2,
+    update: normalizeUpdates(updates),
+    mount: normalizeMount(mounts),
+    unmount: normalizeMount(unmounts)
+  };
+}
+const NOOP_ELEMENT = {
+  dom: void 0,
+  update: noopUpdate,
+  mount: noopMount,
+  unmount: noopMount
+};
+function adoptBase(coordinate, attributes, ref) {
+  const context = currentConstructionContext();
+  const element2 = context.resolveCoordinate(coordinate);
+  if (!element2) {
+    console.warn(`[jay hydration] adoptBase coordinate "${coordinate}" not found in DOM`);
+    return null;
+  }
+  const updates = [];
+  const mounts = [];
+  const unmounts = [];
+  if (ref) {
+    ref.set(element2);
+    updates.push(ref.update);
+    mounts.push(ref.mount);
+    unmounts.push(ref.unmount);
+  }
+  Object.entries(attributes).forEach(([key, value]) => {
+    if (typeof value === "object" && value !== null && "valueFunc" in value) {
+      const dynAttr = value;
+      let attrValue = dynAttr.valueFunc(context.currData);
+      if (!(key === STYLE && element2 instanceof HTMLElement)) {
+        updates.push((newData) => {
+          const newAttrValue = dynAttr.valueFunc(newData);
+          if (newAttrValue !== attrValue) {
+            element2.setAttribute(key, newAttrValue);
+          }
+          attrValue = newAttrValue;
+        });
+      }
+    }
+  });
+  return { element: element2, updates, mounts, unmounts };
+}
+function collectChild(child, updates, mounts, unmounts) {
+  if (child.update !== noopUpdate)
+    updates.push(child.update);
+  if (child.mount !== noopMount)
+    mounts.push(child.mount);
+  if (child.unmount !== noopMount)
+    unmounts.push(child.unmount);
+}
+function adoptElement(coordinate, attributes, children = [], ref) {
+  const base = adoptBase(coordinate, attributes, ref);
+  if (!base)
+    return NOOP_ELEMENT;
+  const { element: element2, updates, mounts, unmounts } = base;
+  for (const child of children) {
+    collectChild(child, updates, mounts, unmounts);
+  }
+  return {
+    dom: element2,
+    update: normalizeUpdates(updates),
+    mount: normalizeMount(mounts),
+    unmount: normalizeMount(unmounts)
+  };
+}
+function adoptDynamicElement(coordinate, attributes, children = [], ref) {
+  const base = adoptBase(coordinate, attributes, ref);
+  if (!base)
+    return NOOP_ELEMENT;
+  const { element: element2, updates, mounts, unmounts } = base;
+  const kindergarten = new Kindergarten(element2);
+  const significantChildren = getSignificantChildren(element2);
+  let significantIndex = 0;
+  const staticGroups = [];
+  for (const child of children) {
+    const group = kindergarten.newGroup();
+    if (child === STATIC) {
+      const domNode = significantChildren[significantIndex];
+      if (domNode)
+        group.children.add(domNode);
+      significantIndex++;
+      staticGroups.push(group);
+    } else if ("_setGroup" in child) {
+      child._setGroup(group);
+      collectChild(child, updates, mounts, unmounts);
+    } else {
+      const domNode = significantChildren[significantIndex];
+      if (domNode)
+        group.children.add(domNode);
+      collectChild(child, updates, mounts, unmounts);
+      significantIndex++;
+    }
+  }
+  const dynamicNodes = /* @__PURE__ */ new Set();
+  for (const group of kindergarten.getGroups()) {
+    if (!staticGroups.includes(group)) {
+      for (const child of group.children) {
+        dynamicNodes.add(child);
+      }
+    }
+  }
+  for (const group of staticGroups) {
+    for (const child of group.children) {
+      if (dynamicNodes.has(child)) {
+        group.children.delete(child);
+      }
+    }
+  }
+  return {
+    dom: element2,
+    update: normalizeUpdates(updates),
+    mount: normalizeMount(mounts),
+    unmount: normalizeMount(unmounts)
+  };
+}
+function getSignificantChildren(element2) {
+  const nodes = element2.childNodes;
+  if (nodes.length <= 1)
+    return Array.from(nodes);
+  const result = [];
+  for (let j = 0; j < nodes.length; j++) {
+    const node = nodes[j];
+    if (node.nodeType !== Node.TEXT_NODE || (node.textContent || "").trim() !== "") {
+      result.push(node);
+    }
+  }
+  return result;
+}
+function hydrateConditional(condition, adoptExisting, createFallback) {
+  const context = currentConstructionContext();
+  const savedContext = saveContext();
+  const currData = context.currData;
+  const wasTrue = currData != null && condition(currData);
+  let adopted;
+  if (wasTrue) {
+    adopted = adoptExisting();
+  }
+  let group;
+  let created = wasTrue ? adopted : void 0;
+  let visible = wasTrue;
+  const update = (newData) => {
+    if (!group)
+      return;
+    const result2 = condition(newData);
+    if (!created && result2) {
+      if (wasTrue)
+        ;
+      else if (createFallback) {
+        restoreContext(savedContext, () => {
+          created = wrapWithModifiedCheck(
+            currentConstructionContext().currData,
+            createFallback()
+          );
+        });
+      }
+    }
+    if (result2 && !visible && created) {
+      group.ensureNode(created.dom);
+      created.mount();
+    } else if (!result2 && visible && created) {
+      group.removeNode(created.dom);
+      created.unmount();
+    }
+    if (result2 && created) {
+      created.update(newData);
+    }
+    visible = result2;
+  };
+  const result = {
+    dom: wasTrue && adopted ? adopted.dom : void 0,
+    update,
+    mount: () => {
+      if (created && visible)
+        created.mount();
+    },
+    unmount: () => {
+      if (created && visible)
+        created.unmount();
+    },
+    _setGroup: (g) => {
+      group = g;
+      if (wasTrue && adopted?.dom) {
+        group.children.add(adopted.dom);
+      }
+      if (created && visible && !wasTrue) {
+        group.ensureNode(created.dom);
+      }
+    }
+  };
+  return result;
+}
+function hydrateForEach(accessor, trackBy, adoptItem, createItem) {
+  const context = currentConstructionContext();
+  const savedContext = saveContext();
+  const parentContext = context;
+  const initialItems = accessor(context.currData) || [];
+  const adoptedItems = [];
+  for (const item of initialItems) {
+    const id = String(item[trackBy]);
+    const itemDom = context.resolveCoordinate(id);
+    const childContext = context.forItem(item, id);
+    const adopted = withContext(CONSTRUCTION_CONTEXT_MARKER, childContext, () => {
+      const elements = adoptItem();
+      const updates = [];
+      const mounts = [];
+      const unmounts = [];
+      for (const el of elements) {
+        if (el.update !== noopUpdate)
+          updates.push(el.update);
+        if (el.mount !== noopMount)
+          mounts.push(el.mount);
+        if (el.unmount !== noopMount)
+          unmounts.push(el.unmount);
+      }
+      return {
+        dom: itemDom || elements[0]?.dom,
+        update: normalizeUpdates(updates),
+        mount: normalizeMount(mounts),
+        unmount: normalizeMount(unmounts)
+      };
+    });
+    adoptedItems.push(adopted);
+  }
+  let group;
+  let lastItems = initialItems;
+  let lastItemsList = new RandomAccessLinkedList(initialItems, trackBy);
+  for (let i = 0; i < initialItems.length; i++) {
+    const id = String(initialItems[i][trackBy]);
+    const node = lastItemsList.get(id);
+    if (node) {
+      node.attach = adoptedItems[i];
+    }
+  }
+  const mount = () => {
+    lastItemsList.forEach((_value, elem) => {
+      if (elem && elem.mount !== noopMount)
+        elem.mount();
+    });
+  };
+  const unmount = () => {
+    lastItemsList.forEach((_value, elem) => {
+      if (elem && elem.unmount !== noopMount)
+        elem.unmount();
+    });
+  };
+  const update = (newData) => {
+    if (!group)
+      return;
+    const items = accessor(newData) || [];
+    const isModified = items !== lastItems;
+    lastItems = items;
+    if (isModified) {
+      const itemsList = new RandomAccessLinkedList(items, trackBy);
+      const instructions = listCompare(
+        lastItemsList,
+        itemsList,
+        (item, id) => {
+          const childContext = parentContext.forItem(item, id);
+          return restoreContext(
+            savedContext,
+            () => withContext(
+              CONSTRUCTION_CONTEXT_MARKER,
+              childContext,
+              () => wrapWithModifiedCheck(
+                currentConstructionContext().currData,
+                createItem(item, id)
+              )
+            )
+          );
+        }
+      );
+      lastItemsList = itemsList;
+      applyListChanges(group, instructions);
+      itemsList.forEach((value, elem) => elem.update(value));
+    }
+  };
+  const result = {
+    dom: void 0,
+    update,
+    mount,
+    unmount,
+    _setGroup: (g) => {
+      group = g;
+      for (const adopted of adoptedItems) {
+        if (adopted.dom) {
+          group.children.add(adopted.dom);
+        }
+      }
+    }
+  };
+  return result;
+}
+function childCompHydrate(compCreator, getProps, instanceCoordinate, ref) {
+  const context = currentConstructionContext();
+  const childContext = context.forInstance(instanceCoordinate);
+  return withContext(CONSTRUCTION_CONTEXT_MARKER, childContext, () => {
+    const childComp2 = compCreator(getProps(context.currData));
+    const updates = [(t) => childComp2.update(getProps(t))];
+    const mounts = [childComp2.mount];
+    const unmounts = [childComp2.unmount];
+    if (ref) {
+      updates.push(ref.update);
+      ref.set(childComp2);
+      mounts.push(ref.mount);
+      unmounts.push(ref.unmount);
+    }
+    return {
+      dom: childComp2.element.dom,
+      update: normalizeUpdates(updates),
+      mount: normalizeMount(mounts),
+      unmount: normalizeMount(unmounts)
+    };
+  });
+}
+function applyListChanges(group, instructions) {
+  instructions.forEach((instruction) => {
+    if (instruction.action === ITEM_ADDED) {
+      group.ensureNode(instruction.elem.dom, instruction.pos);
+      instruction.elem.mount();
+    } else if (instruction.action === ITEM_REMOVED) {
+      group.removeNodeAt(instruction.pos);
+      instruction.elem.unmount();
+    } else {
+      group.moveNode(instruction.fromPos, instruction.pos);
+    }
+  });
+}
 export {
   BaseReferencesManager,
   ComponentCollectionRefImpl,
@@ -1027,10 +1566,15 @@ export {
   ManagedRefType,
   PrivateRefs,
   ReferencesManager,
+  STATIC,
   VIEW_STATE_CHANGE_EVENT,
   WhenRole,
+  adoptDynamicElement,
+  adoptElement,
+  adoptText,
   booleanAttribute,
   childComp,
+  childCompHydrate,
   clearGlobalContextRegistry,
   conditional,
   createJayContext,
@@ -1044,6 +1588,8 @@ export {
   element,
   findContext,
   forEach,
+  hydrateConditional,
+  hydrateForEach,
   injectHeadLinks,
   isCondition,
   isForEach,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jay-framework/runtime",
-  "version": "0.13.0",
+  "version": "0.15.0",
   "type": "module",
   "license": "Apache-2.0",
   "main": "dist/index.js",
@@ -23,11 +23,11 @@
     "test:watch": "vitest"
   },
   "dependencies": {
-    "@jay-framework/list-compare": "^0.13.0",
-    "@jay-framework/reactive": "^0.13.0"
+    "@jay-framework/list-compare": "^0.15.0",
+    "@jay-framework/reactive": "^0.15.0"
   },
   "devDependencies": {
-    "@jay-framework/dev-environment": "^0.13.0",
+    "@jay-framework/dev-environment": "^0.15.0",
     "@testing-library/jest-dom": "^6.2.0",
     "@types/jsdom": "^21.1.6",
     "@types/node": "^20.11.5",