@mintjamsinc/ichigojs 0.1.68 → 0.1.70

package/dist/ichigo.esm.js

@@ -8393,6 +8393,31 @@ class VBindings {
      * 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.
@@ -8404,8 +8429,13 @@ class VBindings {
         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);
                 }
@@ -8663,6 +8693,79 @@ class VBindings {
     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
@@ -10264,9 +10367,18 @@ class VForDirective {
     #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
      */
@@ -10389,11 +10501,11 @@ class VForDirective {
     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();
@@ -10404,7 +10516,7 @@ class VForDirective {
                 vNode.node.parentNode.removeChild(vNode.node);
             }
         }
-        this.#renderedItems.clear();
+        this.#renderedItems = [];
         this.#previousIterations = [];
     }
     /**
@@ -10445,7 +10557,24 @@ class VForDirective {
         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;
@@ -10453,22 +10582,38 @@ class VForDirective {
         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();
             }
@@ -10487,11 +10632,12 @@ class VForDirective {
                 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();
@@ -10523,7 +10669,7 @@ class VForDirective {
                 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;
@@ -10537,12 +10683,12 @@ class VForDirective {
                 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.
@@ -10568,7 +10714,7 @@ class VForDirective {
             // 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;
     }
     /**
@@ -13805,7 +13951,11 @@ class VApplication {
     #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
@@ -13855,8 +14005,17 @@ class VApplication {
                 }
             }
         }
-        // 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.
@@ -13907,8 +14066,9 @@ class VApplication {
      * 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]
@@ -13953,110 +14113,116 @@ class VApplication {
         }
     }
     /**
-     * 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}`);
         }
     }
     /**