@xaendar/core 0.6.20 → 0.7.0

package/dist/xaendar-core.es.d.ts

@@ -85,7 +85,7 @@ export declare type BaseWebComponentConstructor = Constructor<BaseWebComponent,
  */
 declare type Block = {
     condition?: NoArgsFunction<boolean>;
-    block: Function_2<[HTMLElement, Context], Context>;
+    block: Function_2<[HTMLElement, Context, Node | null], Context>;
 };
 
 /**
@@ -131,7 +131,16 @@ export declare class Context {
      */
     private _children;
     /**
-     * DOM nodes owned by this context, tracked for cleanup on destruction.
+     * Map containing the run time values of variables defines during the run time execution
+     * (e.g. {@for} variables: 'index', 'item', etc...)
+     */
+    private _variables;
+    /**
+     * DOM nodes directly mounted into this scope via {@link mountNode} (does not
+     * include nodes owned by child contexts). Used to determine, for a given
+     * context, which DOM nodes belong to it — for example so `_for`'s keyed
+     * diffing can move a reused item's nodes to a new position without
+     * recreating them.
      */
     private _nodes;
     /**
@@ -144,10 +153,24 @@ export declare class Context {
      * Creates a new scope context.
      *
      * @param _root - Web component reference used to resolve property and method bindings.
-     * @param _parent - Optional parent context representing the enclosing scope.
-     * @param _identifiers - Named identifier bindings declared in this scope.
      */
     constructor(_root: BaseWebComponent, _parent: Context);
+    /**
+     * Registers a new identifier name in this scope.
+     *
+     * @param name - The identifier name to register.
+     * @throws When an identifier with the same name is already declared in this scope.
+     */
+    addIdentifier(name: string, value: unknown): void;
+    removeIdentifier(name: string): void;
+    /**
+     * Returns `true` if an identifier with the given name is declared in this
+     * scope or any of its ancestor scopes.
+     *
+     * @param name - The identifier name to look up.
+     * @returns `true` if the identifier exists in the scope chain, `false` otherwise.
+     */
+    get(name: string): unknown;
     /**
      * Returns the event handler method bound to the root component instance.
      *
@@ -168,7 +191,7 @@ export declare class Context {
      */
     removeChild(context: Context): void;
     /**
-     * Registers a DOM node as owned by this context.
+     * Registers a DOM node as directly owned by this context.
      *
      * @param node - The DOM node to track.
      */
@@ -179,6 +202,13 @@ export declare class Context {
      * @param nodeToRemove - The DOM node to untrack.
      */
     removeNode(nodeToRemove: Node): void;
+    /**
+     * Returns the DOM nodes directly owned by this context (not recursively
+     * including nodes owned by child contexts), in mount order. Used by
+     * `_for`'s keyed diffing to locate a reused item's nodes so they can be
+     * repositioned with `insertBefore` instead of being destroyed and recreated.
+     */
+    getNodes(): ReadonlyArray<Node>;
     /**
      * Registers one or more cleanup functions to be called when this context is destroyed.
      *
@@ -198,6 +228,25 @@ export declare class Context {
     unlisten(): void;
 }
 
+/**
+ * Creates a Comment node used as a positional placeholder for dynamic content
+ * (`_if`, `_for`). It is inserted immediately, in order, and stays in place for
+ * the entire lifetime of the given `context`: any future insertion of dynamic
+ * content is done via `insertBefore(node, anchor)`, guaranteeing the correct
+ * position even when sibling constructs update independently and asynchronously.
+ *
+ * @param label - Textual label for the comment, useful for debugging to visually
+ *   distinguish in the DOM which construct (if/for) generated the anchor.
+ * @param parentNode - The parent HTML element the anchor is inserted into.
+ * @param context - The Context the anchor is bound to: it determines the anchor's
+ *   lifecycle, since it will be removed from the DOM when this context is destroyed.
+ * @param referenceNode - The node to insert the anchor relative to (same semantics
+ *   as `Node.insertBefore`). If `null`, the anchor is appended at the end of `parentNode`.
+ * @returns The created Comment node, to be used as the reference point for future
+ *   insertions of dynamic content via `insertBefore(node, anchor)`.
+ */
+export declare function createAnchor(label: string, parentNode: HTMLElement, context: Context, referenceNode?: Comment | null): Comment;
+
 /**
  * Runs a side-effectful function and automatically re-runs it whenever any
  * Signal read during its execution changes.
@@ -267,16 +316,27 @@ export { Event_2 as Event }
 export declare type EventOptions = Beautify<RequireOne<Omit<CustomEventInit, 'detail'>>>;
 
 /**
- * Reactively iterates over a list of items, re-running the loop whenever the tracked condition changes.
- * Previous iteration side-effects are cleaned up before each re-evaluation.
- *
- * @param parentNode - The parent HTML element where the conditional structure is applied.
- * @param parentContext - The parent Context object containing all the variables definition from the Parent Closure
- * @param condition - A reactive function that returns the array of items to iterate over.
- * @param trackExpression - An expression used to identify univocally single iterations to not duplicate DOM elements between different renders
- * @param forFn - A callback invoked for each item, receiving the parent node, the item, and its index. Must return an array of cleanup functions.
+ * Reactively iterates over a list of items. Items are matched across re-runs
+ * by the key produced by `trackExpression`:
+ * - key sopravvive → il Context e l'intero sottoalbero (stato, subscription,
+ *   richieste pendenti) vengono riusati SEMPRE, indipendentemente da un
+ *   eventuale cambio di indice: si spostano solo i nodi DOM, e se il body usa
+ *   $index/$first/$last/$even/$odd questi vengono aggiornati in-place tramite
+ *   `update`, senza ricreare nulla.
+ * - key sparita → il Context viene distrutto.
+ * - key nuova → il Context viene creato.
+ *
+ * @param forFn - Callback invocata per creare un nuovo item. Deve ritornare
+ *   sia il Context che possiede i nodi, sia (opzionalmente) una funzione
+ *   `update` per aggiornare le variabili implicite in-place quando l'item
+ *   viene riusato a un indice diverso.
  */
-export declare function _for(parentNode: HTMLElement, parentContext: Context, condition: () => unknown[], trackExpression: Function_2<[unknown], string | number>, forFn: Function_2<[parentNode: HTMLElement, context: Context, items: unknown[], index: number], Context>): void;
+export declare function _for(parentNode: HTMLElement, parentContext: Context, condition: () => unknown[], trackExpression: Function_2<[unknown], ForKey>, forFn: Function_2<[HTMLElement, Context, unknown[], number, Node | null], {
+    context: Context;
+    update?: (newIndex: number, items: unknown[]) => void;
+}>): void;
+
+declare type ForKey = string | number;
 
 /**
  * Creates a reactive conditional structure from a list of branches.
@@ -294,9 +354,6 @@ export declare function _for(parentNode: HTMLElement, parentContext: Context, co
  *
  * @param parentNode - The parent HTML element where the conditional structure is applied.
  * @param parentContext - The parent Context object containing all the variables definition from the Parent Closure
- * @param unwatchFns - Shared array that collects all active cleanup functions.
- *   Mutated in place: the created effect and branch functions are added to and
- *   removed from this array.
  * @param blocks - Ordered list of conditional branches to evaluate.
  */
 export declare function _if(parentNode: HTMLElement, parentContext: Context, blocks: Block[]): void;
@@ -367,34 +424,47 @@ export declare type InputSignalOptions<ActualValue = unknown, IncomingValue = Ac
 
 /**
  * Builds a record of iteration context variables for a given index in the loop.
- * Provides the current item, index, and convenience flags (`$first`, `$last`, `$even`, `$odd`).
+ * `item` is a plain value (identity-stable across moves thanks to the key),
+ * while `$index`/`$first`/`$last`/`$even`/`$odd` are signals: when an item is
+ * moved to a different position in the array, `update()` writes the new
+ * values into these signals in place, instead of recreating the item's
+ * template output. Anything bound to these variables re-runs reactively;
+ * everything else in the item's subtree (state, subscriptions, pending
+ * requests) is left completely untouched.
  *
  * @param items - The full array being iterated.
  * @param index - The current iteration index.
- * @param itemName - The identifier to reference the i-th item during iteration
- * @param aliases - Aliases for implicit variables defined in the `{@for} loop`
- * @returns A record mapping alias names and built-in variables to their values.
+ * @param itemName - The identifier to reference the i-th item during iteration.
+ * @param aliases - Aliases for implicit variables defined in the `@for` loop.
+ * @returns A handle exposing the resolved variables and an `update` function.
  */
-export declare function _iterationVariables(items: unknown[], index: number, itemName: string, aliases: {
+export declare function _iterationVariables(context: Context, items: unknown[], index: number, itemName: string, aliases: {
     $index: string;
     $first: string;
     $last: string;
     $even: string;
     $odd: string;
-}): Record<string, unknown>;
+}): IterationVariablesHandle;
+
+declare type IterationVariablesHandle = {
+    vars: Record<string, unknown>;
+    update: (newIndex: number, items: unknown[]) => void;
+};
 
 /**
  * Mounts a node into the DOM and binds it to the context lifecycle.
  *
- * Registers the node with the context, appends it to `parentNode`, and
- * schedules a cleanup listener that removes the node from both the context
- * and the DOM when the context is destroyed.
+ * Registers the node with the context, inserts it into `parentNode` at the
+ * given position, and schedules a cleanup listener that removes the node
+ * from both the context and the DOM when the context is destroyed.
  *
  * @param node - The node to mount.
- * @param parentNode - The parent HTML element to append the node to.
+ * @param parentNode - The parent HTML element to insert the node into.
  * @param context - The current template execution scope that owns the node's lifecycle.
+ * @param referenceNode - The node to insert relative to (same semantics
+ *   as `Node.insertBefore`). If `null`, the node is appended at the end of `parentNode`.
  */
-export declare function mountNode(node: Node, parentNode: HTMLElement, context: Context): void;
+export declare function mountNode(node: Node, parentNode: HTMLElement, context: Context, referenceNode?: Comment | null): void;
 
 /**
  * Represents the output type returned by an `@Event` decorator in a web component.
@@ -485,7 +555,7 @@ declare type PropertyDecoratorOptionsWithRequired<ActualValue = unknown, Incomin
  * @param events - List of event listener descriptors to attach to the element.
  * @returns The newly created HTML element.
  */
-export declare function _renderElement(parentNode: HTMLElement, context: Context, tagName: string, attributes: RenderElementAttribute[], events: RenderElementEvent[]): HTMLElement;
+export declare function _renderElement(parentNode: HTMLElement, context: Context, anchor: Comment | null, tagName: string, attributes: RenderElementAttribute[], events: RenderElementEvent[]): HTMLElement;
 
 /**
  * Describes a single HTML attribute to be applied to a rendered DOM element.
@@ -606,8 +676,6 @@ export { Signal_2 as Signal }
  *
  * @param parentNode - The parent HTML element where the conditional structure is applied.
  * @param parentContext - The parent Context object containing all the variables definition from the Parent Closure
- * @param unwatchFns - Shared array that collects all active cleanup functions.
- *   Mutated in place by the underlying {@link _if} call.
  * @param expression - Function that evaluates the switch expression. Called
  *   reactively inside an effect so that signal reads are tracked.
  * @param blocks - Ordered list of case branches. Each entry contains:
@@ -618,7 +686,7 @@ export { Signal_2 as Signal }
  */
 export declare function _switch(parentNode: HTMLElement, parentContext: Context, expression: NoArgsFunction<unknown>, blocks: Array<{
     condition: unknown[] | null;
-    block: Function_2<[HTMLElement, Context], Context>;
+    block: Function_2<[HTMLElement, Context, Node | null], Context>;
 }>): void;
 
 /**

package/dist/xaendar-core.es.js

@@ -507,8 +507,17 @@ var Context = class {
 	* Child contexts representing nested scopes (e.g. `@for` loop iterations, `@if` branches). 
 	*/
 	_children = new Array();
-	/** 
-	* DOM nodes owned by this context, tracked for cleanup on destruction. 
+	/**
+	* Map containing the run time values of variables defines during the run time execution
+	* (e.g. {@for} variables: 'index', 'item', etc...)
+	*/
+	_variables = /* @__PURE__ */ new Map();
+	/**
+	* DOM nodes directly mounted into this scope via {@link mountNode} (does not
+	* include nodes owned by child contexts). Used to determine, for a given
+	* context, which DOM nodes belong to it — for example so `_for`'s keyed
+	* diffing can move a reused item's nodes to a new position without
+	* recreating them.
 	*/
 	_nodes = new Array();
 	/**
@@ -521,14 +530,35 @@ var Context = class {
 	* Creates a new scope context.
 	*
 	* @param _root - Web component reference used to resolve property and method bindings.
-	* @param _parent - Optional parent context representing the enclosing scope.
-	* @param _identifiers - Named identifier bindings declared in this scope.
 	*/
 	constructor(_root, _parent) {
 		this._root = _root;
 		this._parent = _parent;
 	}
 	/**
+	* Registers a new identifier name in this scope.
+	*
+	* @param name - The identifier name to register.
+	* @throws When an identifier with the same name is already declared in this scope.
+	*/
+	addIdentifier(name, value) {
+		if (this._variables.has(name)) throw new Error(`Identifier "${name}" is already declared in this scope.`);
+		this._variables.set(name, value);
+	}
+	removeIdentifier(name) {
+		this._variables.delete(name);
+	}
+	/**
+	* Returns `true` if an identifier with the given name is declared in this
+	* scope or any of its ancestor scopes.
+	*
+	* @param name - The identifier name to look up.
+	* @returns `true` if the identifier exists in the scope chain, `false` otherwise.
+	*/
+	get(name) {
+		return this._variables.has(name) ? this._variables.get(name) : this._parent?.get(name);
+	}
+	/**
 	* Returns the event handler method bound to the root component instance.
 	*
 	* @param handler - The name of the method on the root component to retrieve.
@@ -551,10 +581,10 @@ var Context = class {
 	* @param context - The child context to remove.
 	*/
 	removeChild(context) {
-		this._children = this._children.filter((child) => child === context);
+		this._children = this._children.filter((child) => child !== context);
 	}
 	/**
-	* Registers a DOM node as owned by this context.
+	* Registers a DOM node as directly owned by this context.
 	*
 	* @param node - The DOM node to track.
 	*/
@@ -567,7 +597,16 @@ var Context = class {
 	* @param nodeToRemove - The DOM node to untrack.
 	*/
 	removeNode(nodeToRemove) {
-		this._nodes = this._nodes.filter((node) => node === nodeToRemove);
+		this._nodes = this._nodes.filter((node) => node !== nodeToRemove);
+	}
+	/**
+	* Returns the DOM nodes directly owned by this context (not recursively
+	* including nodes owned by child contexts), in mount order. Used by
+	* `_for`'s keyed diffing to locate a reused item's nodes so they can be
+	* repositioned with `insertBefore` instead of being destroyed and recreated.
+	*/
+	getNodes() {
+		return this._nodes;
 	}
 	/**
 	* Registers one or more cleanup functions to be called when this context is destroyed.
@@ -591,79 +630,149 @@ var Context = class {
 		this._unwatchFns.forEach((fn) => fn());
 		this._children.forEach((child) => child.unlisten());
 		this._unwatchFns = [];
+		this._children = [];
 		this._nodes = [];
+		this._variables.clear();
 	}
 };
 /**
 * Mounts a node into the DOM and binds it to the context lifecycle.
 *
-* Registers the node with the context, appends it to `parentNode`, and
-* schedules a cleanup listener that removes the node from both the context
-* and the DOM when the context is destroyed.
+* Registers the node with the context, inserts it into `parentNode` at the
+* given position, and schedules a cleanup listener that removes the node
+* from both the context and the DOM when the context is destroyed.
 *
 * @param node - The node to mount.
-* @param parentNode - The parent HTML element to append the node to.
+* @param parentNode - The parent HTML element to insert the node into.
 * @param context - The current template execution scope that owns the node's lifecycle.
+* @param referenceNode - The node to insert relative to (same semantics
+*   as `Node.insertBefore`). If `null`, the node is appended at the end of `parentNode`.
 */
-function mountNode(node, parentNode, context) {
+function mountNode(node, parentNode, context, referenceNode = null) {
 	context.addNode(node);
-	parentNode.appendChild(node);
+	parentNode.insertBefore(node, referenceNode);
 	context.listen(() => {
 		context.removeNode(node);
-		parentNode.removeChild(node);
+		if (node.parentNode === parentNode) parentNode.removeChild(node);
 	});
 }
+/**
+* Creates a Comment node used as a positional placeholder for dynamic content
+* (`_if`, `_for`). It is inserted immediately, in order, and stays in place for
+* the entire lifetime of the given `context`: any future insertion of dynamic
+* content is done via `insertBefore(node, anchor)`, guaranteeing the correct
+* position even when sibling constructs update independently and asynchronously.
+*
+* @param label - Textual label for the comment, useful for debugging to visually
+*   distinguish in the DOM which construct (if/for) generated the anchor.
+* @param parentNode - The parent HTML element the anchor is inserted into.
+* @param context - The Context the anchor is bound to: it determines the anchor's
+*   lifecycle, since it will be removed from the DOM when this context is destroyed.
+* @param referenceNode - The node to insert the anchor relative to (same semantics
+*   as `Node.insertBefore`). If `null`, the anchor is appended at the end of `parentNode`.
+* @returns The created Comment node, to be used as the reference point for future
+*   insertions of dynamic content via `insertBefore(node, anchor)`.
+*/
+function createAnchor(label, parentNode, context, referenceNode = null) {
+	const anchor = document.createComment(label);
+	mountNode(anchor, parentNode, context, referenceNode);
+	return anchor;
+}
 //#endregion
 //#region ../packages/core/src/utils/for.util.ts
 /**
-* Reactively iterates over a list of items, re-running the loop whenever the tracked condition changes.
-* Previous iteration side-effects are cleaned up before each re-evaluation.
-*
-* @param parentNode - The parent HTML element where the conditional structure is applied.
-* @param parentContext - The parent Context object containing all the variables definition from the Parent Closure
-* @param condition - A reactive function that returns the array of items to iterate over.
-* @param trackExpression - An expression used to identify univocally single iterations to not duplicate DOM elements between different renders
-* @param forFn - A callback invoked for each item, receiving the parent node, the item, and its index. Must return an array of cleanup functions.
+* Reactively iterates over a list of items. Items are matched across re-runs
+* by the key produced by `trackExpression`:
+* - key sopravvive → il Context e l'intero sottoalbero (stato, subscription,
+*   richieste pendenti) vengono riusati SEMPRE, indipendentemente da un
+*   eventuale cambio di indice: si spostano solo i nodi DOM, e se il body usa
+*   $index/$first/$last/$even/$odd questi vengono aggiornati in-place tramite
+*   `update`, senza ricreare nulla.
+* - key sparita → il Context viene distrutto.
+* - key nuova → il Context viene creato.
+*
+* @param forFn - Callback invocata per creare un nuovo item. Deve ritornare
+*   sia il Context che possiede i nodi, sia (opzionalmente) una funzione
+*   `update` per aggiornare le variabili implicite in-place quando l'item
+*   viene riusato a un indice diverso.
 */
 function _for(parentNode, parentContext, condition, trackExpression, forFn) {
-	let contexts = new Array();
+	const anchor = createAnchor("for", parentNode, parentContext);
+	let entries = /* @__PURE__ */ new Map();
 	const unlistener = effect(() => {
-		contexts.forEach((context) => {
-			context.unlisten();
-			parentContext.removeChild(context);
-		});
-		contexts = [];
 		const items = condition();
+		const newKeys = items.map((item) => trackExpression(item));
+		const newKeySet = new Set(newKeys);
 		untracked(() => {
-			for (let i = 0; i < items.length; i++) {
-				const context = forFn(parentNode, parentContext, items, i);
-				contexts.push(context);
-				parentContext.addChild(context);
+			const newEntries = /* @__PURE__ */ new Map();
+			for (const [key, entry] of entries) if (!newKeySet.has(key)) {
+				entry.context.unlisten();
+				parentContext.removeChild(entry.context);
 			}
+			let nextReference = anchor;
+			for (let i = items.length - 1; i >= 0; i--) {
+				const key = newKeys[i];
+				const existing = entries.get(key);
+				let entry;
+				if (existing) {
+					const nodes = existing.context.getNodes();
+					if (nodes[nodes.length - 1]?.nextSibling !== nextReference) nodes.forEach((node) => parentNode.insertBefore(node, nextReference));
+					existing.update?.(i, items);
+					entry = existing;
+				} else {
+					const created = forFn(parentNode, parentContext, items, i, nextReference);
+					parentContext.addChild(created.context);
+					entry = created;
+				}
+				newEntries.set(key, entry);
+				nextReference = entry.context.getNodes()[0] ?? nextReference;
+			}
+			entries = newEntries;
 		});
 	});
 	parentContext.listen(unlistener);
 }
 /**
 * Builds a record of iteration context variables for a given index in the loop.
-* Provides the current item, index, and convenience flags (`$first`, `$last`, `$even`, `$odd`).
+* `item` is a plain value (identity-stable across moves thanks to the key),
+* while `$index`/`$first`/`$last`/`$even`/`$odd` are signals: when an item is
+* moved to a different position in the array, `update()` writes the new
+* values into these signals in place, instead of recreating the item's
+* template output. Anything bound to these variables re-runs reactively;
+* everything else in the item's subtree (state, subscriptions, pending
+* requests) is left completely untouched.
 *
 * @param items - The full array being iterated.
 * @param index - The current iteration index.
-* @param itemName - The identifier to reference the i-th item during iteration
-* @param aliases - Aliases for implicit variables defined in the `{@for} loop`
-* @returns A record mapping alias names and built-in variables to their values.
+* @param itemName - The identifier to reference the i-th item during iteration.
+* @param aliases - Aliases for implicit variables defined in the `@for` loop.
+* @returns A handle exposing the resolved variables and an `update` function.
 */
-function _iterationVariables(items, index, itemName, aliases) {
-	const even = index % 2 === 0;
-	return {
-		[itemName]: items[index],
-		[aliases.$index]: index,
-		[aliases.$first]: index === 0,
-		[aliases.$last]: index === items.length - 1,
-		[aliases.$even]: even,
-		[aliases.$odd]: !even
+function _iterationVariables(context, items, index, itemName, aliases) {
+	const $index = signal(index);
+	const $first = signal(index === 0);
+	const $last = signal(index === items.length - 1);
+	const $even = signal(index % 2 === 0);
+	const $odd = signal(index % 2 !== 0);
+	const retVal = {
+		vars: {
+			[itemName]: items[index],
+			[aliases.$index]: $index,
+			[aliases.$first]: $first,
+			[aliases.$last]: $last,
+			[aliases.$even]: $even,
+			[aliases.$odd]: $odd
+		},
+		update(newIndex, newItems) {
+			$index.set(newIndex);
+			$first.set(newIndex === 0);
+			$last.set(newIndex === newItems.length - 1);
+			$even.set(newIndex % 2 === 0);
+			$odd.set(newIndex % 2 !== 0);
+		}
 	};
+	Object.entries(retVal.vars).forEach(([key, value]) => context.addIdentifier(key, value));
+	return retVal;
 }
 //#endregion
 //#region ../packages/core/src/utils/if.util.ts
@@ -683,31 +792,22 @@ function _iterationVariables(items, index, itemName, aliases) {
 *
 * @param parentNode - The parent HTML element where the conditional structure is applied.
 * @param parentContext - The parent Context object containing all the variables definition from the Parent Closure
-* @param unwatchFns - Shared array that collects all active cleanup functions.
-*   Mutated in place: the created effect and branch functions are added to and
-*   removed from this array.
 * @param blocks - Ordered list of conditional branches to evaluate.
 */
 function _if(parentNode, parentContext, blocks) {
+	const anchor = createAnchor("if", parentNode, parentContext);
 	let state;
 	let fn;
 	switch (blocks.length) {
 		case 1:
-			fn = (state) => handleIf(parentNode, parentContext, blocks[0], state);
+			fn = (state) => handleIf(parentNode, parentContext, blocks[0], state, anchor);
 			break;
 		case 2:
-			fn = (state) => handleIfElse(parentNode, parentContext, blocks[0], blocks[1], state);
+			fn = (state) => handleIfElse(parentNode, parentContext, blocks[0], blocks[1], state, anchor);
 			break;
-		default: fn = (state) => handleIfElseIf(parentNode, parentContext, blocks, state);
+		default: fn = (state) => handleIfElseIf(parentNode, parentContext, blocks, state, anchor);
 	}
-	const unlistener = effect(() => {
-		if (state) {
-			state.context.unlisten();
-			parentContext.removeChild(state.context);
-		}
-		state = fn(state);
-		if (state) parentContext.addChild(state.context);
-	});
+	const unlistener = effect(() => state = fn(state));
 	parentContext.listen(unlistener);
 }
 /**
@@ -724,13 +824,9 @@ function _if(parentNode, parentContext, blocks) {
 * @returns The new state and new cleanup functions if the active branch changed,
 *   otherwise `undefined`.
 */
-function handleIf(parentNode, parentContext, ifBlock, state) {
-	if (ifBlock.condition()) return checkAndUpdateState(parentNode, parentContext, state, 0, ifBlock.block);
-	else if (state) {
-		const context = state.context;
-		context.unlisten();
-		parentContext.removeChild(context);
-	}
+function handleIf(parentNode, parentContext, ifBlock, state, anchor) {
+	if (ifBlock.condition()) return checkAndUpdateState(parentNode, parentContext, state, 0, ifBlock.block, anchor);
+	teardown(parentContext, state);
 }
 /**
 * Handles the `if` / `else` case (exactly two branches).
@@ -746,8 +842,8 @@ function handleIf(parentNode, parentContext, ifBlock, state) {
 * @returns The new state and new cleanup functions if the active branch changed,
 *   otherwise `undefined`.
 */
-function handleIfElse(parentNode, parentContext, ifBlock, elseBlock, state) {
-	return ifBlock.condition() ? checkAndUpdateState(parentNode, parentContext, state, 0, ifBlock.block) : checkAndUpdateState(parentNode, parentContext, state, 1, elseBlock.block);
+function handleIfElse(parentNode, parentContext, ifBlock, elseBlock, state, anchor) {
+	return ifBlock.condition() ? checkAndUpdateState(parentNode, parentContext, state, 0, ifBlock.block, anchor) : checkAndUpdateState(parentNode, parentContext, state, 1, elseBlock.block, anchor);
 }
 /**
 * Handles the general case of an `if` / `else if` / ... / `else` chain (three or more branches).
@@ -763,10 +859,10 @@ function handleIfElse(parentNode, parentContext, ifBlock, elseBlock, state) {
 * @returns The new state and new cleanup functions if the active branch changed,
 *   otherwise `undefined`. Also returns `undefined` if no branch matches.
 */
-function handleIfElseIf(parentNode, parentContext, blocks, state) {
+function handleIfElseIf(parentNode, parentContext, blocks, state, anchor) {
 	for (let i = 0; i < blocks.length; i++) {
 		const { condition, block } = blocks[i];
-		if (!condition || condition()) return checkAndUpdateState(parentNode, parentContext, state, i, block);
+		if (!condition || condition()) return checkAndUpdateState(parentNode, parentContext, state, i, block, anchor);
 	}
 }
 /**
@@ -789,13 +885,34 @@ function handleIfElseIf(parentNode, parentContext, blocks, state) {
 * @returns The updated state if the active branch changed, or `undefined` if the branch
 *   is unchanged.
 */
-function checkAndUpdateState(parentNode, parentContext, state, newState, conditionalBlockFn) {
-	if (state?.activeBranch !== newState) {
-		state?.context.unlisten();
-		return {
-			activeBranch: newState,
-			context: untracked(() => conditionalBlockFn(parentNode, parentContext))
-		};
+function checkAndUpdateState(parentNode, parentContext, state, newState, conditionalBlockFn, anchor) {
+	if (state?.activeBranch === newState) return state;
+	if (state) {
+		state.context.unlisten();
+		parentContext.removeChild(state.context);
+	}
+	const context = untracked(() => conditionalBlockFn(parentNode, parentContext, anchor));
+	parentContext.addChild(context);
+	return {
+		activeBranch: newState,
+		context
+	};
+}
+/**
+* Handles the case where no branch condition matched: tears down the previously
+* active branch, if one existed, by unlistening its context (running cleanup
+* functions and destroying its subtree) and detaching it from the parent context.
+* A no-op if no branch was previously active.
+*
+* @param parentContext - The parent Context from which the previous branch's
+*   context should be detached.
+* @param state - The current state (active branch index and its context), or
+*   `undefined` if no branch is currently active.
+*/
+function teardown(parentContext, state) {
+	if (state) {
+		state.context.unlisten();
+		parentContext.removeChild(state.context);
 	}
 }
 //#endregion
@@ -817,9 +934,9 @@ function checkAndUpdateState(parentNode, parentContext, state, newState, conditi
 * @param events - List of event listener descriptors to attach to the element.
 * @returns The newly created HTML element.
 */
-function _renderElement(parentNode, context, tagName, attributes, events) {
+function _renderElement(parentNode, context, anchor, tagName, attributes, events) {
 	const element = document.createElement(tagName);
-	mountNode(element, parentNode, context);
+	mountNode(element, parentNode, context, anchor);
 	attributes.forEach(({ name, value, literal }) => {
 		literal ? element.setAttribute(name, String(value())) : context.listen(effect(() => element.setAttribute(name, String(value()))));
 	});
@@ -880,8 +997,6 @@ function _renderLiteralText(parentNode, context, text) {
 *
 * @param parentNode - The parent HTML element where the conditional structure is applied.
 * @param parentContext - The parent Context object containing all the variables definition from the Parent Closure
-* @param unwatchFns - Shared array that collects all active cleanup functions.
-*   Mutated in place by the underlying {@link _if} call.
 * @param expression - Function that evaluates the switch expression. Called
 *   reactively inside an effect so that signal reads are tracked.
 * @param blocks - Ordered list of case branches. Each entry contains:
@@ -897,4 +1012,4 @@ function _switch(parentNode, parentContext, expression, blocks) {
 	})));
 }
 //#endregion
-export { BaseWebComponent, Context, Event, Property, WebComponent, _for, _if, _iterationVariables, _renderElement, _renderLiteralText, _renderText, _switch, computed, effect, input, mountNode, signal, untracked };
+export { BaseWebComponent, Context, Event, Property, WebComponent, _for, _if, _iterationVariables, _renderElement, _renderLiteralText, _renderText, _switch, computed, createAnchor, effect, input, mountNode, signal, untracked };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xaendar/core",
-  "version": "0.6.20",
+  "version": "0.7.0",
   "description": "A library containing core utils such as webcomponent base classes and theming support",
   "sideEffects": false,
   "type": "module",
@@ -16,7 +16,7 @@
     }
   },
   "dependencies": {
-    "@xaendar/signals": "0.6.20",
-    "@xaendar/types": "0.6.20"
+    "@xaendar/signals": "0.7.0",
+    "@xaendar/types": "0.7.0"
   }
 }