shortcutxl 0.3.76 → 0.3.78

package/native-app/renderer/index.html

@@ -4,8 +4,8 @@
     <meta charset="UTF-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
     <title>Shortcut CLI</title>
-    <script type="module" crossorigin src="./assets/index-CFc-oZuS.js"></script>
-    <link rel="stylesheet" crossorigin href="./assets/index-OhGE0UY4.css">
+    <script type="module" crossorigin src="./assets/index-B4jz6epR.js"></script>
+    <link rel="stylesheet" crossorigin href="./assets/index-C__g36ft.css">
   </head>
   <body>
     <div id="root"></div>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "shortcutxl",
-  "version": "0.3.76",
+  "version": "0.3.78",
   "license": "MIT",
   "type": "module",
   "types": "./dist/index.d.ts",
@@ -33,6 +33,10 @@
       "types": "./dist/app/file-uploads.d.ts",
       "default": "./dist/app/file-uploads.js"
     },
+    "./app/tool-binaries": {
+      "types": "./dist/app/tools/tool-binaries.d.ts",
+      "default": "./dist/app/tools/tool-binaries.js"
+    },
     "./app/providers/message-converter": {
       "types": "./dist/app/providers/message-converter.d.ts",
       "default": "./dist/app/providers/message-converter.js"
@@ -145,6 +149,14 @@
       "types": "./dist/tui/index.d.ts",
       "default": "./dist/tui/index.js"
     },
+    "./autocomplete": {
+      "types": "./dist/autocomplete/index.d.ts",
+      "default": "./dist/autocomplete/index.js"
+    },
+    "./autocomplete/core": {
+      "types": "./dist/autocomplete/core.d.ts",
+      "default": "./dist/autocomplete/core.js"
+    },
     "./host-tools": {
       "types": "./dist/embedded-agent/host-tools/index.d.ts",
       "default": "./dist/embedded-agent/host-tools/index.js"
@@ -255,12 +267,11 @@
     "electron": "42.6.1",
     "extract-zip": "^2.0.1",
     "file-type": "^21.3.1",
-    "glob": "^13.0.6",
     "hosted-git-info": "^9.0.2",
     "ignore": "^7.0.5",
     "jose": "^6.2.2",
     "marked": "^15.0.12",
-    "minimatch": "^10.2.4",
+    "minimatch": "^10.2.6",
     "openai": "6.10.0",
     "partial-json": "^0.1.7",
     "proper-lockfile": "^4.1.2",
@@ -342,8 +353,11 @@
     "test": "pnpm run build:mogruntime && vitest --run",
     "dev:integration": "tsx tests/connectors/runner/run-agentic-integration.ts",
     "test:e2e": "vitest --run --config vitest.e2e.config.ts",
+    "test:e2e:provider-native-agentic": "vitest --run --config vitest.e2e.config.ts tests/embedded-agent/provider-native-agentic",
     "test:manual-smoke:whatsapp-live": "vitest --run --config vitest.e2e.config.ts tests/remote-control/whatsapp-cli.live-provider.manual-smoke.test.ts",
     "test:pty": "vitest --run --config vitest.pty.config.ts",
+    "test:pty:windows-smoke": "vitest --run --config vitest.pty.config.ts tests/helpers/pty/driver.pty.test.ts",
+    "test:windows-approvals": "vitest --run --config vitest.windows-approvals.config.ts",
     "test:tui-sim": "vitest --run --config vitest.tui-sim.config.ts",
     "smoke:rpc": "node scripts/smoke-rpc-host.js",
     "analyze:tui-trace": "node scripts/analyze-tui-render-trace.js",

package/skills/add-custom-model/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: add-custom-model
+description: Add or update a custom model in ShortcutXL. Use when the user wants to connect a hosted model, local model, gateway, or proxy.
+---
+
+# Add a Custom Model
+
+Add the model to `~/.shortcut/agent/models.json`.
+
+## Steps
+
+1. Read `models.md` from the Agent Docs `Additional docs` path in the system prompt.
+2. Get the following details from the user or the provider's documentation:
+   - Provider ID
+   - Base URL
+   - API type
+   - Model ID
+   - API key or API-key environment variable
+3. Read the existing `models.json`. Preserve its current providers and models.
+4. Add or update the requested provider and model.
+5. Validate the JSON.
+6. Open `/model` and select the new model. Opening `/model` reloads the file.
+7. Test a response and a tool call.
+
+Use one of these API types:
+
+- `openai-completions`
+- `openai-responses`
+- `anthropic-messages`
+- `google-generative-ai`
+
+Use this minimal configuration:
+
+```json
+{
+  "providers": {
+    "provider-id": {
+      "baseUrl": "https://provider.example/v1",
+      "api": "openai-completions",
+      "apiKey": "PROVIDER_API_KEY",
+      "models": [{ "id": "model-id" }]
+    }
+  }
+}
+```
+
+Prefer an environment-variable name for `apiKey` and confirm that it is set.
+For a local server without authentication, use a non-empty placeholder such as
+`local`. Never expose an API key in the response.
+
+If the provider does not support one of the listed APIs, it cannot be added
+through `models.json`.

package/user-docs/dist/index.html

@@ -1908,7 +1908,7 @@ Excel automatically loads ShortcutXL on startup. No manual setup needed again.
 npm update -g shortcutxl
 ```
 
-ShortcutXL tells you when a new version is available. The Excel add-in auto-syncs with the agent — no separate update needed.
+ShortcutXL checks for updates asynchronously every 12 hours. When a new version is available, restart the CLI and choose **Update now** in the startup prompt. The Excel add-in auto-syncs with the agent — no separate update needed.
 
 
 

package/xll/modules/shortcut_xl/_managed.py

@@ -6,7 +6,8 @@ from shortcut_xl._com import xl_app
 from shortcut_xl._exec_sandbox import active_exec_sandbox, build_safe_builtins
 from shortcut_xl._log import xl_log
 from shortcut_xl._threading import _run_on_main
-from shortcut_xl._tracking import DirtyTracker, TrackedApp
+from shortcut_xl._tracking import DirtyTracker
+from shortcut_xl.api import active_write_tracker
 from shortcut_xl.api.format import format_cell_diff
 from shortcut_xl.api.utils.helpers import (
     address_to_index,
@@ -39,6 +40,24 @@ class EditModeError(Exception):
     """Raised when Excel is in cell edit mode at request start."""
 
 
+class _ExcelAppProxy:
+    """Transparent app facade whose module globals participate in the sandbox."""
+
+    __slots__ = ('_app',)
+
+    def __init__(self, app):
+        object.__setattr__(self, '_app', app)
+
+    def __getattr__(self, name):
+        return getattr(object.__getattribute__(self, '_app'), name)
+
+    def __setattr__(self, name, value):
+        setattr(object.__getattribute__(self, '_app'), name, value)
+
+    def __repr__(self):
+        return repr(object.__getattribute__(self, '_app'))
+
+
 def _is_edit_mode_error(e):
     """Check if a COM exception is the Excel cell-edit-mode failure."""
     if hasattr(e, 'hresult') and e.hresult == _EDIT_MODE_SCODE:
@@ -64,8 +83,8 @@ def run_managed(code_str):
     """Compile and execute user code on the main thread with Excel state managed.
 
     Preserves Calculation/Iteration settings, disables Events/Alerts,
-    runs code with a tracking proxy, collects dirty cells, then
-    restores Excel state.
+    runs code with range-scoped tracking for wrapped API writes, collects
+    dirty cells, then restores Excel state.
 
     Returns the list of dirty cells. Caller (_exec_entry) is responsible
     for CF highlighting, JSON response building, and stdout capture.
@@ -99,11 +118,11 @@ def run_managed(code_str):
         try:
             app.EnableEvents = False
             app.DisplayAlerts = False
-            tracker = DirtyTracker(app)
-            tracked = TrackedApp(app, tracker)
+            tracker = DirtyTracker()
+            managed_app = _ExcelAppProxy(app)
             safe_builtins = build_safe_builtins()
-            ns = {**_USER_GLOBALS, 'app': tracked, '__builtins__': safe_builtins}
-            with active_exec_sandbox(safe_builtins):
+            ns = {**_USER_GLOBALS, 'app': managed_app, '__builtins__': safe_builtins}
+            with active_write_tracker(tracker), active_exec_sandbox(safe_builtins):
                 exec(code, ns)
         finally:
             # Collect changes BEFORE restoring calc-related state so we only see

package/xll/modules/shortcut_xl/_tracking.py

@@ -1,310 +1,200 @@
-"""Dirty cell tracking — lazy sheet snapshots.
+"""Range-scoped dirty-cell tracking for wrapped Excel API writes.
 
-Instead of snapshotting the entire workbook, we proxy Worksheet access
-so that a sheet's UsedRange.Value2 is captured on first touch.  After
-execution we re-read only the touched sheets and diff.  Cost is O(touched
-sheets) not O(workbook), and the agent gets raw COM objects for everything
-below the Worksheet level — zero overhead on Range reads/writes.
+Wrapped write operations register their destination COM Range immediately
+before mutation. The tracker snapshots only those ranges and compares them
+after execution. Direct COM writes are intentionally outside this contract.
 """
 
 from typing import Any, TypedDict
 
 from shortcut_xl._log import xl_log
 from shortcut_xl.api.utils.com_utils import normalize_2d
-from shortcut_xl.api.utils.helpers import col_letter
+from shortcut_xl.api.utils.helpers import address_to_index, col_letter
 
 
 class _DirtyCellBase(TypedDict):
-    """Required fields produced by _diff_snapshots for every changed cell."""
+    """Required fields produced for every changed cell."""
 
     sheet: str
-    address: str  # e.g. "B5" — bare cell address, no sheet prefix
+    address: str
     oldValue: Any
     value: Any
 
 
 class DirtyCell(_DirtyCellBase, total=False):
-    """A changed cell as produced by DirtyTracker.collect_changes().
+    formula: str
+    oldFormula: str
+    workbook: str
+    numberFormat: str
 
-    Required: sheet, address, oldValue, value
-    Optional fields are added during the enrichment pass in collect_changes().
-    """
 
-    formula: str  # new formula (if cell has one after the change)
-    oldFormula: str  # previous formula (if cell had one before)
-    workbook: str  # workbook name — added during enrichment
-    numberFormat: str  # Excel number format string — added during enrichment
-
-
-class _SheetSnapshot:
-    """Immutable snapshot of a worksheet's UsedRange values and formulas."""
+class _RangeSnapshot:
+    """Immutable values and formulas for one explicit COM Range."""
 
     __slots__ = ('top_row', 'left_col', 'rows', 'cols', 'data', 'formulas')
 
-    def __init__(self, ws):
-        ur = ws.UsedRange
-        self.top_row = ur.Row
-        self.left_col = ur.Column
-        self.rows = ur.Rows.Count
-        self.cols = ur.Columns.Count
-        self.data = normalize_2d(ur.Value, self.rows, self.cols)
+    def __init__(self, rng):
+        self.top_row = rng.Row
+        self.left_col = rng.Column
+        self.rows = rng.Rows.Count
+        self.cols = rng.Columns.Count
+        self.data = normalize_2d(rng.Value, self.rows, self.cols)
         try:
-            self.formulas = normalize_2d(ur.Formula, self.rows, self.cols)
+            self.formulas = normalize_2d(rng.Formula, self.rows, self.cols)
         except Exception:
             self.formulas = None
 
+    def contains(self, row: int, col: int) -> bool:
+        return self.top_row <= row < self.top_row + self.rows and self.left_col <= col < self.left_col + self.cols
+
+    def value_at(self, row: int, col: int):
+        return self.data[row - self.top_row][col - self.left_col]
+
+    def formula_at(self, row: int, col: int):
+        return _formula_value(self, row - self.top_row, col - self.left_col)
 
-def _get_formula(snap, ri, ci):
-    """Get formula string from snapshot, or None if no formula data."""
+
+def _formula_value(snap, ri, ci):
     if snap.formulas is None:
         return None
     try:
-        f = snap.formulas[ri][ci]
+        formula = snap.formulas[ri][ci]
     except (IndexError, TypeError):
         return None
-    # COM returns the raw value for non-formula cells; only keep actual formulas
-    if isinstance(f, str) and f.startswith('='):
-        return f
+    if isinstance(formula, str) and formula.startswith('='):
+        return formula
     return None
 
 
-def _diff_snapshots(sheet_name: str, before: _SheetSnapshot, after: _SheetSnapshot) -> list[DirtyCell]:
-    """Compare two _SheetSnapshots, return list of change dicts.
-
-    Compares row-by-row first (tuple equality short-circuits) so
-    unchanged rows cost almost nothing.
-    """
+def _diff_snapshots(sheet_name: str, before: _RangeSnapshot, after: _RangeSnapshot) -> list[DirtyCell]:
+    """Compare two snapshots, including formula-only changes."""
     changes = []
-    # Same geometry — fast path
-    if (
+    same_geometry = (
         before.top_row == after.top_row
         and before.left_col == after.left_col
         and before.rows == after.rows
         and before.cols == after.cols
-    ):
-        for ri in range(before.rows):
-            if before.data[ri] == after.data[ri]:
-                continue
-            row_num = before.top_row + ri
-            for ci in range(before.cols):
-                old = before.data[ri][ci]
-                new = after.data[ri][ci]
-                if old != new:
-                    addr = f'{col_letter(before.left_col + ci - 1)}{row_num}'
-                    entry = {
-                        'sheet': sheet_name,
-                        'address': addr,
-                        'oldValue': old,
-                        'value': new,
-                    }
-                    formula = _get_formula(after, ri, ci)
-                    if formula:
-                        entry['formula'] = formula
-                    old_formula = _get_formula(before, ri, ci)
-                    if old_formula:
-                        entry['oldFormula'] = old_formula
-                    changes.append(entry)
-        return changes
-
-    # Different geometry — union bounding box
-    min_r = min(before.top_row, after.top_row)
-    min_c = min(before.left_col, after.left_col)
-    max_r = max(before.top_row + before.rows - 1, after.top_row + after.rows - 1)
-    max_c = max(before.left_col + before.cols - 1, after.left_col + after.cols - 1)
-
-    def _get(snap, row, col):
-        r = row - snap.top_row
-        c = col - snap.left_col
-        if 0 <= r < snap.rows and 0 <= c < snap.cols:
-            return snap.data[r][c]
+    )
+    min_row = min(before.top_row, after.top_row)
+    min_col = min(before.left_col, after.left_col)
+    max_row = max(before.top_row + before.rows - 1, after.top_row + after.rows - 1)
+    max_col = max(before.left_col + before.cols - 1, after.left_col + after.cols - 1)
+
+    def get_value(snap, row, col):
+        if snap.contains(row, col):
+            return snap.value_at(row, col)
         return None
 
-    def _get_formula_abs(snap, row, col):
-        r = row - snap.top_row
-        c = col - snap.left_col
-        if 0 <= r < snap.rows and 0 <= c < snap.cols:
-            return _get_formula(snap, r, c)
+    def get_formula(snap, row, col):
+        if snap.contains(row, col):
+            return snap.formula_at(row, col)
         return None
 
-    for row in range(min_r, max_r + 1):
-        for col in range(min_c, max_c + 1):
-            old = _get(before, row, col)
-            new = _get(after, row, col)
-            if old != new:
-                addr = f'{col_letter(col - 1)}{row}'
-                entry = {
-                    'sheet': sheet_name,
-                    'address': addr,
-                    'oldValue': old,
-                    'value': new,
-                }
-                formula = _get_formula_abs(after, row, col)
-                if formula:
-                    entry['formula'] = formula
-                old_formula = _get_formula_abs(before, row, col)
-                if old_formula:
-                    entry['oldFormula'] = old_formula
-                changes.append(entry)
+    for row in range(min_row, max_row + 1):
+        if same_geometry:
+            row_index = row - before.top_row
+            if before.data[row_index] == after.data[row_index] and all(
+                _formula_value(before, row_index, col_index) == _formula_value(after, row_index, col_index)
+                for col_index in range(before.cols)
+            ):
+                continue
+        for col in range(min_col, max_col + 1):
+            old = get_value(before, row, col)
+            new = get_value(after, row, col)
+            old_formula = get_formula(before, row, col)
+            formula = get_formula(after, row, col)
+            if old == new and old_formula == formula:
+                continue
+            entry: DirtyCell = {
+                'sheet': sheet_name,
+                'address': f'{col_letter(col - 1)}{row}',
+                'oldValue': old,
+                'value': new,
+            }
+            if formula:
+                entry['formula'] = formula
+            if old_formula:
+                entry['oldFormula'] = old_formula
+            changes.append(entry)
     return changes
 
 
+class _TrackedRange:
+    __slots__ = ('rng', 'workbook', 'sheet', 'before')
+
+    def __init__(self, rng, workbook: str, sheet: str, before: _RangeSnapshot):
+        self.rng = rng
+        self.workbook = workbook
+        self.sheet = sheet
+        self.before = before
+
+
 class DirtyTracker:
-    """Snapshots sheets on first access, diffs after execution."""
+    """Snapshots only ranges registered by wrapped write operations."""
 
-    __slots__ = ('_app', '_snapshots')
+    __slots__ = ('_ranges', '_keys', '_originals')
 
-    def __init__(self, app):
-        self._app = app
-        self._snapshots = {}  # name -> (ws, _SheetSnapshot)
+    def __init__(self):
+        self._ranges: list[_TrackedRange] = []
+        self._keys: set[tuple[str, str, int, int, int, int]] = set()
+        self._originals: dict[tuple[str, str, int, int], tuple[Any, str | None]] = {}
 
-    def snapshot_sheet(self, ws):
-        """Capture a sheet's data on first access.  No-op on subsequent calls."""
+    def track_range(self, rng) -> None:
+        """Capture a destination range once, before its first exact-range write."""
         try:
-            name = ws.Name
-        except Exception:
-            return
-        if name not in self._snapshots:
-            try:
-                self._snapshots[name] = (ws, _SheetSnapshot(ws))
-            except Exception as e:
-                xl_log(f'DirtyTracker.snapshot_sheet({name}): {e}')
+            worksheet = rng.Parent
+            sheet = worksheet.Name
+            workbook = worksheet.Parent.Name
+            key = (workbook, sheet, rng.Row, rng.Column, rng.Rows.Count, rng.Columns.Count)
+            if key in self._keys:
+                return
+            before = _RangeSnapshot(rng)
+            self._keys.add(key)
+            self._ranges.append(_TrackedRange(rng, workbook, sheet, before))
+            for row in range(before.top_row, before.top_row + before.rows):
+                for col in range(before.left_col, before.left_col + before.cols):
+                    cell_key = (workbook, sheet, row, col)
+                    self._originals.setdefault(cell_key, (before.value_at(row, col), before.formula_at(row, col)))
+        except Exception as error:
+            xl_log(f'DirtyTracker.track_range failed: {error}')
 
     def collect_changes(self) -> list[DirtyCell]:
-        """Re-read snapshotted sheets and return list of cell changes."""
-        all_changes = []
-        for name, (ws, before) in self._snapshots.items():
+        """Re-read registered ranges and return deduplicated final cell changes."""
+        candidates: dict[tuple[str, str, str], DirtyCell] = {}
+        uniform_formats: dict[tuple[str, str, str], str] = {}
+
+        for tracked in self._ranges:
             try:
-                after = _SheetSnapshot(ws)
-                changes = _diff_snapshots(name, before, after)
-                # Enrich with workbook name + numberFormat
+                after = _RangeSnapshot(tracked.rng)
+                changes = _diff_snapshots(tracked.sheet, tracked.before, after)
                 try:
-                    wb_name = ws.Parent.Name
+                    number_format = tracked.rng.NumberFormat if changes else None
                 except Exception:
-                    wb_name = None
+                    number_format = None
                 for entry in changes:
-                    if wb_name:
-                        entry['workbook'] = wb_name
-                    try:
-                        fmt = ws.Range(entry['address']).NumberFormat
-                        if fmt and fmt != 'General':
-                            entry['numberFormat'] = str(fmt)
-                    except Exception:
-                        pass
-                all_changes.extend(changes)
-            except Exception as e:
-                xl_log(f'DirtyTracker.collect_changes({name}): {e}')
-        return all_changes
-
-
-# ---------------------------------------------------------------------------
-# Thin proxy classes (Application → Workbook → Worksheet access only)
-# ---------------------------------------------------------------------------
-
-
-class TrackedApp:
-    """Proxy around Application.  Wraps workbook/sheet access to trigger
-    snapshots; everything else passes straight through to COM."""
-
-    _WB_ATTRS = frozenset(('ActiveWorkbook', 'ThisWorkbook'))
-    _SHEET_ACCESSORS = frozenset(('Worksheets', 'Sheets'))
-    _SHEET_DIRECT = frozenset(('ActiveSheet',))
-    __slots__ = ('_app', '_tracker')
-
-    def __init__(self, app, tracker):
-        object.__setattr__(self, '_app', app)
-        object.__setattr__(self, '_tracker', tracker)
-
-    def __getattr__(self, name):
-        val = getattr(object.__getattribute__(self, '_app'), name)
-        tracker = object.__getattribute__(self, '_tracker')
-        if name in TrackedApp._WB_ATTRS:
-            return _TrackedWorkbook(val, tracker)
-        if name == 'Workbooks':
-            return _TrackedWorkbooks(val, tracker)
-        if name in TrackedApp._SHEET_ACCESSORS:
-            return _TrackedSheetAccessor(val, tracker)
-        if name in TrackedApp._SHEET_DIRECT:
-            tracker.snapshot_sheet(val)
-            return val
-        return val
-
-    def __setattr__(self, name, value):
-        setattr(object.__getattribute__(self, '_app'), name, value)
-
-    def __repr__(self):
-        return repr(object.__getattribute__(self, '_app'))
-
-
-class _TrackedWorkbooks:
-    """Proxy for Workbooks collection."""
-
-    __slots__ = ('_obj', '_tracker')
-
-    def __init__(self, obj, tracker):
-        object.__setattr__(self, '_obj', obj)
-        object.__setattr__(self, '_tracker', tracker)
-
-    def __call__(self, *args, **kwargs):
-        wb = object.__getattribute__(self, '_obj')(*args, **kwargs)
-        return _TrackedWorkbook(wb, object.__getattribute__(self, '_tracker'))
-
-    def __getattr__(self, name):
-        return getattr(object.__getattribute__(self, '_obj'), name)
-
-    def __iter__(self):
-        tracker = object.__getattribute__(self, '_tracker')
-        for wb in object.__getattribute__(self, '_obj'):
-            yield _TrackedWorkbook(wb, tracker)
-
-
-class _TrackedWorkbook:
-    """Proxy for a Workbook — wraps Worksheet/Sheet access."""
-
-    _SHEET_ACCESSORS = frozenset(('Worksheets', 'Sheets'))
-    _SHEET_DIRECT = frozenset(('ActiveSheet',))
-    __slots__ = ('_wb', '_tracker')
-
-    def __init__(self, wb, tracker):
-        object.__setattr__(self, '_wb', wb)
-        object.__setattr__(self, '_tracker', tracker)
-
-    def __getattr__(self, name):
-        val = getattr(object.__getattribute__(self, '_wb'), name)
-        tracker = object.__getattribute__(self, '_tracker')
-        if name in _TrackedWorkbook._SHEET_ACCESSORS:
-            return _TrackedSheetAccessor(val, tracker)
-        if name in _TrackedWorkbook._SHEET_DIRECT:
-            tracker.snapshot_sheet(val)
-            return val
-        return val
-
-    def __setattr__(self, name, value):
-        setattr(object.__getattribute__(self, '_wb'), name, value)
-
-    def __repr__(self):
-        return repr(object.__getattribute__(self, '_wb'))
-
-
-class _TrackedSheetAccessor:
-    """Proxy for Worksheets/Sheets collection — snapshots each sheet
-    the first time it is accessed, then returns the real COM Worksheet."""
-
-    __slots__ = ('_obj', '_tracker')
-
-    def __init__(self, obj, tracker):
-        object.__setattr__(self, '_obj', obj)
-        object.__setattr__(self, '_tracker', tracker)
-
-    def __call__(self, *args, **kwargs):
-        ws = object.__getattribute__(self, '_obj')(*args, **kwargs)
-        object.__getattribute__(self, '_tracker').snapshot_sheet(ws)
-        return ws  # real COM object — no more proxying
-
-    def __getattr__(self, name):
-        return getattr(object.__getattribute__(self, '_obj'), name)
+                    key = (tracked.workbook, tracked.sheet, entry['address'])
+                    entry['workbook'] = tracked.workbook
+                    candidates[key] = entry
+                    if isinstance(number_format, str) and number_format != 'General':
+                        uniform_formats[key] = number_format
+            except Exception as error:
+                xl_log(f'DirtyTracker.collect_changes({tracked.workbook}:{tracked.sheet}): {error}')
+
+        result = []
+        for (workbook, sheet, address), candidate in candidates.items():
+            row_index, col_index = address_to_index(address)
+            old_value, old_formula = self._originals[(workbook, sheet, row_index + 1, col_index + 1)]
+            new_formula = candidate.get('formula')
+            if old_value == candidate['value'] and old_formula == new_formula:
+                continue
 
-    def __iter__(self):
-        tracker = object.__getattribute__(self, '_tracker')
-        for ws in object.__getattribute__(self, '_obj'):
-            tracker.snapshot_sheet(ws)
-            yield ws
+            candidate['oldValue'] = old_value
+            if old_formula:
+                candidate['oldFormula'] = old_formula
+            else:
+                candidate.pop('oldFormula', None)
+            number_format = uniform_formats.get((workbook, sheet, address))
+            if number_format:
+                candidate['numberFormat'] = number_format
+            result.append(candidate)
+        return result