@mintjamsinc/ichigojs 0.1.68 → 0.1.70

package/dist/ichigo.cjs

@@ -8399,6 +8399,31 @@
          * is replaced, the binding is set to null/undefined, or the bindings are destroyed.
          */
         #externalSubscriptions = new Map();
+        /**
+         * Recompute callbacks for computed properties registered on these bindings.
+         * Maps a computed property name to a function that recomputes and caches its value.
+         * Only the bindings instance that owns the computed (typically the root) holds an entry;
+         * child bindings resolve computed reads by delegating to their parent through the proxy.
+         */
+        #computedRecomputers = new Map();
+        /**
+         * The set of computed properties whose cached value is stale and must be recomputed on next
+         * access (pull-based evaluation). Populated by markComputedDirty when a dependency changes,
+         * and cleared as each computed is resolved.
+         */
+        #dirtyComputeds = new Set();
+        /**
+         * Guard set used to detect re-entrant (circular) computed resolution. While a computed is
+         * being recomputed its name is held here; a nested read of the same computed returns the
+         * currently cached (stale) value instead of recursing infinitely.
+         */
+        #resolvingComputeds = new Set();
+        /**
+         * The plain backing object behind the #local proxy. Kept as a direct reference so the cached
+         * value of a computed property can be read without triggering pull-based re-evaluation
+         * (see peekComputed).
+         */
+        #store = {};
         /**
          * Creates a new instance of VBindings.
          * @param parent The parent bindings, if any.
@@ -8410,8 +8435,13 @@
             if (this.#logger?.isDebugEnabled) {
                 this.#logger.debug(`VBindings created. Parent: ${this.#parent ? 'yes' : 'no'}`);
             }
-            this.#local = new Proxy({}, {
+            this.#local = new Proxy(this.#store, {
                 get: (obj, key) => {
+                    // Pull-based evaluation: if this key is a dirty computed property, recompute it now
+                    // so the read returns a fresh value (synchronously, even before the update microtask).
+                    if (typeof key === 'string') {
+                        this.#resolveComputedIfDirty(key);
+                    }
                     if (Reflect.has(obj, key)) {
                         return Reflect.get(obj, key);
                     }
@@ -8669,6 +8699,79 @@
         registerWritableComputed(key, setter) {
             this.#writableComputeds.set(key, setter);
         }
+        /**
+         * Registers a computed property for pull-based (lazy) evaluation. The provided recompute
+         * callback is invoked the first time the property is read after it has been marked dirty
+         * (or during the pre-render flush), and is expected to update the cached value (typically
+         * via setSilent).
+         * @param key The computed property name.
+         * @param recompute The callback that recomputes and caches the property's value.
+         */
+        registerComputed(key, recompute) {
+            this.#computedRecomputers.set(key, recompute);
+        }
+        /**
+         * Marks a computed property as dirty so it will be recomputed on next access.
+         * @param key The computed property name.
+         */
+        markComputedDirty(key) {
+            this.#dirtyComputeds.add(key);
+        }
+        /**
+         * Reads the currently cached value of a computed property without triggering pull-based
+         * re-evaluation. Used by the recompute routine to obtain the previous value for change
+         * detection. Falls back to the parent bindings when the key is not stored locally.
+         * @param key The computed property name.
+         * @returns The cached value, or undefined if not cached.
+         */
+        peekComputed(key) {
+            if (Object.prototype.hasOwnProperty.call(this.#store, key)) {
+                return this.#store[key];
+            }
+            return this.#parent?.peekComputed(key);
+        }
+        /**
+         * Forces resolution of every computed property currently marked dirty. Called before the DOM
+         * diff and watcher notification so that the set of changed identifiers is complete.
+         */
+        flushDirtyComputeds() {
+            for (const key of [...this.#dirtyComputeds]) {
+                this.#resolveComputedIfDirty(key);
+            }
+        }
+        /**
+         * Resolves a computed property if its cached value is dirty (pull-based evaluation), by
+         * invoking its registered recompute callback. Computed→computed chains resolve naturally:
+         * reading another computed inside the getter re-enters this method for that key. Re-entrant
+         * resolution of the same key (a circular dependency) is detected and short-circuited, leaving
+         * the previously cached value in place.
+         * @param key The property name to resolve.
+         */
+        #resolveComputedIfDirty(key) {
+            const recompute = this.#computedRecomputers.get(key);
+            if (!recompute) {
+                // Not a computed owned by these bindings; a parent (if any) resolves it when the value
+                // is read through the proxy delegation in the get trap.
+                return;
+            }
+            if (!this.#dirtyComputeds.has(key)) {
+                return;
+            }
+            if (this.#resolvingComputeds.has(key)) {
+                this.#logger?.warn(`Circular dependency detected while resolving computed property '${key}'.`);
+                return;
+            }
+            this.#resolvingComputeds.add(key);
+            try {
+                // Clear the dirty flag before recomputing so reads of this same key during recomputation
+                // (other than a true cycle) do not attempt to resolve it again.
+                this.#dirtyComputeds.delete(key);
+                recompute();
+            }
+            finally {
+                this.#resolvingComputeds.delete(key);
+            }
+        }
         /**
          * Manually adds an identifier to the set of changed identifiers.
          * This is useful for computed properties that need to mark themselves as changed
@@ -10270,9 +10373,18 @@
         #sourceName;
         #useOfSyntax = false; // Track if 'of' syntax was used
         /**
-         * Map to track rendered items by their keys
+         * Ordered list of currently rendered items.
+         *
+         * This is intentionally an ordered array of { key, vNode } entries rather
+         * than a Map<key, VNode>. The :key attribute is a *reconciliation hint*
+         * used to identify and reuse the same logical row across re-renders — it is
+         * not the identity of the rendered set. Keying the rendered set by a Map
+         * would make it structurally impossible to hold two rows that resolve to
+         * the same key, which would silently drop application data. The most
+         * fundamental invariant of a list directive is "N items in => N rows out",
+         * so the rendered set must be a positional list that can carry duplicates.
          */
-        #renderedItems = new Map();
+        #renderedItems = [];
         /**
          * Previous iterations to detect changes
          */
@@ -10395,11 +10507,11 @@
         destroy() {
             // Clean up all rendered items
             // First destroy all VNodes (calls @unmount hooks), then remove from DOM
-            for (const vNode of this.#renderedItems.values()) {
+            for (const { vNode } of this.#renderedItems) {
                 vNode.destroy();
             }
             // Then remove DOM nodes
-            for (const vNode of this.#renderedItems.values()) {
+            for (const { vNode } of this.#renderedItems) {
                 const range = vNode.fragmentRange;
                 if (range) {
                     range.remove();
@@ -10410,7 +10522,7 @@
                     vNode.node.parentNode.removeChild(vNode.node);
                 }
             }
-            this.#renderedItems.clear();
+            this.#renderedItems = [];
             this.#previousIterations = [];
         }
         /**
@@ -10451,7 +10563,24 @@
             this.#previousIterations = iterations;
         }
         /**
-         * Key-based diffing for efficient DOM updates
+         * Key-based diffing for efficient DOM updates.
+         *
+         * Reconciliation model
+         * --------------------
+         * The :key attribute is treated as a *hint* for reusing the same logical
+         * row across re-renders, not as the identity of the rendered set. The
+         * previously rendered rows are placed into a pool keyed by :key (a queue
+         * per key, so equal keys can hold more than one row). Each incoming
+         * iteration then claims a row from its key's queue when one is available,
+         * otherwise a fresh row is created. Whatever stays in the pool at the end
+         * is genuinely gone and is destroyed and removed.
+         *
+         * This guarantees the directive's most fundamental invariant — "N items in
+         * => N rows out" — even when the application supplies duplicate keys. We
+         * still warn on duplicates because they make reuse ambiguous (reordering
+         * becomes positional rather than identity-stable), but we never silently
+         * drop the application's data, and no row is ever orphaned: every old row
+         * is either reused or explicitly removed.
          */
         #updateList(newIterations) {
             const parent = this.#vNode.anchorNode?.parentNode;
@@ -10459,22 +10588,38 @@
             if (!parent || !anchor) {
                 throw new Error('v-for element must have a parent and anchor');
             }
-            const newRenderedItems = new Map();
-            // Track which keys are still needed and detect duplicates
-            const neededKeys = new Set();
+            // Build a reuse pool from the currently rendered rows. A queue per key
+            // (FIFO) lets duplicate keys reuse multiple rows: the first incoming
+            // occurrence claims the first existing row, the second claims the next,
+            // and so on.
+            const pool = new Map();
+            for (const { key, vNode } of this.#renderedItems) {
+                let queue = pool.get(key);
+                if (!queue) {
+                    queue = [];
+                    pool.set(key, queue);
+                }
+                queue.push(vNode);
+            }
+            // Decide, for each incoming iteration in order, whether it reuses an
+            // existing row or needs a new one. Reused rows are taken out of the
+            // pool so that what remains afterwards is exactly the set to remove.
             const seenKeys = new Set();
-            for (const ctx of newIterations) {
-                if (seenKeys.has(ctx.key)) {
-                    console.warn(`[ichigo.js] Duplicate key detected in v-for: "${ctx.key}". This may cause unexpected behavior. Keys should be unique.`);
+            const plan = [];
+            for (const context of newIterations) {
+                if (seenKeys.has(context.key)) {
+                    console.warn(`[ichigo.js] Duplicate key detected in v-for: "${context.key}". All entries are still rendered, but reordering may be unstable. Keys should be unique.`);
                 }
-                seenKeys.add(ctx.key);
-                neededKeys.add(ctx.key);
+                seenKeys.add(context.key);
+                const queue = pool.get(context.key);
+                const reused = queue && queue.length ? queue.shift() : undefined;
+                plan.push({ context, reused });
             }
-            // Remove items that are no longer needed
+            // Remove rows that were not reused.
             // First destroy VNodes (calls @unmount hooks while DOM is still accessible)
             const nodesToRemove = [];
-            for (const [key, vNode] of this.#renderedItems) {
-                if (!neededKeys.has(key)) {
+            for (const queue of pool.values()) {
+                for (const vNode of queue) {
                     nodesToRemove.push(vNode);
                     vNode.destroy();
                 }
@@ -10493,11 +10638,12 @@
                     parentOfNode.removeChild(vNode.node);
                 }
             }
-            // Add or reorder items
+            // Add or reorder rows, building the new ordered rendered set.
+            const newRenderedItems = [];
             let prevNode = anchor;
-            for (const context of newIterations) {
+            for (const { context, reused } of plan) {
                 const { key } = context;
-                let vNode = this.#renderedItems.get(key);
+                let vNode = reused;
                 if (!vNode) {
                     // Create new item
                     const clone = this.#cloneNode();
@@ -10529,7 +10675,7 @@
                     if (clone.nodeType === Node.DOCUMENT_FRAGMENT_NODE) {
                         const range = VFragmentRange.insert(parent, prevNode.nextSibling, 'vfor-fragment', clone);
                         vNode.fragmentRange = range;
-                        newRenderedItems.set(key, vNode);
+                        newRenderedItems.push({ key, vNode });
                         vNode.forceUpdate();
                         prevNode = range.lastNode;
                         continue;
@@ -10543,12 +10689,12 @@
                     else {
                         parent.appendChild(nodeToInsert);
                     }
-                    newRenderedItems.set(key, vNode);
+                    newRenderedItems.push({ key, vNode });
                     vNode.forceUpdate();
                 }
                 else {
                     // Reuse existing item
-                    newRenderedItems.set(key, vNode);
+                    newRenderedItems.push({ key, vNode });
                     // Update bindings
                     this.#updateItemBindings(vNode, context);
                     // For fragment-backed iterations, move the entire range atomically.
@@ -10574,7 +10720,7 @@
                 // Advance prevNode to this iteration's last DOM node
                 prevNode = vNode.fragmentRange?.lastNode ?? vNode.anchorNode ?? vNode.node;
             }
-            // Update rendered items map
+            // Update the ordered rendered set
             this.#renderedItems = newRenderedItems;
         }
         /**
@@ -13811,7 +13957,11 @@
         #initializeBindings() {
             // Create bindings with change tracking
             this.#bindings = new VBindings({
-                onChange: () => {
+                onChange: (identifier) => {
+                    // Pull-based invalidation: mark dependent computed properties dirty synchronously
+                    // so a subsequent synchronous read returns a fresh value, then schedule the
+                    // batched DOM update for the next microtask.
+                    this.#markDirtyComputeds(identifier);
                     this.#scheduleUpdate();
                 },
                 vApplication: this
@@ -13861,8 +14011,17 @@
                     }
                 }
             }
-            // Add computed properties (initialization mode)
-            this.#recomputeProperties(true);
+            // Register computed properties for pull-based (lazy) evaluation. Each computed is
+            // recomputed on first access after being marked dirty, rather than eagerly in the update
+            // microtask. We mark them all dirty and resolve once here so that initial values are
+            // cached and recorded as changes for the first render.
+            if (this.#options.computed) {
+                for (const key of Object.keys(this.#options.computed)) {
+                    this.#bindings.registerComputed(key, () => this.#recomputeOne(key));
+                    this.#bindings.markComputedDirty(key);
+                }
+            }
+            this.#flushDirtyComputeds();
         }
         /**
          * Initializes watchers from the watch option.
@@ -13913,8 +14072,9 @@
          * Executes an immediate DOM update.
          */
         #update() {
-            // Re-evaluate computed properties that depend on changed values
-            this.#recomputeProperties();
+            // Resolve any computed properties still marked dirty (those not already pulled by a
+            // synchronous read) so that the set of changed identifiers is complete before the DOM diff.
+            this.#flushDirtyComputeds();
             // Apply computed source path mappings to changes
             // This converts paths like "model.elements[0].executionListeners"
             // to "selectedElement.executionListeners" when selectedElement points to model.elements[0]
@@ -13959,110 +14119,116 @@
             }
         }
         /**
-         * Recursively recomputes computed properties based on changed identifiers.
-         * @param isInitialization - If true, computes all computed properties regardless of dependencies
+         * Marks computed properties as dirty (pull-based invalidation) when a dependency changes.
+         * Uses the statically analyzed dependency graph; because computed→computed dependencies are
+         * flattened to their underlying reactive paths during analysis, a single change marks every
+         * transitively dependent computed dirty in one pass. The actual recomputation is deferred until
+         * the value is read (see #recomputeOne).
+         * @param identifier The changed identifier reported by the bindings change tracker.
          */
-        #recomputeProperties(isInitialization = false) {
-            if (!this.#options.computed) {
+        #markDirtyComputeds(identifier) {
+            if (!this.#options.computed || !this.#bindings) {
                 return;
             }
-            const computed = new Set();
-            const processing = new Set();
-            // Gather all changed identifiers, including all parent paths
-            // e.g., for "model.elements[0].messageRef", also add:
-            // "model.elements[0]", "model.elements", "model"
-            const allChanges = new Set();
-            this.#bindings?.changes.forEach(id => {
-                allChanges.add(id);
-                // Add all parent paths by progressively stripping from the end
-                let path = id;
-                while (path.length > 0) {
-                    // Find last separator (either '[' or '.')
-                    const bracketIdx = path.lastIndexOf('[');
-                    const dotIdx = path.lastIndexOf('.');
-                    const lastSep = Math.max(bracketIdx, dotIdx);
-                    if (lastSep === -1) {
-                        break;
-                    }
-                    path = path.substring(0, lastSep);
-                    if (path.length > 0) {
-                        allChanges.add(path);
-                    }
-                }
-            });
-            // Helper function to recursively compute a property
-            const compute = (key) => {
-                // Skip if already computed in this update cycle
-                if (computed.has(key)) {
-                    return;
-                }
-                // Detect circular dependency
-                if (processing.has(key)) {
-                    this.#logger.error(`Circular dependency detected for computed property '${key}'`);
-                    return;
-                }
-                processing.add(key);
-                // Get the dependencies for this computed property
+            for (const key of Object.keys(this.#computedDependencies)) {
                 const deps = this.#computedDependencies[key] || [];
-                // First, recursively compute any dependent computed properties.
-                // This must happen before the change check so that computed→computed
-                // dependency chains are resolved and allChanges is up-to-date.
-                for (const dep of deps) {
-                    if (this.#options.computed[dep]) {
-                        compute(dep);
-                    }
-                }
-                // If none of the dependencies have changed, skip recomputation (unless it's initialization).
-                // Checked after recursive computation to detect transitive changes through computed properties.
-                if (!isInitialization && !deps.some(dep => allChanges.has(dep))) {
-                    computed.add(key);
-                    return;
+                if (deps.some(dep => this.#dependencyAffectedBy(dep, identifier))) {
+                    this.#bindings.markComputedDirty(key);
                 }
-                // Now compute this property
-                const computedFn = VApplication.#getComputedGetter(this.#options.computed[key]);
-                try {
-                    const oldValue = this.#bindings?.get(key);
-                    const newValue = computedFn.call(this.#bindings?.raw);
-                    // Check if the value actually changed
-                    let hasChanged = oldValue !== newValue;
-                    // For arrays, always update (VBindings will detect length changes via its length cache)
-                    if (!hasChanged && Array.isArray(newValue)) {
-                        hasChanged = true;
-                    }
-                    if (hasChanged) {
-                        // Use setSilent to avoid triggering onChange during computed property updates
-                        // Then mark the computed property as changed so UI depending on it will update
-                        this.#bindings?.setSilent(key, newValue);
-                        this.#bindings?.markChanged(key);
-                        allChanges.add(key);
-                        // Track source path mapping for computed property values
-                        // This allows changes like "model.elements[0].x" to be mapped to "selectedElement.x"
-                        if (typeof newValue === 'object' && newValue !== null) {
-                            const sourcePath = ReactiveProxy.getPath(newValue);
-                            if (sourcePath) {
-                                // Remove old mapping for this computed property
-                                for (const [path, name] of this.#computedSourcePaths) {
-                                    if (name === key) {
-                                        this.#computedSourcePaths.delete(path);
-                                        break;
-                                    }
+            }
+        }
+        /**
+         * Determines whether a change to `changePath` affects a computed dependency `dep`, taking both
+         * path directions into account:
+         *  - an exact match;
+         *  - `changePath` is a descendant of `dep` (e.g. dep "cartItems", change "cartItems.0.quantity")
+         *    — a nested mutation of the dependency;
+         *  - `dep` is a descendant of `changePath` (e.g. dep "user.name", change "user") — the container
+         *    holding the dependency was replaced wholesale.
+         * Local and global path aliases (e.g. computed source paths) are also honored via the bindings'
+         * own alias-aware matcher.
+         * @param dep The dependency path declared by a computed property.
+         * @param changePath The identifier reported by the bindings change tracker.
+         */
+        #dependencyAffectedBy(dep, changePath) {
+            if (changePath === dep) {
+                return true;
+            }
+            if (changePath.startsWith(dep + '.') || changePath.startsWith(dep + '[')) {
+                return true;
+            }
+            if (dep.startsWith(changePath + '.') || dep.startsWith(changePath + '[')) {
+                return true;
+            }
+            // Fall back to alias-aware matching for aliased paths (computed source paths, props, etc.).
+            return this.#bindings.doesChangeMatchIdentifier(changePath, dep);
+        }
+        /**
+         * Forces resolution of all computed properties currently marked dirty so that the set of
+         * changed identifiers is complete before watcher notification and the DOM diff. Computeds that
+         * were already pulled by a synchronous read earlier in the cycle are no longer dirty and are
+         * skipped, so each computed is recomputed at most once per update cycle.
+         */
+        #flushDirtyComputeds() {
+            this.#bindings?.flushDirtyComputeds();
+        }
+        /**
+         * Recomputes a single computed property and updates its cached value. Registered with the
+         * bindings as the pull-based recompute callback, so it runs lazily the first time the property
+         * is read after being marked dirty (or during the pre-render flush). Computed→computed chains
+         * resolve naturally and order-independently: reading a dependent computed inside the getter
+         * triggers its own lazy resolution through the bindings proxy.
+         *
+         * When the value actually changes, the computed name is recorded as a change so that
+         * dependency-precise DOM updates and watcher notifications still fire, and the source-path
+         * mapping is refreshed so nested changes to the underlying object map back to the computed.
+         * @param key The computed property name.
+         */
+        #recomputeOne(key) {
+            if (!this.#options.computed || !this.#bindings) {
+                return;
+            }
+            const def = this.#options.computed[key];
+            if (!def) {
+                return;
+            }
+            const computedFn = VApplication.#getComputedGetter(def);
+            try {
+                // Read the previous value without triggering re-resolution, for change detection.
+                const oldValue = this.#bindings.peekComputed(key);
+                const newValue = computedFn.call(this.#bindings.raw);
+                // Check if the value actually changed.
+                let hasChanged = oldValue !== newValue;
+                // For arrays, always treat as changed (VBindings detects length changes via its length
+                // cache). This preserves the precise-update behavior of the previous eager implementation.
+                if (!hasChanged && Array.isArray(newValue)) {
+                    hasChanged = true;
+                }
+                // Cache the value silently so the read returns it without re-triggering reactivity.
+                this.#bindings.setSilent(key, newValue);
+                if (hasChanged) {
+                    // Mark the computed property as changed so UI and watchers depending on it update.
+                    this.#bindings.markChanged(key);
+                    // Track source path mapping for computed property values.
+                    // This allows changes like "model.elements[0].x" to be mapped to "selectedElement.x".
+                    if (typeof newValue === 'object' && newValue !== null) {
+                        const sourcePath = ReactiveProxy.getPath(newValue);
+                        if (sourcePath) {
+                            // Remove old mapping for this computed property
+                            for (const [path, name] of this.#computedSourcePaths) {
+                                if (name === key) {
+                                    this.#computedSourcePaths.delete(path);
+                                    break;
                                 }
-                                // Add new mapping
-                                this.#computedSourcePaths.set(sourcePath, key);
                             }
+                            // Add new mapping
+                            this.#computedSourcePaths.set(sourcePath, key);
                         }
                     }
                 }
-                catch (error) {
-                    this.#logger.error(`Error evaluating computed property '${key}': ${error}`);
-                }
-                computed.add(key);
-                processing.delete(key);
-            };
-            // Compute all properties; the recursive logic inside compute() handles
-            // dependency ordering and skips properties whose dependencies did not change.
-            for (const key of Object.keys(this.#computedDependencies)) {
-                compute(key);
+            }
+            catch (error) {
+                this.#logger.error(`Error evaluating computed property '${key}': ${error}`);
             }
         }
         /**