@kaskad/component-tree 0.0.1 → 0.0.2

package/fesm2022/kaskad-component-tree.mjs

@@ -0,0 +1,2380 @@
+import { makeObservable, observable, runInAction, computed, action, configure, untracked } from 'mobx';
+import { isObject, unfoldNodeSchema } from '@kaskad/schema';
+import { Delimiters, log } from '@kaskad/config';
+import { DefinitionStore } from '@kaskad/definition';
+
+function isArrayNode(node) {
+    return node.valueType.type === 'array';
+}
+function isCommandNode(node) {
+    return node.valueType.type === 'command';
+}
+
+class ComputationFrame {
+    schema;
+    disposers;
+    activated = false;
+    constructor(schema, disposers = [], activated = false) {
+        this.schema = schema;
+        this.disposers = disposers;
+        this.activated = activated;
+        makeObservable(this, {
+            activated: observable.ref,
+        });
+    }
+    /**
+     * Mark this computation frame as activated.
+     * This is an action that ensures MobX compliance.
+     */
+    markActivated() {
+        runInAction(() => {
+            this.activated = true;
+        });
+    }
+    dispose() {
+        this.disposers.forEach((d) => d());
+    }
+}
+
+/**
+ * Manages a stack of computation frames for nested computations.
+ * For example: formula → formula → template chain.
+ */
+class ComputationStack {
+    /**
+     * Maximum allowed stack depth to prevent infinite recursion.
+     */
+    static MAX_DEPTH = 10;
+    _frames;
+    constructor() {
+        this._frames = observable.array([], { deep: false, name: 'computation-stack' });
+    }
+    /**
+     * Get the topmost computation frame from the stack.
+     * Returns null if stack is empty.
+     */
+    get top() {
+        return this._frames[this._frames.length - 1] ?? null;
+    }
+    /**
+     * Returns true if all frames in the stack are activated.
+     * Empty stack returns true (vacuously).
+     */
+    get allActivated() {
+        return this._frames.length === 0 || this._frames.every((f) => f.activated);
+    }
+    /**
+     * Get the current stack depth.
+     */
+    get depth() {
+        return this._frames.length;
+    }
+    /**
+     * Check if the stack is empty.
+     */
+    get isEmpty() {
+        return this._frames.length === 0;
+    }
+    /**
+     * Push a new computation frame onto the stack.
+     * Throws if depth limit is exceeded.
+     */
+    push(schema) {
+        if (this._frames.length >= ComputationStack.MAX_DEPTH) {
+            throw new Error(`Computation stack overflow: depth ${this._frames.length + 1} exceeds maximum ${ComputationStack.MAX_DEPTH}. ` +
+                `This may indicate infinite recursion in computation chain.`);
+        }
+        return runInAction(() => {
+            const frame = new ComputationFrame(schema, [], false);
+            this._frames.push(frame);
+            return frame;
+        });
+    }
+    /**
+     * Pop all frames from the given depth onward.
+     * For example, if depth=2, this removes frames at indices 2, 3, 4, etc.
+     * Useful when a computation at a specific depth re-evaluates and needs
+     * to clear its results without affecting parent computations.
+     */
+    popFrom(depth) {
+        runInAction(() => {
+            while (this._frames.length > depth) {
+                const frame = this._frames.pop();
+                frame?.dispose();
+            }
+        });
+    }
+    /**
+     * Dispose all frames in the stack.
+     */
+    dispose() {
+        runInAction(() => {
+            while (this._frames.length > 0) {
+                const frame = this._frames.pop();
+                frame?.dispose();
+            }
+        });
+    }
+}
+
+const componentTreeConfig = {
+    runCommand: (_node, ..._args) => {
+        throw new Error('runCommand is not implemented. Please provide an implementation.');
+    },
+};
+
+function isNode(value) {
+    return isObject(value) && 'nodeType' in value;
+}
+
+class AbstractNode {
+    valueType;
+    position;
+    nodeType;
+    computationStack = new ComputationStack();
+    bindingSchema = null;
+    extraBinding = null;
+    disposers = [];
+    selfEvaluating = false;
+    selfFailed = false;
+    selfActivated = false;
+    constructor(valueType, structure, position) {
+        this.valueType = valueType;
+        this.position = position;
+        if (structure === undefined) {
+            throw new Error(`Node structure cannot be undefined`);
+        }
+        this._structure = structure;
+        this.nodeType = valueType.type;
+        makeObservable(this, {
+            _structure: observable.ref,
+            selfEvaluating: observable.ref,
+            selfFailed: observable.ref,
+            selfActivated: observable.ref,
+            evaluating: computed,
+            failed: computed,
+            fullyActivated: computed,
+            computationActivated: computed,
+            isSelfActivated: computed,
+            extractedValue: computed,
+            viewModel: computed,
+        }, { name: `Node-${this.valueType.type}` });
+    }
+    _structure;
+    get structure() {
+        return this._structure;
+    }
+    set structure(value) {
+        if (value === undefined) {
+            throw new Error(`Node structure cannot be undefined`);
+        }
+        runInAction(() => (this._structure = value));
+    }
+    get evaluating() {
+        return this.selfEvaluating || this.childrenEvaluating;
+    }
+    set evaluating(evaluating) {
+        this.selfEvaluating = evaluating;
+    }
+    get failed() {
+        return this.selfFailed || this.childrenFailed;
+    }
+    set failed(failed) {
+        this.selfFailed = failed;
+    }
+    get fullyActivated() {
+        return this.selfActivated && this.computationActivated && this.childrenActivated;
+    }
+    get computationActivated() {
+        return this.computationStack.allActivated;
+    }
+    get isSelfActivated() {
+        return this.selfActivated;
+    }
+    get viewModel() {
+        return this.extractedValue;
+    }
+    markActivated() {
+        runInAction(() => (this.selfActivated = true));
+    }
+    dispose() {
+        runInAction(() => {
+            // Dispose all computation frames in the stack
+            this.computationStack.dispose();
+            // run self-level disposers
+            this.disposers.forEach((disposer) => disposer());
+            this.disposers.length = 0; // reset array
+        });
+        // delegate to subclass for the child walk
+        this.disposeChildren();
+    }
+}
+class LeafNode extends AbstractNode {
+    constructor(valueType, structure, position) {
+        super(valueType, structure, position);
+    }
+    get extractedValue() {
+        return this.structure;
+    }
+    get childrenEvaluating() {
+        return false;
+    }
+    get childrenFailed() {
+        return false;
+    }
+    get childrenActivated() {
+        return true;
+    }
+    getNodeByPath(path) {
+        // Leaf nodes cannot be traversed further
+        return path.length === 0 ? this : null;
+    }
+    disposeChildren() {
+        return;
+    }
+}
+class CommandNode extends LeafNode {
+    inFlight = 0;
+    constructor(valueType, structure, position) {
+        super(valueType, structure, position);
+        makeObservable(this, {
+            inFlight: observable,
+            executing: computed,
+        });
+    }
+    get executing() {
+        return this.inFlight > 0;
+    }
+    get viewModel() {
+        return {
+            execute: this.#execute,
+            executing: this.executing,
+            failed: this.failed,
+        };
+    }
+    #execute = async (...args) => {
+        runInAction(() => this.inFlight++);
+        this.failed = false; // Reset failed state before execution
+        try {
+            return await componentTreeConfig.runCommand(this, ...args);
+        }
+        catch (error) {
+            this.failed = true; // Set failed state on error
+            throw error;
+        }
+        finally {
+            runInAction(() => this.inFlight--);
+        }
+    };
+}
+class ArrayNode extends AbstractNode {
+    constructor(valueType, structure, position) {
+        super(valueType, structure, position);
+    }
+    get extractedValue() {
+        const value = this.structure;
+        if (!value)
+            return null;
+        return value.map((item) => item.extractedValue);
+    }
+    get childrenEvaluating() {
+        return this.structure ? this.structure.some((n) => n.evaluating) : false;
+    }
+    get childrenFailed() {
+        return this.structure ? this.structure.some((n) => n.failed) : false;
+    }
+    get childrenActivated() {
+        return this.structure ? this.structure.every((n) => n.fullyActivated) : true;
+    }
+    getNodeByPath(path) {
+        if (path.length === 0) {
+            return this;
+        }
+        const [head, ...tail] = path;
+        if (!this.structure)
+            return null;
+        const found = this.structure[head];
+        if (!found)
+            return null;
+        return found.getNodeByPath(tail);
+    }
+    disposeChildren() {
+        this.structure?.forEach((child) => isNode(child) && child.dispose());
+    }
+}
+class AbstractObjectLikeNode extends AbstractNode {
+    constructor(valueType, structure, position) {
+        super(valueType, structure, position);
+    }
+    get childrenEvaluating() {
+        const obj = this.object();
+        return !!obj && Object.values(obj).some((n) => n.evaluating);
+    }
+    get childrenFailed() {
+        const obj = this.object();
+        return !!obj && Object.values(obj).some((n) => n.failed);
+    }
+    get childrenActivated() {
+        const obj = this.object();
+        return obj ? Object.values(obj).every((n) => n.fullyActivated) : true;
+    }
+    getNodeByPath(path) {
+        if (path.length === 0) {
+            return this;
+        }
+        const [head, ...tail] = path;
+        const obj = this.object();
+        if (!obj)
+            return null;
+        const found = obj[head];
+        if (!found)
+            return null;
+        return found.getNodeByPath(tail);
+    }
+    disposeChildren() {
+        const obj = this.object();
+        if (!obj)
+            return;
+        Object.values(obj).forEach((n) => n.dispose());
+    }
+    mapObjectExtracted() {
+        const obj = this.object();
+        if (!obj)
+            return null;
+        return Object.fromEntries(Object.entries(obj).map(([k, n]) => [k, n.extractedValue]));
+    }
+}
+class MapNode extends AbstractObjectLikeNode {
+    constructor(valueType, structure, position) {
+        super(valueType, structure, position);
+    }
+    get extractedValue() {
+        return this.mapObjectExtracted();
+    }
+    object() {
+        return this.structure;
+    }
+}
+class SetNode extends AbstractNode {
+    constructor(valueType, structure, position) {
+        super(valueType, structure, position);
+    }
+    get extractedValue() {
+        const value = this.structure;
+        if (!value)
+            return null;
+        const extractedValues = new Set();
+        value.forEach((item) => {
+            extractedValues.add(item.extractedValue);
+        });
+        return extractedValues;
+    }
+    get childrenEvaluating() {
+        return this.structure ? Array.from(this.structure).some((n) => n.evaluating) : false;
+    }
+    get childrenFailed() {
+        return this.structure ? Array.from(this.structure).some((n) => n.failed) : false;
+    }
+    get childrenActivated() {
+        return this.structure ? Array.from(this.structure).every((n) => n.fullyActivated) : true;
+    }
+    getNodeByPath(path) {
+        if (path.length === 0) {
+            return this;
+        }
+        // Sets don't support path traversal since they don't have indexed access
+        return null;
+    }
+    disposeChildren() {
+        this.structure?.forEach((child) => isNode(child) && child.dispose());
+    }
+}
+class ObjectNode extends AbstractObjectLikeNode {
+    constructor(valueType, structure, position) {
+        super(valueType, structure, position);
+    }
+    get extractedValue() {
+        return this.mapObjectExtracted();
+    }
+    object() {
+        return this.structure;
+    }
+}
+class ShapeNode extends AbstractObjectLikeNode {
+    constructor(valueType, structure, position) {
+        super(valueType, structure, position);
+    }
+    get extractedValue() {
+        return this.mapObjectExtracted();
+    }
+    object() {
+        return this.structure;
+    }
+}
+class VariantShapeNode extends AbstractObjectLikeNode {
+    constructor(valueType, structure, position) {
+        super(valueType, structure, position);
+    }
+    get extractedValue() {
+        const base = this.mapObjectExtracted();
+        if (!base || !this.structure)
+            return null;
+        const kindField = `${this.valueType.shapeType}Type`;
+        return { ...base, [kindField]: this.structure.kind };
+    }
+    object() {
+        return this.structure?.fields ?? null;
+    }
+}
+// TNode is removed - use AbstractNode<ValueType> directly
+
+const modifiers = [':', '^', '&'];
+function parseComponentSelector(selector) {
+    if (!selector.trim()) {
+        return [];
+    }
+    const result = [];
+    const parts = selector.split(/\s+/);
+    for (let i = 0; i < parts.length; i++) {
+        let part = parts[i];
+        if (part.includes('[')) {
+            while (!part.endsWith(']') && i < parts.length - 1) {
+                i++;
+                part += ' ' + parts[i];
+            }
+        }
+        result.push(parseSelectorSegment(part));
+    }
+    return result;
+}
+function parseSelectorSegment(rawSegment) {
+    const segment = {
+        qualifier: '',
+        modifier: null,
+        conditions: [],
+    };
+    // Extract :nth(N) pseudo-selector
+    const nthMatch = rawSegment.match(/:nth\((-?\d+)\)/);
+    if (nthMatch) {
+        segment.index = parseInt(nthMatch[1], 10);
+        rawSegment = rawSegment.replace(/:nth\(-?\d+\)/, '');
+    }
+    const conditionsMatch = rawSegment.match(/\[(.*?)]/g);
+    if (conditionsMatch) {
+        segment.conditions = conditionsMatch.map((item) => item.slice(1, -1).split('='));
+        const conditionStart = rawSegment.indexOf('[');
+        rawSegment = rawSegment.slice(0, conditionStart);
+    }
+    const firstChar = rawSegment[0];
+    segment.modifier = modifiers.includes(firstChar) ? firstChar : null;
+    segment.qualifier = rawSegment.replace(/^[:^&]/, '');
+    return segment;
+}
+
+/**
+ * Parse a path string into structured segments.
+ *
+ * ## Path Notation Rules
+ *
+ * **Dot notation (.)** - Access object properties
+ * - `user.profile.name` - Access nested object properties
+ * - `config.0` - Access object property named "0" (string key)
+ *
+ * **Bracket notation ([])** - Access array elements by numeric index
+ * - `items[0].name` - Access first array element, then its 'name' property
+ * - `matrix[0][1]` - Access multi-dimensional arrays
+ *
+ * **Optional chaining (?.)** - Safely access potentially missing properties
+ * - `user?.profile?.email` - Returns null if any segment is missing
+ *
+ * **Variable prefix ($)** - Access variables instead of properties
+ * - `$config.theme` - Access variable 'config', then its 'theme' property
+ * - `$items[0]` - Access variable 'items' array, then first element
+ *
+ * **Component selector (->)** - Access properties on other components
+ * - `&ref->prop.field` - Access 'prop.field' on component with ref
+ * - `:Button[disabled=true]->label` - Access 'label' on Button with condition
+ * - `^parent->config` - Access 'config' on parent component
+ *
+ * **Optional component selector (?->)** - Safely access components that might not exist
+ * - `&ref?->value` - Returns null if component with ref doesn't exist
+ * - `:OptionalType?->property` - Returns null if component type not found
+ * - `^Parent?->config` - Returns null if parent doesn't match
+ *
+ * ## Component Selector Syntax
+ *
+ * Component selectors support modifiers and conditions:
+ * - `&ref` - Select by ref
+ * - `:ComponentType` - Select by component type
+ * - `^parent` - Select parent component
+ * - `[prop=value]` - Filter by property value
+ * - Multiple conditions: `:Button[disabled=true][type=submit]`
+ *
+ * ## Notation Disambiguation
+ *
+ * The choice between dot and bracket notation determines the access type:
+ * ```typescript
+ * 'data.0'      // Object property named "0" (string key)
+ * 'data[0]'     // Array element at index 0 (numeric index)
+ * 'columns.1'   // Object property named "1"
+ * 'columns[1]'  // Array element at index 1
+ * ```
+ *
+ * @example
+ * parseNodeSelector('users[0].name')
+ * // => { kind: 'property', head: 'users', tail: [{ key: 0, optional: false }, { key: 'name', optional: false }] }
+ *
+ * @example
+ * parseNodeSelector('config.0')
+ * // => { kind: 'property', head: 'config', tail: [{ key: '0', optional: false }] }
+ *
+ * @example
+ * parseNodeSelector('prop?.nested?.field')
+ * // => { kind: 'property', head: 'prop', tail: [{ key: 'nested', optional: true }, { key: 'field', optional: true }] }
+ *
+ * @example
+ * parseNodeSelector('$varName.field')
+ * // => { kind: 'variable', head: 'varName', tail: [{ key: 'field', optional: false }] }
+ *
+ * @example
+ * parseNodeSelector('&ref->prop.field')
+ * // => {
+ * //   componentSelector: [{ qualifier: 'ref', modifier: '&', conditions: [] }],
+ * //   kind: 'property',
+ * //   head: 'prop',
+ * //   tail: [{ key: 'field', optional: false }]
+ * // }
+ *
+ * @example
+ * parseNodeSelector(':Button[disabled=true]->label.text')
+ * // => {
+ * //   componentSelector: [{ qualifier: 'Button', modifier: ':', conditions: [['disabled', 'true']] }],
+ * //   kind: 'property',
+ * //   head: 'label',
+ * //   tail: [{ key: 'text', optional: false }]
+ * // }
+ */
+function parseNodeSelector(path) {
+    if (!path) {
+        throw new Error('Empty path provided');
+    }
+    // Handle variable prefix
+    if (path.startsWith(Delimiters.Variable)) {
+        const withoutPrefix = path.slice(1);
+        // Check for both . and ?. separators
+        const dotIndex = withoutPrefix.indexOf(Delimiters.NodePath);
+        const optionalIndex = withoutPrefix.indexOf('?.');
+        // If no separator found, it's just the variable name
+        if (dotIndex === -1 && optionalIndex === -1) {
+            return {
+                kind: 'variable',
+                head: withoutPrefix,
+                tail: [],
+            };
+        }
+        // Find the first separator (. or ?.)
+        let firstSeparatorIndex;
+        let isOptional;
+        if (dotIndex === -1) {
+            firstSeparatorIndex = optionalIndex;
+            isOptional = true;
+        }
+        else if (optionalIndex === -1) {
+            firstSeparatorIndex = dotIndex;
+            isOptional = false;
+        }
+        else {
+            firstSeparatorIndex = Math.min(dotIndex, optionalIndex);
+            isOptional = firstSeparatorIndex === optionalIndex;
+        }
+        const varName = withoutPrefix.substring(0, firstSeparatorIndex);
+        const restPath = withoutPrefix.substring(firstSeparatorIndex + (isOptional ? 2 : 1));
+        return {
+            kind: 'variable',
+            head: varName,
+            tail: parseSegments(restPath, isOptional), // Pass the optional flag
+        };
+    }
+    // Handle component selector arrow (both ?-> and ->)
+    const optionalArrowIndex = path.indexOf('?->');
+    const strictArrowIndex = path.indexOf('->');
+    // Determine which arrow to use (prefer ?-> if both are found)
+    let arrowIndex = -1;
+    let arrowLength = 2;
+    let isOptionalComponent = false;
+    if (optionalArrowIndex !== -1 && (strictArrowIndex === -1 || optionalArrowIndex < strictArrowIndex)) {
+        arrowIndex = optionalArrowIndex;
+        arrowLength = 3;
+        isOptionalComponent = true;
+    }
+    else if (strictArrowIndex !== -1) {
+        arrowIndex = strictArrowIndex;
+        arrowLength = 2;
+        isOptionalComponent = false;
+    }
+    if (arrowIndex !== -1) {
+        const componentSelectorStr = path.substring(0, arrowIndex);
+        const nodePath = path.substring(arrowIndex + arrowLength);
+        const parsed = parseNodeSelector(nodePath);
+        return {
+            component: {
+                selector: parseComponentSelector(componentSelectorStr),
+                optional: isOptionalComponent,
+            },
+            kind: parsed.kind,
+            head: parsed.head,
+            tail: parsed.tail,
+        };
+    }
+    // Regular property path
+    return parsePropertyPath(path);
+}
+/**
+ * Parse a property path (no variable prefix or component selector)
+ */
+function parsePropertyPath(path) {
+    if (!path) {
+        throw new Error('Empty property path provided');
+    }
+    const allSegments = parseSegments(path);
+    if (allSegments.length === 0) {
+        throw new Error('Empty property path provided');
+    }
+    const [first, ...rest] = allSegments;
+    return {
+        kind: 'property',
+        head: first.key,
+        tail: rest,
+    };
+}
+/**
+ * Parse path segments, handling optional chaining and array notation
+ * @param path - The path to parse
+ * @param startOptional - If true, the first segment should be marked as optional
+ */
+function parseSegments(path, startOptional = false) {
+    if (!path)
+        return [];
+    const segments = [];
+    let current = '';
+    let nextOptional = startOptional; // Start with the passed optional flag
+    let i = 0;
+    while (i < path.length) {
+        const char = path[i];
+        const nextChar = path[i + 1];
+        // Handle optional chaining ?.
+        if (char === '?' && nextChar === '.') {
+            if (current) {
+                segments.push(makeSegment(current, nextOptional, false));
+                current = '';
+            }
+            nextOptional = true;
+            i += 2;
+            continue;
+        }
+        // Handle array bracket notation [0]
+        if (char === '[') {
+            if (current) {
+                segments.push(makeSegment(current, nextOptional, false));
+                current = '';
+                nextOptional = false;
+            }
+            let index = '';
+            i++;
+            while (i < path.length && path[i] !== ']') {
+                index += path[i];
+                i++;
+            }
+            if (path[i] === ']') {
+                segments.push(makeSegment(index, nextOptional, true)); // fromBracket = true
+                i++; // Skip ]
+                // Skip following . if present
+                if (path[i] === '.')
+                    i++;
+            }
+            continue;
+        }
+        // Handle regular . separator
+        if (char === '.') {
+            if (current) {
+                segments.push(makeSegment(current, nextOptional, false));
+                current = '';
+                nextOptional = false;
+            }
+            i++;
+            continue;
+        }
+        current += char;
+        i++;
+    }
+    if (current) {
+        segments.push(makeSegment(current, nextOptional, false));
+    }
+    return segments;
+}
+/**
+ * Create a path segment, parsing numbers only for bracket notation.
+ * Dot notation keeps keys as strings to allow object properties named "0", "1", etc.
+ *
+ * @param key - The segment key
+ * @param optional - Whether this segment uses optional chaining
+ * @param fromBracket - True if this came from bracket notation [0], false if from dot notation
+ */
+function makeSegment(key, optional, fromBracket = false) {
+    // Only convert to number if it came from bracket notation
+    if (fromBracket) {
+        const asNumber = Number(key);
+        if (!Number.isNaN(asNumber)) {
+            return { key: asNumber, optional };
+        }
+    }
+    // Keep as string for dot notation or non-numeric bracket content
+    return { key, optional };
+}
+
+function formatSource(sourceUrl, path) {
+    if (!sourceUrl)
+        return '';
+    const pathStr = path?.length ? ` @ ${path.join('.')}` : '';
+    return `[${sourceUrl}${pathStr}]`;
+}
+
+/**
+ * Traverse a node using parsed path segments, respecting optional chaining.
+ *
+ * @param node - The starting node
+ * @param segments - Array of path segments to traverse
+ * @returns The found node, or null if not found and optional chaining was used
+ * @throws Error if a required segment is not found
+ *
+ * @example
+ * const userNode = component.getNode('user');
+ * const nameNode = traverseNode(userNode, [
+ *   { key: 'profile', optional: false },
+ *   { key: 'name', optional: false }
+ * ]);
+ *
+ * @example
+ * // With optional chaining - returns null instead of throwing
+ * const emailNode = traverseNode(userNode, [
+ *   { key: 'contact', optional: true },
+ *   { key: 'email', optional: false }
+ * ]);
+ */
+function traverseNode(node, segments) {
+    if (segments.length === 0) {
+        return node;
+    }
+    const [head, ...tail] = segments;
+    const found = node.getNodeByPath([head.key]);
+    if (!found) {
+        if (head.optional) {
+            return null; // Optional chaining returns null
+        }
+        // Check if this is a shape/object-like node with null value
+        // In this case, accessing properties should return null instead of throwing
+        // This is common in reactive systems where shape values might not be initialized yet
+        if (node.nodeType === 'shape' ||
+            node.nodeType === 'variantShape' ||
+            node.nodeType === 'object' ||
+            node.nodeType === 'map') {
+            const extracted = node.extractedValue;
+            if (extracted === null || extracted === undefined) {
+                return null;
+            }
+        }
+        throw new Error(`Cannot access ${typeof head.key === 'number' ? 'index' : 'property'} ` +
+            `'${head.key}' on ${node.nodeType} node at path ${node.position.path.join('.')}`);
+    }
+    return traverseNode(found, tail);
+}
+
+class TComponent {
+    id;
+    position;
+    refSpaceId;
+    sourceUrl;
+    componentType;
+    props;
+    variables;
+    onNodeChange;
+    handlerDisposers = [];
+    constructor(config) {
+        this.id = config.id;
+        this.position = config.position;
+        this.refSpaceId = config.refSpaceId;
+        this.sourceUrl = config.sourceUrl ?? null;
+        this.componentType = config.componentType;
+        this.props = config.props;
+        this.variables = config.variables;
+        this.onNodeChange = config.onNodeChange;
+        makeObservable(this, {
+            props: observable.shallow,
+            variables: observable.shallow,
+            setVariable: action,
+        });
+    }
+    setVariable(variableName, node) {
+        this.variables.set(variableName, node);
+    }
+    /**
+     * Find a node by selector. Returns null if the node is not found.
+     * This is an alias for getNode for consistency with ComponentStore's API.
+     */
+    findNode(nodeSelector) {
+        const parsed = parseNodeSelector(nodeSelector);
+        return this.findNodeFromParsed(parsed);
+    }
+    /**
+     * Get a node by selector. Throws an error if the node is not found.
+     * Use findNode() for optional lookups that return null instead of throwing.
+     *
+     * Note: Even if the selector contains optional chaining (?.), this method will throw
+     * if the node is not found. Use findNode() for optional chaining support.
+     */
+    getNode(nodeSelector) {
+        const parsed = parseNodeSelector(nodeSelector);
+        return this.getNodeFromParsed(parsed);
+    }
+    findNodeFromParsed(parsed) {
+        // Handle variable access
+        if (parsed.kind === 'variable') {
+            const varNode = this.variables.get(parsed.head);
+            if (!varNode) {
+                return null;
+            }
+            return traverseNode(varNode, parsed.tail);
+        }
+        // Handle property access
+        const propNode = this.props.get(parsed.head);
+        if (!propNode) {
+            return null;
+        }
+        return traverseNode(propNode, parsed.tail);
+    }
+    getNodeFromParsed(parsed) {
+        const src = formatSource(this.sourceUrl);
+        // Handle variable access
+        if (parsed.kind === 'variable') {
+            const varNode = this.variables.get(parsed.head);
+            if (!varNode) {
+                throw new Error(`${src} Variable '${parsed.head}' does not exist in component '${this.id}' (type: ${this.componentType})`);
+            }
+            const result = traverseNode(varNode, parsed.tail);
+            if (!result) {
+                throw new Error(`${src} Node not found for variable path '${parsed.head}${parsed.tail.map((s) => `.${s.key}`).join('')}' in component '${this.id}'`);
+            }
+            return result;
+        }
+        // Handle property access - strict mode, always throw if not found
+        const propNode = this.props.get(parsed.head);
+        if (!propNode) {
+            throw new Error(`${src} Property '${parsed.head}' does not exist on component '${this.id}' (type: ${this.componentType}). ` +
+                `Available properties: [${Array.from(this.props.keys()).join(', ')}]`);
+        }
+        const result = traverseNode(propNode, parsed.tail);
+        if (!result) {
+            throw new Error(`${src} Node not found for property path '${parsed.head}${parsed.tail.map((s) => `.${s.key}`).join('')}' in component '${this.id}'`);
+        }
+        return result;
+    }
+    getNodeValue(nodeSelector) {
+        // Use findNode to support optional chaining and return null if not found
+        const node = this.findNode(nodeSelector);
+        return node ? node.extractedValue : null;
+    }
+    dispose() {
+        this.handlerDisposers.forEach((disposer) => disposer());
+        this.handlerDisposers = [];
+        for (const [, prop] of this.props.entries()) {
+            prop.dispose();
+        }
+        for (const [, variable] of this.variables.entries()) {
+            variable.dispose();
+        }
+    }
+}
+
+class RefSpace {
+    id;
+    parentRefSpaceId;
+    byRef;
+    constructor(id, parentRefSpaceId = null) {
+        this.id = id;
+        this.parentRefSpaceId = parentRefSpaceId;
+        this.byRef = observable.map({}, { name: 'by-ref-map', deep: false });
+    }
+    get refs() {
+        return this.byRef;
+    }
+    addRefs(refs) {
+        runInAction(() => {
+            for (const ref in refs) {
+                this.byRef.set(ref, refs[ref]);
+            }
+        });
+    }
+    getComponentIdByRef(ref) {
+        return this.byRef.get(ref) || null;
+    }
+}
+
+function traversArray(ctx, nodeQueue) {
+    if (!ctx.selectorSegments.length) {
+        return;
+    }
+    const arrayValue = ctx.currentNode.value || [];
+    const description = ctx.currentNode.valueType;
+    for (const item of arrayValue) {
+        const childCtx = {
+            ...ctx,
+            currentNode: {
+                valueType: description.item,
+                value: item,
+            },
+        };
+        nodeQueue.push(childCtx);
+    }
+}
+
+function traversComponent(ctx, nodeQueue, foundComponents) {
+    const componentId = ctx.currentNode.value;
+    if (componentId === null)
+        return;
+    const segmentQueue = [...ctx.selectorSegments];
+    const store = ComponentStore.getInstance();
+    const currentComponent = store.getComponentOrThrow(componentId);
+    while (segmentQueue.length > 0) {
+        const selectorSegment = segmentQueue.shift();
+        if (!selectorSegment)
+            break;
+        const isLastSelectorSegment = segmentQueue.length === 0;
+        if (selectorSegment.modifier === '&') {
+            const refSpace = store.getRefSpaceOrThrow(currentComponent.refSpaceId);
+            const foundComponentId = refSpace.getComponentIdByRef(selectorSegment.qualifier);
+            if (!foundComponentId) {
+                if (!refSpace.parentRefSpaceId) {
+                    return;
+                }
+                const parentRefSpace = store.getRefSpaceOrThrow(refSpace.parentRefSpaceId);
+                const foundInParent = parentRefSpace.getComponentIdByRef(selectorSegment.qualifier);
+                if (!foundInParent) {
+                    return;
+                }
+                if (isLastSelectorSegment) {
+                    foundComponents.push(foundInParent);
+                    return;
+                }
+                addToQueue(currentComponent.id, {
+                    valueType: { type: 'component' },
+                    value: foundInParent,
+                }, segmentQueue, nodeQueue);
+                return;
+            }
+            if (isLastSelectorSegment) {
+                foundComponents.push(foundComponentId);
+                return;
+            }
+            continue;
+        }
+        if (selectorSegment.modifier === '^') {
+            const matched = testComponentType(selectorSegment.qualifier, currentComponent.componentType) &&
+                testConditions(selectorSegment.conditions, currentComponent);
+            if (!matched) {
+                addToQueue(currentComponent.id, {
+                    valueType: { type: 'component' },
+                    value: currentComponent.position.componentId,
+                }, [selectorSegment, ...segmentQueue], nodeQueue);
+                return;
+            }
+            if (isLastSelectorSegment) {
+                foundComponents.push(componentId);
+            }
+            continue;
+        }
+        if (selectorSegment.modifier === ':') {
+            if (!DefinitionStore.getInstance().hasComponentWithType(selectorSegment.qualifier)) {
+                log.trace(`Component with type "${selectorSegment.qualifier}" does not exist.`);
+                return;
+            }
+            if (currentComponent.id === ctx.relativeTo) {
+                addComponentNodesToQueue(currentComponent, [selectorSegment, ...segmentQueue], nodeQueue);
+                return;
+            }
+            const matched = testComponentType(selectorSegment.qualifier, currentComponent.componentType) &&
+                testConditions(selectorSegment.conditions, currentComponent);
+            if (!matched) {
+                addComponentNodesToQueue(currentComponent, [selectorSegment, ...segmentQueue], nodeQueue);
+                return;
+            }
+            if (isLastSelectorSegment) {
+                foundComponents.push(componentId);
+                return;
+            }
+            addToQueue(currentComponent.id, {
+                valueType: { type: 'component' },
+                value: currentComponent.id,
+            }, segmentQueue, nodeQueue);
+            return;
+        }
+        log.trace('Potentially invalid selector', ctx.selectorSegments);
+    }
+}
+function testComponentType(qualifier, componentType) {
+    return DefinitionStore.getInstance().getComponentTraits(componentType).includes(qualifier);
+}
+function testConditions(conditions, component) {
+    return conditions.every((condition) => {
+        const [key, expectedValue] = condition;
+        if (!component.props.has(key))
+            return false;
+        const actualValue = String(extractNodeValue(component.props.get(key)));
+        return actualValue === expectedValue;
+    });
+}
+function addComponentNodesToQueue(component, selectorSegments, nodeQueue) {
+    for (const node of component.props.values()) {
+        addToQueue(component.id, {
+            valueType: node.valueType,
+            value: extractNodeValue(node),
+        }, selectorSegments, nodeQueue);
+    }
+}
+function addToQueue(componentId, node, selectorSegments, nodeQueue) {
+    const childCtx = {
+        selectorSegments,
+        currentNode: node,
+        relativeTo: componentId,
+    };
+    nodeQueue.push(childCtx);
+}
+function extractNodeValue(node) {
+    if (!node)
+        return null;
+    return node.extractedValue;
+}
+
+function traversObject(ctx, nodeQueue) {
+    if (!ctx.selectorSegments.length) {
+        return;
+    }
+    const description = ctx.currentNode.valueType;
+    const objectNodeValue = ctx.currentNode.value;
+    if (!objectNodeValue) {
+        return;
+    }
+    Object.entries(description.fields).forEach(([fieldKey, fieldDescription]) => {
+        const childCtx = {
+            ...ctx,
+            currentNode: {
+                valueType: fieldDescription,
+                value: objectNodeValue[fieldKey],
+            },
+        };
+        nodeQueue.push(childCtx);
+    });
+    return;
+}
+
+const traversesRegistry = {
+    _registry: {
+        array: traversArray,
+        object: traversObject,
+        component: traversComponent,
+        map: () => [], // TODO: implement
+        // the following node types cannot contain components
+        set: () => [],
+        unknown: () => [],
+        boolean: () => [],
+        string: () => [],
+        number: () => [],
+        componentSchema: () => [],
+        validator: () => [],
+        command: () => [],
+        shape: () => [],
+        variantShape: () => [],
+    },
+    get(type) {
+        if (!this._registry[type]) {
+            throw new Error(`Travers for type "${type}" not found`);
+        }
+        return this._registry[type];
+    },
+};
+
+function findComponent(relativeTo, selector) {
+    const ids = findComponentsIds(relativeTo, selector);
+    if (!ids.length) {
+        return null;
+    }
+    if (ids.length > 1) {
+        throw new Error(`Selector matched ${ids.length} components (expected 1): ${ids.join(', ')}`);
+    }
+    return ComponentStore.getInstance().getComponentOrThrow(ids[0]);
+}
+function findComponents(relativeTo, selector) {
+    const ids = findComponentsIds(relativeTo, selector);
+    return ids.map((componentId) => ComponentStore.getInstance().getComponentOrThrow(componentId));
+}
+function findComponentsIds(relativeTo, selector) {
+    const selectors = [selector];
+    const foundComponents = [];
+    for (const parsedSelector of selectors) {
+        if (parsedSelector.length === 0) {
+            foundComponents.push(relativeTo);
+            continue;
+        }
+        const startFrom = {
+            currentNode: {
+                valueType: { type: 'component' },
+                value: relativeTo,
+            },
+            selectorSegments: parsedSelector,
+            relativeTo,
+        };
+        const nodeQueue = [startFrom];
+        while (nodeQueue.length > 0) {
+            const ctx = nodeQueue.shift();
+            if (!ctx)
+                break;
+            const traverser = traversesRegistry.get(ctx.currentNode.valueType.type);
+            traverser(ctx, nodeQueue, foundComponents);
+        }
+    }
+    const uniqueComponents = Array.from(new Set(foundComponents));
+    // Apply :nth(N) filtering if the last segment has an index
+    const lastSegment = selector[selector.length - 1];
+    if (lastSegment && lastSegment.index !== undefined) {
+        const index = lastSegment.index;
+        const actualIndex = index < 0 ? uniqueComponents.length + index : index;
+        if (actualIndex < 0 || actualIndex >= uniqueComponents.length) {
+            const selectorStr = selector.map(formatSelectorSegment).join(' ');
+            throw new Error(`Index ${index} out of bounds for selector "${selectorStr}" (found ${uniqueComponents.length} elements)`);
+        }
+        return [uniqueComponents[actualIndex]];
+    }
+    return uniqueComponents;
+}
+function formatSelectorSegment(segment) {
+    let result = segment.modifier ? segment.modifier + segment.qualifier : segment.qualifier;
+    if (segment.conditions.length > 0) {
+        result += segment.conditions.map(([key, value]) => `[${key}=${value}]`).join('');
+    }
+    if (segment.index !== undefined) {
+        result += `:nth(${segment.index})`;
+    }
+    return result;
+}
+
+function withPath(opts, newPath) {
+    return {
+        ...opts,
+        position: { componentId: opts.position.componentId, path: newPath },
+    };
+}
+function withPosition(opts, componentId, path) {
+    return {
+        ...opts,
+        position: { componentId, path },
+    };
+}
+function appendPath(opts, ...segments) {
+    return withPath(opts, [...opts.position.path, ...segments]);
+}
+
+function createArrayNode(schema, opts) {
+    // TODO: set empty array on unfolding ?
+    const value = (schema.value || []).map((item, index) => createNode(item, appendPath(opts, index)));
+    return new ArrayNode(schema.valueType, value, opts.position);
+}
+
+function createCommandNode(schema, opts) {
+    if (!opts.position.componentId) {
+        throw new Error(`componentId is required for command.`);
+    }
+    if (!isObject(schema.value)) {
+        return new CommandNode(schema.valueType, null, opts.position);
+    }
+    const structure = { ...schema.value }; // Clone the value to avoid mutation
+    if (!structure.owner) {
+        structure.owner = opts.position.componentId;
+    }
+    return new CommandNode(schema.valueType, structure, opts.position);
+}
+
+const componentIdGenerator = {
+    increment: 0,
+    generateId() {
+        return ['csid', ++this.increment].filter((item) => !!item).join('-');
+    },
+    reset() {
+        this.increment = 0;
+    },
+};
+
+function createComponentNode(schema, opts) {
+    const componentSchema = schema.value;
+    if (!componentSchema || typeof componentSchema === 'string') {
+        return new LeafNode(schema.valueType, componentSchema, opts.position);
+    }
+    if (componentSchema.ref && opts.refs[opts.refSpaceId]?.[componentSchema.ref]) {
+        throw new Error(`Duplicated ref "${componentSchema.ref}".`);
+    }
+    const id = componentIdGenerator.generateId();
+    const isFacade = componentSchema.componentType === 'sys.Facade';
+    const isRefSpace = componentSchema.componentType === 'sys.RefSpace';
+    const needsContentSpace = isFacade || isRefSpace;
+    const contentSpaceId = isFacade ? `${id}-template` : isRefSpace ? `${id}-instance` : opts.refSpaceId;
+    const props = new Map();
+    for (const [key, propSchema] of componentSchema.props.entries()) {
+        // 'content' prop uses isolated RefSpace
+        const propOpts = needsContentSpace && key === 'content' ? { ...opts, refSpaceId: contentSpaceId } : opts;
+        props.set(key, createNode(propSchema, withPosition(propOpts, id, [key])));
+    }
+    const variables = new Map();
+    for (const [key, variableSchema] of componentSchema.variables.entries()) {
+        variables.set(key, createNode(variableSchema, withPosition(opts, id, [key])));
+    }
+    const onNodeChange = componentSchema.onNodeChange.map((handler) => ({
+        ...handler,
+        command: createNode(handler.command, withPosition(opts, id, [handler.selector])),
+    }));
+    opts.components[id] = new TComponent({
+        id,
+        componentType: componentSchema.componentType,
+        props,
+        variables,
+        onNodeChange,
+        position: opts.position,
+        refSpaceId: isFacade ? opts.refSpaceId : contentSpaceId,
+        sourceUrl: opts.sourceUrl,
+    });
+    if (componentSchema.ref) {
+        opts.refs[opts.refSpaceId] ??= {};
+        opts.refs[opts.refSpaceId][componentSchema.ref] = id;
+    }
+    if (needsContentSpace) {
+        const refSpace = new RefSpace(contentSpaceId, opts.refSpaceId);
+        ComponentStore.getInstance().addRefSpace(refSpace);
+        if (opts.refs[contentSpaceId]) {
+            refSpace.addRefs(opts.refs[contentSpaceId]);
+        }
+    }
+    return new LeafNode({ type: 'component' }, id, opts.position);
+}
+
+function createLeafNode(schema, opts) {
+    return new LeafNode(schema.valueType, schema.value, opts.position);
+}
+
+function createMapNode(schema, opts) {
+    if (!schema.value) {
+        return new MapNode(schema.valueType, null, opts.position);
+    }
+    const children = {};
+    for (const key in schema.value) {
+        children[key] = createNode(schema.value[key], appendPath(opts, key));
+    }
+    return new MapNode(schema.valueType, children, opts.position);
+}
+
+function createObjectNode(schema, opts) {
+    if (!schema.value) {
+        return new ObjectNode(schema.valueType, null, opts.position);
+    }
+    if (!Object.keys(schema.valueType).length) {
+        return new ObjectNode(schema.valueType, null, opts.position);
+    }
+    const fields = {};
+    for (const key in schema.value) {
+        fields[key] = createNode(schema.value[key], appendPath(opts, key));
+    }
+    return new ObjectNode(schema.valueType, fields, opts.position);
+}
+
+function createSetNode(schema, opts) {
+    if (!schema.value) {
+        return new SetNode(schema.valueType, null, opts.position);
+    }
+    // Convert array to Set of nodes
+    const items = schema.value.map((item, index) => createNode(item, appendPath(opts, index)));
+    const value = new Set(items);
+    return new SetNode(schema.valueType, value, opts.position);
+}
+
+function createShapeNode(schema, opts) {
+    if (!isObject(schema.value)) {
+        return new ShapeNode(schema.valueType, null, opts.position);
+    }
+    const fields = {};
+    for (const key in schema.value) {
+        fields[key] = createNode(schema.value[key], appendPath(opts, key));
+    }
+    return new ShapeNode(schema.valueType, fields, opts.position);
+}
+
+function createVariantShapeNode(schema, opts) {
+    if (!schema.value) {
+        return new VariantShapeNode(schema.valueType, null, opts.position);
+    }
+    const value = splitValue(schema.value, schema.valueType);
+    const fields = {};
+    for (const key in value.fields) {
+        fields[key] = createNode(value.fields[key], appendPath(opts, key));
+    }
+    return new VariantShapeNode(schema.valueType, { kind: value.kind, fields }, opts.position);
+}
+function splitValue(value, valueType) {
+    const kindKey = `${valueType.shapeType}Type`;
+    const { [kindKey]: kind, ...fields } = value;
+    if (!kind) {
+        throw new Error(`Missing kind field ${kindKey}`);
+    }
+    return { kind, fields };
+}
+
+function createNode(unfolded, opts) {
+    if (unfolded instanceof AbstractNode) {
+        return unfolded;
+    }
+    const node = _create(unfolded, opts);
+    if (unfolded.computation) {
+        node.computationStack.push(unfolded.computation);
+    }
+    node.bindingSchema = unfolded.binding;
+    node.extraBinding = unfolded.extraBinding;
+    return node;
+}
+const nodeCreators = {
+    component: (node, opts) => createComponentNode(node, opts),
+    array: (node, opts) => createArrayNode(node, opts),
+    map: (node, opts) => createMapNode(node, opts),
+    set: (node, opts) => createSetNode(node, opts),
+    object: (node, opts) => createObjectNode(node, opts),
+    command: (node, opts) => createCommandNode(node, opts),
+    shape: (node, opts) => createShapeNode(node, opts),
+    variantShape: (node, opts) => createVariantShapeNode(node, opts),
+    // Leaf types
+    string: (node, opts) => createLeafNode(node, opts),
+    number: (node, opts) => createLeafNode(node, opts),
+    boolean: (node, opts) => createLeafNode(node, opts),
+    unknown: (node, opts) => createLeafNode(node, opts),
+    componentSchema: (node, opts) => createLeafNode(node, opts),
+};
+function _create(node, opts) {
+    const creator = nodeCreators[node.valueType.type];
+    if (creator) {
+        return creator(node, opts);
+    }
+    // Fallback for any unknown types
+    return createLeafNode(node, opts);
+}
+
+const componentIdExtractors = {
+    array: (value, ids) => {
+        if (!Array.isArray(value))
+            return; // the check is needed for booleanInputGroup value proxies (TODO: verify)
+        for (const node of value) {
+            extractComponentsIds(node, ids);
+        }
+    },
+    object: (value, ids) => {
+        if (!value)
+            return;
+        for (const node of Object.values(value)) {
+            extractComponentsIds(node, ids);
+        }
+    },
+    map: (value, ids) => {
+        if (!value)
+            return;
+        for (const node of Object.values(value)) {
+            extractComponentsIds(node, ids);
+        }
+    },
+    component: (value, ids) => {
+        if (!value)
+            return;
+        const componentId = value;
+        ids.push(componentId);
+        const component = ComponentStore.getInstance().getComponent(componentId);
+        if (component) {
+            for (const [, propNode] of component.props) {
+                extractComponentsIds(propNode, ids);
+            }
+        }
+    },
+};
+function extractComponentsIds(node, ids = []) {
+    const value = node.structure;
+    const extractor = componentIdExtractors[node.valueType.type];
+    if (extractor) {
+        extractor(value, ids);
+    }
+    return ids;
+}
+
+function getComponent(node) {
+    if (!node.position.componentId) {
+        throw new Error('Node does not have a component context');
+    }
+    return ComponentStore.getInstance().getComponentOrThrow(node.position.componentId);
+}
+
+configure({
+    enforceActions: 'always',
+});
+class ComponentStore {
+    static instance;
+    components = new Map();
+    refSpaces = observable.map({}, { deep: false, name: 'ref-spaces-map' });
+    componentsToPreload = new Set();
+    // Index for O(m) RefSpace cleanup during component removal
+    componentsByRefSpace = new Map();
+    static getInstance() {
+        if (!ComponentStore.instance) {
+            ComponentStore.instance = new ComponentStore();
+        }
+        return ComponentStore.instance;
+    }
+    // tests purposes only
+    static reset() {
+        const store = ComponentStore.getInstance();
+        runInAction(() => {
+            // Remove all root components (components without parents)
+            // This will cascade and remove all child components and RefSpaces
+            const rootComponents = Array.from(store.components.values()).filter((c) => !c.position.componentId);
+            for (const component of rootComponents) {
+                store.removeComponent(component.id);
+            }
+            // Clear any remaining orphaned data (shouldn't be any, but just to be safe)
+            store.components.clear();
+            store.refSpaces.clear();
+            store.componentsToPreload.clear();
+            store.componentsByRefSpace.clear();
+            componentIdGenerator.reset();
+        });
+        return store;
+    }
+    addRefSpace(refSpace) {
+        runInAction(() => {
+            this.refSpaces.set(refSpace.id, refSpace);
+        });
+    }
+    addComponents(components) {
+        runInAction(() => {
+            for (const id in components) {
+                const component = components[id];
+                this.components.set(id, component);
+                // Maintain componentsByRefSpace index
+                if (!this.componentsByRefSpace.has(component.refSpaceId)) {
+                    this.componentsByRefSpace.set(component.refSpaceId, new Set());
+                }
+                this.componentsByRefSpace.get(component.refSpaceId)?.add(id);
+            }
+        });
+    }
+    getRefSpace(refSpaceId) {
+        return this.refSpaces.get(refSpaceId) ?? null;
+    }
+    getRefSpaceOrThrow(refSpaceId) {
+        const refSpace = this.getRefSpace(refSpaceId);
+        if (!refSpace) {
+            throw new Error(`RefSpace with id "${refSpaceId}" is not found.`);
+        }
+        return refSpace;
+    }
+    getComponent(componentId) {
+        return this.components.get(componentId) || null;
+    }
+    getComponentOrThrow(componentId) {
+        const component = this.getComponent(componentId);
+        if (!component) {
+            throw new Error(`Component with id "${componentId}" is not found.`);
+        }
+        return component;
+    }
+    findVariable(componentId, variableName) {
+        const component = this.getComponentOrThrow(componentId);
+        const node = component.variables.get(variableName);
+        if (node) {
+            return node;
+        }
+        const parentComponentId = component.position.componentId;
+        if (!parentComponentId) {
+            return null;
+        }
+        return this.findVariable(parentComponentId, variableName);
+    }
+    /**
+     * Find a single component using a selector relative to another component.
+     * Throws if multiple components match the selector.
+     *
+     * @param relativeTo - The component ID to search relative to
+     * @param selector - Component selector string (e.g., 'Button', '&myRef', '^parent', ':button', 'Button[disabled=true]')
+     * @returns The matching component or null if not found
+     * @throws If the selector matches multiple components
+     *
+     * @example
+     * ```typescript
+     * const button = store.findComponent(componentId, 'Button');
+     * const aliased = store.findComponent(componentId, '&myRef');
+     * const parent = store.findComponent(componentId, '^parent');
+     * const byType = store.findComponent(componentId, ':button');
+     * const filtered = store.findComponent(componentId, 'Button[disabled=true]');
+     * ```
+     */
+    findComponent(relativeTo, selector) {
+        const parsed = parseComponentSelector(selector);
+        return findComponent(relativeTo, parsed);
+    }
+    /**
+     * Find all components matching a selector relative to another component.
+     *
+     * @param relativeTo - The component ID to search relative to
+     * @param selector - Component selector string (e.g., 'Button', '&myRef', ':button', 'Button[disabled=true]')
+     * @returns Array of matching components (empty if none found)
+     *
+     * @example
+     * ```typescript
+     * const buttons = store.findComponents(componentId, 'Button');
+     * const allOfType = store.findComponents(componentId, ':button');
+     * const filtered = store.findComponents(componentId, 'Button[disabled=true]');
+     * ```
+     */
+    findComponents(relativeTo, selector) {
+        const parsed = parseComponentSelector(selector);
+        return findComponents(relativeTo, parsed);
+    }
+    /**
+     * Get a node by selector relative to a component.
+     * Throws an error if the component or node is not found.
+     * Use findNode() for optional lookups that return null instead of throwing.
+     *
+     * Note: Even if the selector contains optional chaining (?.), this method will throw
+     * if the node is not found. Use findNode() for optional chaining support.
+     *
+     * Component selector behavior:
+     * - `&ref->value` - Throws if component with ref doesn't exist
+     * - `&ref?->value` - Throws if node not found, but allows missing component (returns null for the whole expression)
+     *
+     * @param relativeTo - The component ID to search relative to
+     * @param selector - Node selector string (e.g., 'prop', '$variable', '^Parent->prop', '&ref?->value')
+     * @returns The node
+     * @throws If the component or node is not found (unless using ?-> for component)
+     *
+     * @example
+     * ```typescript
+     * const node = store.getNode(componentId, 'requiredProp'); // throws if not found
+     * const optionalNode = store.findNode(componentId, 'user?.profile'); // returns null if not found
+     * const optionalComponent = store.getNode(componentId, '&optional?->value'); // throws only if value missing, not if component missing
+     * ```
+     */
+    getNode(relativeTo, selector) {
+        const parsed = parseNodeSelector(selector);
+        // Look up the component
+        let component;
+        if (parsed.component) {
+            component = findComponent(relativeTo, parsed.component.selector);
+            // If component not found and not using optional selector, throw error
+            if (!component && !parsed.component.optional) {
+                const src = formatSource(this.getComponent(relativeTo)?.sourceUrl);
+                throw new Error(`${src} Component not found for selector '${selector}' relative to '${relativeTo}'`);
+            }
+        }
+        else {
+            component = this.getComponentOrThrow(relativeTo);
+        }
+        // If component is null (only possible with component.optional), throw
+        if (!component) {
+            const src = formatSource(this.getComponent(relativeTo)?.sourceUrl);
+            throw new Error(`${src} Component not found for selector '${selector}' relative to '${relativeTo}'`);
+        }
+        const src = formatSource(component.sourceUrl);
+        // If it's a variable path, use RefSpace chain lookup
+        if (parsed.kind === 'variable') {
+            const node = this.findVariable(component.id, parsed.head);
+            if (!node) {
+                throw new Error(`${src} Variable '${parsed.head}' does not exist in component '${component.id}' or its parent RefSpaces`);
+            }
+            const result = traverseNode(node, parsed.tail);
+            if (!result) {
+                throw new Error(`${src} Node not found for selector '${selector}' in component '${component.id}'`);
+            }
+            return result;
+        }
+        // For property paths, use strict lookup that throws on missing nodes
+        const node = component.getNodeFromParsed(parsed);
+        if (!node) {
+            throw new Error(`${src} Node not found for selector '${selector}' in component '${component.id}'`);
+        }
+        return node;
+    }
+    /**
+     * Find a node by selector relative to a component.
+     * Returns null if the node is not found.
+     *
+     * Component selector behavior:
+     * - `&ref->value` - Throws if component doesn't exist (strict by default)
+     * - `&ref?->value` - Returns null if component doesn't exist (lenient when explicit)
+     *
+     * Use `?->` to explicitly indicate that a missing component is acceptable.
+     * This makes the code self-documenting and prevents accidental null returns.
+     *
+     * @param relativeTo - The component ID to search relative to
+     * @param selector - Node selector string (e.g., 'prop', '$variable', '^Parent->prop', '&ref?->value')
+     * @returns The node or null if not found
+     *
+     * @example
+     * ```typescript
+     * // Strict - throws if component missing
+     * const node = store.findNode(componentId, '&ref->value');
+     *
+     * // Lenient - returns null if component missing
+     * const optionalNode = store.findNode(componentId, '&ref?->value');
+     * if (optionalNode) {
+     *   // Use the node
+     * }
+     * ```
+     */
+    findNode(relativeTo, selector) {
+        const parsed = parseNodeSelector(selector);
+        // If a component selector is specified, look up the component
+        let component = parsed.component
+            ? findComponent(relativeTo, parsed.component.selector)
+            : this.getComponent(relativeTo);
+        // If component not found and not using optional selector, throw error
+        if (!component && parsed.component && !parsed.component.optional) {
+            const src = formatSource(this.getComponent(relativeTo)?.sourceUrl);
+            throw new Error(`${src} Component not found for selector '${selector}' relative to '${relativeTo}'`);
+        }
+        if (!component) {
+            return null;
+        }
+        // If looking up a variable in a sys.Facade component (without explicit component selector),
+        // start search from the facade's parent. This ensures variables are resolved from the facade's
+        // context, not from within the facade itself. This only applies when using the implicit
+        // relativeTo component, not when explicitly selecting a Facade (e.g., ':sys.Facade->$var')
+        if (parsed.kind === 'variable' && !parsed.component && component.componentType === 'sys.Facade') {
+            const parentComponentId = component.position.componentId;
+            if (parentComponentId) {
+                const parentComponent = this.getComponent(parentComponentId);
+                // If parent exists, use it for variable lookup; otherwise fall back to the Facade itself
+                if (parentComponent) {
+                    component = parentComponent;
+                }
+            }
+        }
+        const src = formatSource(component.sourceUrl);
+        // If it's a variable path, use RefSpace chain lookup
+        if (parsed.kind === 'variable') {
+            const node = this.findVariable(component.id, parsed.head);
+            if (!node) {
+                // Variable itself doesn't exist - this is likely a typo, so throw
+                throw new Error(`${src} Variable "${parsed.head}" not found in component "${component.id}"`);
+            }
+            // Variable exists, traverse the path (may return null if path is missing)
+            return traverseNode(node, parsed.tail);
+        }
+        // For property paths, throw if property doesn't exist but allow null paths
+        const node = component.props.get(parsed.head);
+        if (!node) {
+            throw new Error(`${src} Property "${parsed.head}" not found in component "${component.id}" (type: ${component.componentType}). ` +
+                `Available properties: [${Array.from(component.props.keys()).join(', ')}]`);
+        }
+        // Property exists, traverse the path (may return null if path is missing)
+        return traverseNode(node, parsed.tail);
+    }
+    /**
+     * Collect node values from multiple components into an array.
+     * Maps over all components matching the selector and extracts a node value from each.
+     *
+     * @param relativeTo - The component ID to search relative to
+     * @param componentSelector - Selector for finding components (e.g., ':forms.Input', 'Button')
+     * @param nodeSelector - The node path to extract from each component (e.g., 'value', 'inputKey')
+     * @returns Array of node values from matched components
+     *
+     * @example
+     * ```typescript
+     * // Get all input values
+     * const values = store.collectValuesArray(componentId, ':forms.Input', 'value');
+     * // Returns: ['value1', 'value2', 'value3']
+     * ```
+     */
+    collectValuesArray(relativeTo, componentSelector, nodeSelector) {
+        const components = this.findComponents(relativeTo, componentSelector);
+        return components.map((component) => component.getNodeValue(nodeSelector));
+    }
+    /**
+     * Collect node values from multiple components into a map/object.
+     * Reduces over all components matching the selector, using one node as the key and another as the value.
+     *
+     * @param relativeTo - The component ID to search relative to
+     * @param componentSelector - Selector for finding components (e.g., ':forms.Input', 'Button')
+     * @param keyNodeSelector - The node path to use as the object key (e.g., 'inputKey', 'id')
+     * @param valueNodeSelector - The node path to use as the object value (e.g., 'value', 'label')
+     * @returns Object/map with keys and values from matched components
+     *
+     * @example
+     * ```typescript
+     * // Create a map from inputKey to value
+     * const map = store.collectValuesMap(componentId, ':forms.Input', 'inputKey', 'value');
+     * // Returns: { key1: 'value1', key2: 'value2' }
+     * ```
+     */
+    collectValuesMap(relativeTo, componentSelector, keyNodeSelector, valueNodeSelector) {
+        const components = this.findComponents(relativeTo, componentSelector);
+        return components.reduce((acc, component) => {
+            const key = component.getNodeValue(keyNodeSelector);
+            const value = component.getNodeValue(valueNodeSelector);
+            // skip if the key is not defined
+            if (key) {
+                acc[key] = value;
+            }
+            return acc;
+        }, {});
+    }
+    /**
+     * Set a node from a raw schema value.
+     * The raw schema will be unfolded before being applied.
+     * Handles structure, computation stack, and nested components.
+     *
+     * @param node - The node to update
+     * @param rawSchema - The raw schema value (will be unfolded into a NodeSchema)
+     */
+    setNodeRawSchema(node, rawSchema) {
+        try {
+            const unfolded = unfoldNodeSchema(rawSchema, node.valueType);
+            this.setNodeSchema(node, unfolded);
+        }
+        catch (e) {
+            const component = getComponent(node);
+            const src = formatSource(component.sourceUrl, node.position.path);
+            throw new Error(`${src} ${e.message}`, { cause: e });
+        }
+    }
+    /**
+     * Set a node from an already-unfolded schema.
+     * Use this when you already have a NodeSchema to avoid double-unfolding.
+     * Handles structure, nested components, and computation stack.
+     *
+     * @param node - The node to update
+     * @param schema - The unfolded NodeSchema to set
+     */
+    setNodeSchema(node, schema) {
+        const component = getComponent(node);
+        const refSpace = this.getRefSpaceOrThrow(component.refSpaceId);
+        const opts = {
+            refSpaceId: refSpace.id,
+            position: { componentId: component.id, path: node.position.path },
+            components: {},
+            refs: {},
+            sourceUrl: component.sourceUrl ?? undefined,
+        };
+        const tmpNode = createNode(schema, opts);
+        runInAction(() => {
+            // Handle component removal for component-type nodes
+            // Only remove components that are in the old structure but NOT in the new structure
+            // This is important for component[] types where existing component IDs may be reused
+            const oldComponents = extractComponentsIds(node);
+            const newComponents = new Set(extractComponentsIds(tmpNode));
+            for (const id of oldComponents) {
+                if (!newComponents.has(id)) {
+                    this.removeComponent(id);
+                }
+            }
+            // Set new structure and register new components/refs
+            node.structure = tmpNode.structure;
+            // Add refs for all RefSpaces (parent RefSpace and any nested RefSpaces created)
+            for (const refSpaceId in opts.refs) {
+                const targetRefSpace = this.getRefSpace(refSpaceId);
+                if (targetRefSpace) {
+                    const refs = opts.refs[refSpaceId] ?? {};
+                    targetRefSpace.addRefs(refs);
+                }
+            }
+            this.addComponents(opts.components);
+        });
+        // Push computation frame onto stack (after runAction, before activation)
+        if (schema.computation) {
+            const resultFrame = tmpNode.computationStack.top;
+            if (resultFrame) {
+                node.computationStack.push(resultFrame.schema);
+            }
+        }
+    }
+    /**
+     * Remove an item from an array node.
+     * Handles cleanup of nested components in the removed item.
+     *
+     * @param arrayNode - The array node to remove from
+     * @param index - The index of the item to remove
+     */
+    removeArrayItem(arrayNode, index) {
+        runInAction(() => {
+            const value = arrayNode.structure || [];
+            const removedItem = value[index];
+            // Clean up components in the removed item
+            if (removedItem) {
+                const oldComponents = extractComponentsIds(removedItem);
+                for (const id of oldComponents) {
+                    this.removeComponent(id);
+                }
+            }
+            arrayNode.structure = [...value.slice(0, index), ...value.slice(index + 1)];
+        });
+    }
+    /**
+     * Insert an item into an array node at a specific index.
+     * Creates a node structure from the raw value and inserts it at the specified position.
+     * Shifts existing items to the right.
+     *
+     * @param arrayNode - The array node to insert into
+     * @param index - The index at which to insert the item
+     * @param value - The raw value to insert (will be transformed into a node structure)
+     */
+    insertArrayItem(arrayNode, index, value) {
+        const { itemNode, opts, refSpace } = this.createArrayItemNode(arrayNode, index, value);
+        runInAction(() => {
+            const currentValue = arrayNode.structure || [];
+            arrayNode.structure = [...currentValue.slice(0, index), itemNode, ...currentValue.slice(index)];
+            const refs = opts.refs[refSpace.id] ?? {};
+            refSpace.addRefs(refs);
+            this.addComponents(opts.components);
+        });
+    }
+    /**
+     * Replace an item in an array node at a specific index.
+     * Creates a node structure from the raw value and replaces the item at the specified position.
+     * Properly cleans up nested components in the replaced item.
+     *
+     * @param arrayNode - The array node containing the item to replace
+     * @param index - The index of the item to replace
+     * @param value - The raw value to set (will be transformed into a node structure)
+     */
+    replaceArrayItem(arrayNode, index, value) {
+        const { itemNode, opts, refSpace } = this.createArrayItemNode(arrayNode, index, value);
+        runInAction(() => {
+            const currentValue = arrayNode.structure || [];
+            const replacedItem = currentValue[index];
+            // Clean up components in the replaced item
+            if (replacedItem) {
+                const oldComponents = extractComponentsIds(replacedItem);
+                for (const id of oldComponents) {
+                    this.removeComponent(id);
+                }
+            }
+            arrayNode.structure = [...currentValue.slice(0, index), itemNode, ...currentValue.slice(index + 1)];
+            const refs = opts.refs[refSpace.id] ?? {};
+            refSpace.addRefs(refs);
+            this.addComponents(opts.components);
+        });
+    }
+    /**
+     * Append an item to the end of an array node.
+     * Creates a node structure from the raw value and appends it to the array.
+     *
+     * @param arrayNode - The array node to append to
+     * @param value - The raw value to append (will be transformed into a node structure)
+     */
+    appendArrayItem(arrayNode, value) {
+        // Calculate the index for the new item
+        const currentLength = arrayNode.structure?.length ?? 0;
+        const { itemNode, opts, refSpace } = this.createArrayItemNode(arrayNode, currentLength, value);
+        runInAction(() => {
+            arrayNode.structure = [...(arrayNode.structure ?? []), itemNode];
+            const refs = opts.refs[refSpace.id] ?? {};
+            refSpace.addRefs(refs);
+            this.addComponents(opts.components);
+        });
+    }
+    /**
+     * Reconcile for-loop children using key-based diffing.
+     * Instead of destroying all children and recreating them,
+     * this method compares old vs new keys and only creates/destroys what's necessary.
+     *
+     * @param arrayNode - The array node containing for-loop children
+     * @param newSchemas - The new schemas to reconcile
+     * @returns Indices of newly added items for activation
+     */
+    reconcileForLoopChildren(arrayNode, newSchemas) {
+        const oldChildren = arrayNode.structure || [];
+        // Handle null/undefined newSchemas
+        if (!newSchemas) {
+            this.setNodeRawSchema(arrayNode, []);
+            return [];
+        }
+        // If there are no old children, just set the new schemas
+        if (oldChildren.length === 0) {
+            this.setNodeRawSchema(arrayNode, newSchemas);
+            return newSchemas.map((_, index) => index);
+        }
+        // If there are no new schemas, just set empty array (will remove all)
+        if (newSchemas.length === 0) {
+            this.setNodeRawSchema(arrayNode, []);
+            return [];
+        }
+        // Check if explicit keys are provided (trackBy syntax)
+        const hasExplicitKeys = this.checkForExplicitKeys(newSchemas);
+        if (!hasExplicitKeys) {
+            // No explicit keys - fall back to full replacement
+            this.setNodeRawSchema(arrayNode, newSchemas);
+            return newSchemas.map((_, index) => index);
+        }
+        // Extract keys from old children and new schemas
+        const oldKeyMap = this.extractOldKeys(oldChildren);
+        const newKeys = this.extractNewKeys(newSchemas);
+        // Check for duplicate keys in new schemas
+        const duplicateKeys = this.findDuplicateKeys(newKeys);
+        if (duplicateKeys.size > 0) {
+            log.warn(`Duplicate keys detected in for-loop: ${Array.from(duplicateKeys).join(', ')}. ` +
+                'This may cause unexpected behavior. Falling back to full replacement.');
+            this.setNodeRawSchema(arrayNode, newSchemas);
+            return newSchemas.map((_, index) => index);
+        }
+        // Build sets for diffing
+        const oldKeySet = new Set(oldKeyMap.keys());
+        const newKeySet = new Set(newKeys);
+        // Determine what to add, remove, and keep
+        const toRemove = [];
+        const toKeepSet = new Set();
+        for (const key of oldKeySet) {
+            if (newKeySet.has(key)) {
+                toKeepSet.add(key);
+            }
+            else {
+                toRemove.push(key);
+            }
+        }
+        const toAdd = [];
+        newKeys.forEach((key, index) => {
+            if (!oldKeySet.has(key)) {
+                toAdd.push(index);
+            }
+        });
+        // Perform the actual reconciliation
+        this.applyForLoopReconciliation(arrayNode, {
+            oldKeyMap,
+            newKeys,
+            newSchemas,
+            toRemove,
+            toKeep: Array.from(toKeepSet),
+        });
+        // Update loop variables (index, first, last, and item variables) for repositioned components
+        this.updateLoopVariables(arrayNode, newKeys, newSchemas, oldKeyMap);
+        return toAdd;
+    }
+    /**
+     * Apply for-loop reconciliation by building new structure and cleaning up removed components.
+     */
+    applyForLoopReconciliation(arrayNode, reconcileInfo) {
+        const { oldKeyMap, newKeys, newSchemas, toRemove, toKeep } = reconcileInfo;
+        const toKeepSet = new Set(toKeep);
+        const component = getComponent(arrayNode);
+        const refSpace = this.getRefSpaceOrThrow(component.refSpaceId);
+        // Build the new structure array, reusing kept nodes and creating new ones
+        const newStructure = [];
+        const newComponents = {};
+        const newRefs = {};
+        // Build new structure in order of new keys
+        // Use untracked to avoid MobX reactivity issues when reading structure
+        const oldStructure = untracked(() => arrayNode.structure);
+        for (let i = 0; i < newKeys.length; i++) {
+            const key = newKeys[i];
+            const oldEntry = oldKeyMap.get(key);
+            if (oldEntry && toKeepSet.has(key) && oldStructure && oldStructure[oldEntry.index]) {
+                // Reuse existing node
+                newStructure.push(oldStructure[oldEntry.index]);
+            }
+            else {
+                // Create new node
+                const schema = newSchemas[i];
+                const itemPath = [...arrayNode.position.path, i];
+                const opts = {
+                    refSpaceId: refSpace.id,
+                    position: { componentId: component.id, path: itemPath },
+                    components: {},
+                    refs: {},
+                    sourceUrl: component.sourceUrl ?? undefined,
+                };
+                const itemNode = createNode(unfoldNodeSchema(schema, arrayNode.valueType.item), opts);
+                newStructure.push(itemNode);
+                // Collect new components and refs
+                Object.assign(newComponents, opts.components);
+                const itemRefs = opts.refs[refSpace.id] ?? {};
+                Object.assign(newRefs, itemRefs);
+            }
+        }
+        runInAction(() => {
+            // Remove components that are no longer needed
+            for (const key of toRemove) {
+                const entry = oldKeyMap.get(key);
+                if (entry) {
+                    this.removeComponent(entry.componentId);
+                }
+            }
+            // Update the structure
+            arrayNode.structure = newStructure;
+            // Register new refs and components
+            refSpace.addRefs(newRefs);
+            this.addComponents(newComponents);
+        });
+    }
+    /**
+     * Update loop variables (including item variable) on components that have been repositioned or whose data changed.
+     */
+    updateLoopVariables(node, newKeys, newSchemas, oldKeyMap) {
+        const structure = node.structure || [];
+        const totalItems = newKeys.length;
+        runInAction(() => {
+            newKeys.forEach((key, newIndex) => {
+                const oldEntry = oldKeyMap.get(key);
+                if (!oldEntry)
+                    return; // Skip newly added items
+                const child = structure[newIndex];
+                if (!child)
+                    return;
+                const componentId = child.structure;
+                if (!componentId)
+                    return;
+                const component = this.getComponent(componentId);
+                if (!component)
+                    return;
+                // Update $index variable if it exists and the index changed
+                // Variables are stored without the $ prefix (e.g., 'index' not '$index')
+                const indexNode = component.variables.get('index');
+                if (indexNode && oldEntry.index !== newIndex) {
+                    indexNode.structure = newIndex;
+                }
+                // Update $first variable if it exists
+                const firstNode = component.variables.get('first');
+                if (firstNode) {
+                    const wasFirst = oldEntry.index === 0;
+                    const isFirst = newIndex === 0;
+                    if (wasFirst !== isFirst) {
+                        firstNode.structure = isFirst;
+                    }
+                }
+                // Update $last variable if it exists
+                const lastNode = component.variables.get('last');
+                if (lastNode) {
+                    lastNode.structure = newIndex === totalItems - 1;
+                }
+                // Update item variables from new schema
+                const newSchema = newSchemas[newIndex];
+                for (const [schemaKey, schemaValue] of Object.entries(newSchema)) {
+                    if (!schemaKey.startsWith('$'))
+                        continue;
+                    const varName = schemaKey.slice(1); // Remove '$' prefix
+                    // Skip loop control variables (already handled above)
+                    if (varName === 'index' || varName === 'first' || varName === 'last' || varName === 'trackBy') {
+                        continue;
+                    }
+                    const varNode = component.variables.get(varName);
+                    if (!varNode)
+                        continue;
+                    const varDef = schemaValue;
+                    if (!varDef || !('_value' in varDef))
+                        continue;
+                    // Update item variable using setNodeRawSchema for proper object handling
+                    this.setNodeRawSchema(varNode, varDef._value);
+                }
+            });
+        });
+    }
+    /**
+     * Check if schemas have explicit trackBy keys that can be used for diffing.
+     */
+    checkForExplicitKeys(schemas) {
+        if (schemas.length === 0)
+            return false;
+        const firstSchema = schemas[0];
+        if (!firstSchema)
+            return false;
+        const forKeySchema = firstSchema['$trackBy'];
+        if (forKeySchema && '_value' in forKeySchema) {
+            const value = forKeySchema._value;
+            if (typeof value === 'number') {
+                return false;
+            }
+            if (typeof value === 'string') {
+                const indexPattern = /^\d+(?::\d+)*$/;
+                return !indexPattern.test(value);
+            }
+            return true;
+        }
+        return false;
+    }
+    /**
+     * Extract keys from existing children (RefSpace components with $trackBy variable)
+     */
+    extractOldKeys(children) {
+        const keyMap = new Map();
+        children.forEach((child, index) => {
+            const componentId = child.structure;
+            if (!componentId)
+                return;
+            const component = this.getComponent(componentId);
+            if (!component || component.componentType !== 'sys.RefSpace')
+                return;
+            const keyNode = component.variables.get('trackBy');
+            const key = keyNode ? keyNode.extractedValue : component.id;
+            keyMap.set(String(key), { index, componentId });
+        });
+        return keyMap;
+    }
+    /**
+     * Extract keys from new schemas (generated by repeat())
+     */
+    extractNewKeys(schemas) {
+        return schemas.map((schema, index) => {
+            const forKeyValue = schema['$trackBy'];
+            if (forKeyValue && '_value' in forKeyValue) {
+                return String(forKeyValue._value);
+            }
+            return String(index);
+        });
+    }
+    /**
+     * Find duplicate keys in an array
+     */
+    findDuplicateKeys(keys) {
+        const seen = new Set();
+        const duplicates = new Set();
+        for (const key of keys) {
+            if (seen.has(key)) {
+                duplicates.add(key);
+            }
+            seen.add(key);
+        }
+        return duplicates;
+    }
+    removeComponent(componentId) {
+        const component = this.components.get(componentId);
+        if (!component)
+            return;
+        runInAction(() => {
+            // Collect all nested child component IDs (depth-first traversal)
+            const allChildIds = [];
+            for (const [, propNode] of component.props) {
+                extractComponentsIds(propNode, allChildIds);
+            }
+            for (const [, varNode] of component.variables) {
+                extractComponentsIds(varNode, allChildIds);
+            }
+            // Deduplicate while preserving order (later items are deeper in tree)
+            const childIds = [...new Set(allChildIds)];
+            const allIds = new Set([componentId, ...childIds]);
+            const spacesToRemove = this.collectRefSpacesToRemove(allIds);
+            // Dispose components in leaf-first order (reverse of depth-first)
+            for (let i = childIds.length - 1; i >= 0; i--) {
+                this.components.get(childIds[i])?.dispose();
+            }
+            component.dispose();
+            // Finally, delete all components and RefSpaces from registries
+            for (const id of allIds) {
+                // Remove from componentsByRefSpace index
+                const comp = this.components.get(id);
+                if (comp) {
+                    this.componentsByRefSpace.get(comp.refSpaceId)?.delete(id);
+                }
+                this.components.delete(id);
+            }
+            for (const refSpaceId of spacesToRemove) {
+                this.refSpaces.delete(refSpaceId);
+                // Clean up empty index entries
+                this.componentsByRefSpace.delete(refSpaceId);
+            }
+        });
+    }
+    /**
+     * Creates a new node for an array item from a raw value.
+     * Returns the created node and the options used (for registering components/refs).
+     * @throws If the array node has no parent component
+     */
+    createArrayItemNode(arrayNode, index, value) {
+        const component = getComponent(arrayNode);
+        const refSpace = this.getRefSpaceOrThrow(component.refSpaceId);
+        const itemPath = [...arrayNode.position.path, index];
+        const opts = {
+            refSpaceId: refSpace.id,
+            position: { componentId: component.position.componentId, path: itemPath },
+            components: {},
+            refs: {},
+            sourceUrl: component.sourceUrl ?? undefined,
+        };
+        const itemNode = createNode(unfoldNodeSchema(value, arrayNode.valueType.item), opts);
+        return { itemNode, opts, refSpace };
+    }
+    collectRefSpacesToRemove(componentIdsToDelete) {
+        // Collect unique RefSpace IDs that components belong to (candidates for removal)
+        const candidateSpaceIds = new Set();
+        for (const componentId of componentIdsToDelete) {
+            const refSpaceId = this.components.get(componentId)?.refSpaceId;
+            if (refSpaceId) {
+                candidateSpaceIds.add(refSpaceId);
+            }
+        }
+        // Filter to only RefSpaces that have no remaining components after deletion
+        const refSpaceIdsToDelete = new Set();
+        for (const refSpaceId of candidateSpaceIds) {
+            const componentsInSpace = this.componentsByRefSpace.get(refSpaceId);
+            if (!componentsInSpace)
+                continue;
+            // Check if ALL components in this RefSpace are being deleted
+            let allDeleted = true;
+            for (const id of componentsInSpace) {
+                if (!componentIdsToDelete.has(id)) {
+                    allDeleted = false;
+                    break;
+                }
+            }
+            if (allDeleted) {
+                refSpaceIdsToDelete.add(refSpaceId);
+            }
+        }
+        return refSpaceIdsToDelete;
+    }
+}
+
+function createRootNode(refSpaceId, schema, ownerComponentId, parentRefSpaceId, sourceUrl) {
+    const opts = {
+        refSpaceId: refSpaceId,
+        position: { componentId: ownerComponentId, path: [] },
+        components: {},
+        refs: {},
+        sourceUrl,
+    };
+    const root = createNode(schema, opts);
+    const refSpace = new RefSpace(refSpaceId, parentRefSpaceId);
+    const store = ComponentStore.getInstance();
+    store.addRefSpace(refSpace);
+    store.addComponents(opts.components);
+    const refs = opts.refs[refSpaceId] ?? {};
+    refSpace.addRefs(refs);
+    return root;
+}
+
+class ComponentTreeApi {
+    static store = ComponentStore.getInstance();
+    static findComponent(relativeTo, componentSelector) {
+        return this.store.findComponent(relativeTo, componentSelector);
+    }
+    static findComponentsIds(relativeTo, componentSelector) {
+        return findComponentsIds(relativeTo, parseComponentSelector(componentSelector));
+    }
+    static findComponents(relativeTo, componentSelector) {
+        const ids = this.findComponentsIds(relativeTo, componentSelector);
+        return ids.map((id) => this.store.getComponentOrThrow(id));
+    }
+    static getComponent(relativeTo, componentSelector) {
+        const component = this.store.findComponent(relativeTo, componentSelector);
+        if (!component) {
+            throw new Error(`Component ${componentSelector} not found`);
+        }
+        return component;
+    }
+    static findNode(relativeTo, componentSelector) {
+        return this.store.findNode(relativeTo, componentSelector);
+    }
+    static getNode(relativeTo, componentSelector) {
+        return this.store.getNode(relativeTo, componentSelector);
+    }
+    static collectValuesArray(componentId, componentSelector, nodeSelector) {
+        try {
+            return this.store.collectValuesArray(componentId, componentSelector, nodeSelector);
+        }
+        catch (e) {
+            log.error(`Error collecting values as array by component selector ${componentSelector}`, e);
+            return [];
+        }
+    }
+    static collectValuesMap(componentId, componentSelector, keyNodeSelector, valueNodeSelector) {
+        try {
+            return this.store.collectValuesMap(componentId, componentSelector, keyNodeSelector, valueNodeSelector);
+        }
+        catch (e) {
+            log.error(`Error collecting values as map by component selector ${componentSelector}`, e);
+            return {};
+        }
+    }
+    static isCommandRunning(componentId, selector) {
+        try {
+            const node = this.getNode(componentId, selector);
+            if (!isCommandNode(node)) {
+                throw new Error(`Error`);
+            }
+            return node.viewModel.executing;
+        }
+        catch (e) {
+            log.error(`Error checking command running state by selector ${selector}`, e);
+            return false;
+        }
+    }
+    static runCommandNode(componentId, selector, ...args) {
+        try {
+            const node = this.getNode(componentId, selector);
+            if (!isCommandNode(node)) {
+                throw new Error(`Node at "${selector}" is not a command`);
+            }
+            log.trace(`Running command "${selector}" on ${componentId}`);
+            return node.viewModel.execute(...args);
+        }
+        catch (e) {
+            log.error(`Error running command by selector "${selector}" with args:`, JSON.stringify(args), e);
+            return null;
+        }
+    }
+    static setNodeRawSchema(componentId, selector, value) {
+        try {
+            const node = this.getNode(componentId, selector);
+            this.store.setNodeRawSchema(node, value);
+        }
+        catch (e) {
+            log.error(`Error setting node by selector "${selector}" with value:`, value, e);
+        }
+    }
+    static appendArrayItem(componentId, selector, item) {
+        try {
+            const arrayNode = this.store.getNode(componentId, selector);
+            this.store.appendArrayItem(arrayNode, item);
+        }
+        catch (e) {
+            log.error(`Error appending array item to selector "${selector}" with value:`, item, e);
+        }
+    }
+    static insertArrayItem(componentId, selector, index, item) {
+        try {
+            const arrayNode = this.store.getNode(componentId, selector);
+            this.store.insertArrayItem(arrayNode, index, item);
+        }
+        catch (e) {
+            log.error(`Error inserting array item to selector "${selector}" with value:`, item, e);
+        }
+    }
+    static removeArrayItem(componentId, selector, index) {
+        try {
+            const arrayNode = this.store.getNode(componentId, selector);
+            this.store.removeArrayItem(arrayNode, index);
+        }
+        catch (e) {
+            log.error(`Error removing array item from selector "${selector}" at index ${index}`, e);
+        }
+    }
+    static replaceArrayItem(componentId, selector, index, item) {
+        try {
+            const arrayNode = this.store.getNode(componentId, selector);
+            this.store.replaceArrayItem(arrayNode, index, item);
+        }
+        catch (e) {
+            log.error(`Error replacing array item at selector "${selector}" at index ${index} with value:`, item, e);
+        }
+    }
+}
+
+/**
+ * Generated bundle index. Do not edit.
+ */
+
+export { AbstractNode, AbstractObjectLikeNode, ArrayNode, CommandNode, ComponentStore, ComponentTreeApi, ComputationFrame, ComputationStack, LeafNode, MapNode, ObjectNode, RefSpace, SetNode, ShapeNode, TComponent, VariantShapeNode, componentTreeConfig, createRootNode, formatSource, getComponent, isArrayNode, isCommandNode };
+//# sourceMappingURL=kaskad-component-tree.mjs.map