shortcutxl 0.2.12 → 0.2.13

package/xll/modules/pong.py

@@ -1,188 +1,188 @@
-"""
-Pong in Excel — type =pong_start() to play!
-
-Two AI paddles rally a ball across a 30x20 cell grid.
-Type =pong_stop() to end the game.
-"""
-import shortcut_xl
-from shortcut_xl import xl_func
-import random
-
-WIDTH  = 30
-HEIGHT = 20
-PADDLE_H = 4
-FPS = 30
-
-# Grid occupies A3:AD22 (20 rows x 30 cols)
-_GRID_RANGE = "A3:AD22"
-
-_state = {
-    'ball_x': 15.0, 'ball_y': 10.0,
-    'ball_dx': 1.0,  'ball_dy': 0.7,
-    'paddle_l': 8,   'paddle_r': 8,
-    'score_l': 0,    'score_r': 0,
-    'running': False,
-}
-
-
-def _reset_ball():
-    _state['ball_x'] = WIDTH / 2.0
-    _state['ball_y'] = HEIGHT / 2.0
-    _state['ball_dx'] = random.choice([-1.0, 1.0])
-    _state['ball_dy'] = random.uniform(-1.0, 1.0)
-
-
-def _render():
-    # Build the grid
-    grid = []
-    for r in range(HEIGHT):
-        row = []
-        for c in range(WIDTH):
-            ch = ""
-            # Left paddle
-            if c == 0 and _state['paddle_l'] <= r < _state['paddle_l'] + PADDLE_H:
-                ch = chr(9608)  # full block
-            # Right paddle
-            elif c == WIDTH - 1 and _state['paddle_r'] <= r < _state['paddle_r'] + PADDLE_H:
-                ch = chr(9608)
-            # Ball
-            elif int(round(_state['ball_y'])) == r and int(round(_state['ball_x'])) == c:
-                ch = chr(9679)  # black circle
-            # Center line
-            elif c == WIDTH // 2 and r % 2 == 0:
-                ch = chr(9474)  # light vertical
-            row.append(ch)
-        grid.append(row)
-
-    # Write entire frame in one batch — one repaint, one retry point
-    score = f"PONG   {_state['score_l']}  :  {_state['score_r']}"
-
-    def _paint(app):
-        # Suppress auto-recalculation — without this every 600-cell write
-        # triggers a full recalc cycle that fights our rendering and causes
-        # the visible "flashing" effect.
-        app.Calculation = -4135  # xlCalculationManual
-
-        sheet = app.ActiveSheet
-
-        # One-time setup: make cells square-ish and use a monospace font
-        # so the Unicode glyphs (█ ● │) are actually visible.
-        if not _state.get('_formatted'):
-            _state['_formatted'] = True
-            area = sheet.Range(_GRID_RANGE)
-            area.ColumnWidth = 2.14
-            area.Font.Name = "Consolas"
-            area.Font.Size = 11
-            area.HorizontalAlignment = -4108  # xlCenter
-
-        # Grid (20x30) — use direct range address, NOT Resize()
-        # win32com Resize() is broken: returns only the bottom-right cell
-        grid_com = tuple(tuple(row) for row in grid)
-        sheet.Range(_GRID_RANGE).Value = grid_com
-        # Scoreboard + instructions
-        sheet.Range("A1").Value = score
-        sheet.Range("A2").Value = "pong_start() to play   pong_stop() to end"
-
-    shortcut_xl.xl_batch(_paint)
-
-
-def _tick():
-    shortcut_xl.xl_log(f"_tick: running={_state['running']}")
-    if not _state['running']:
-        return
-
-    try:
-        _tick_inner()
-        shortcut_xl.xl_log("_tick: frame OK")
-    except Exception as e:
-        shortcut_xl.xl_log(f"pong tick error: {e}")
-        import traceback
-        shortcut_xl.xl_log(traceback.format_exc())
-        _state['running'] = False
-        shortcut_xl.schedule_call(_restore_calc, 0.3)
-        return
-
-
-def _tick_inner():
-    s = _state
-
-    # Move ball
-    s['ball_x'] += s['ball_dx']
-    s['ball_y'] += s['ball_dy']
-
-    # Bounce top/bottom
-    if s['ball_y'] <= 0:
-        s['ball_y'] = 0
-        s['ball_dy'] = abs(s['ball_dy'])
-    elif s['ball_y'] >= HEIGHT - 1:
-        s['ball_y'] = HEIGHT - 1
-        s['ball_dy'] = -abs(s['ball_dy'])
-
-    # Left paddle check
-    if s['ball_x'] <= 1:
-        if s['paddle_l'] - 0.5 <= s['ball_y'] < s['paddle_l'] + PADDLE_H + 0.5:
-            s['ball_dx'] = abs(s['ball_dx'])
-            s['ball_x'] = 1
-            # Add spin based on where ball hit paddle
-            hit_pos = (s['ball_y'] - s['paddle_l']) / PADDLE_H
-            s['ball_dy'] = (hit_pos - 0.5) * 2.0
-        else:
-            s['score_r'] += 1
-            _reset_ball()
-
-    # Right paddle check
-    if s['ball_x'] >= WIDTH - 2:
-        if s['paddle_r'] - 0.5 <= s['ball_y'] < s['paddle_r'] + PADDLE_H + 0.5:
-            s['ball_dx'] = -abs(s['ball_dx'])
-            s['ball_x'] = WIDTH - 2
-            hit_pos = (s['ball_y'] - s['paddle_r']) / PADDLE_H
-            s['ball_dy'] = (hit_pos - 0.5) * 2.0
-        else:
-            s['score_l'] += 1
-            _reset_ball()
-
-    # AI: move paddles toward ball with slight delay
-    ball_y = s['ball_y']
-    for paddle in ('paddle_l', 'paddle_r'):
-        target = int(ball_y) - PADDLE_H // 2
-        diff = target - s[paddle]
-        # Add some imperfection
-        speed = 1 if abs(diff) < 3 else 2
-        if diff > 0:
-            s[paddle] = min(s[paddle] + speed, HEIGHT - PADDLE_H)
-        elif diff < 0:
-            s[paddle] = max(s[paddle] - speed, 0)
-
-    # Speed up slightly over time
-    if abs(s['ball_dx']) < 2.5:
-        s['ball_dx'] *= 1.005
-
-    _render()
-    shortcut_xl.schedule_call(_tick, 1.0 / FPS)
-
-
-def _restore_calc():
-    """Restore automatic calculation after the game ends."""
-    def _do(app):
-        app.Calculation = -4105  # xlCalculationAutomatic
-    shortcut_xl.xl_batch(_do)
-
-
-@xl_func
-def pong_start():
-    if _state['running']:
-        return "Already running!"
-    _state['running'] = True
-    _state['score_l'] = 0
-    _state['score_r'] = 0
-    _state['_formatted'] = False
-    _reset_ball()
-    shortcut_xl.schedule_call(_tick, 0.1)
-    return "PONG!"
-
-
-@xl_func
-def pong_stop():
-    _state['running'] = False
-    shortcut_xl.schedule_call(_restore_calc, 0.3)
-    return "Stopped"
+"""
+Pong in Excel — type =pong_start() to play!
+
+Two AI paddles rally a ball across a 30x20 cell grid.
+Type =pong_stop() to end the game.
+"""
+import shortcut_xl
+from shortcut_xl import xl_func
+import random
+
+WIDTH  = 30
+HEIGHT = 20
+PADDLE_H = 4
+FPS = 30
+
+# Grid occupies A3:AD22 (20 rows x 30 cols)
+_GRID_RANGE = "A3:AD22"
+
+_state = {
+    'ball_x': 15.0, 'ball_y': 10.0,
+    'ball_dx': 1.0,  'ball_dy': 0.7,
+    'paddle_l': 8,   'paddle_r': 8,
+    'score_l': 0,    'score_r': 0,
+    'running': False,
+}
+
+
+def _reset_ball():
+    _state['ball_x'] = WIDTH / 2.0
+    _state['ball_y'] = HEIGHT / 2.0
+    _state['ball_dx'] = random.choice([-1.0, 1.0])
+    _state['ball_dy'] = random.uniform(-1.0, 1.0)
+
+
+def _render():
+    # Build the grid
+    grid = []
+    for r in range(HEIGHT):
+        row = []
+        for c in range(WIDTH):
+            ch = ""
+            # Left paddle
+            if c == 0 and _state['paddle_l'] <= r < _state['paddle_l'] + PADDLE_H:
+                ch = chr(9608)  # full block
+            # Right paddle
+            elif c == WIDTH - 1 and _state['paddle_r'] <= r < _state['paddle_r'] + PADDLE_H:
+                ch = chr(9608)
+            # Ball
+            elif int(round(_state['ball_y'])) == r and int(round(_state['ball_x'])) == c:
+                ch = chr(9679)  # black circle
+            # Center line
+            elif c == WIDTH // 2 and r % 2 == 0:
+                ch = chr(9474)  # light vertical
+            row.append(ch)
+        grid.append(row)
+
+    # Write entire frame in one batch — one repaint, one retry point
+    score = f"PONG   {_state['score_l']}  :  {_state['score_r']}"
+
+    def _paint(app):
+        # Suppress auto-recalculation — without this every 600-cell write
+        # triggers a full recalc cycle that fights our rendering and causes
+        # the visible "flashing" effect.
+        app.Calculation = -4135  # xlCalculationManual
+
+        sheet = app.ActiveSheet
+
+        # One-time setup: make cells square-ish and use a monospace font
+        # so the Unicode glyphs (█ ● │) are actually visible.
+        if not _state.get('_formatted'):
+            _state['_formatted'] = True
+            area = sheet.Range(_GRID_RANGE)
+            area.ColumnWidth = 2.14
+            area.Font.Name = "Consolas"
+            area.Font.Size = 11
+            area.HorizontalAlignment = -4108  # xlCenter
+
+        # Grid (20x30) — use direct range address, NOT Resize()
+        # win32com Resize() is broken: returns only the bottom-right cell
+        grid_com = tuple(tuple(row) for row in grid)
+        sheet.Range(_GRID_RANGE).Value = grid_com
+        # Scoreboard + instructions
+        sheet.Range("A1").Value = score
+        sheet.Range("A2").Value = "pong_start() to play   pong_stop() to end"
+
+    shortcut_xl.xl_batch(_paint)
+
+
+def _tick():
+    shortcut_xl.xl_log(f"_tick: running={_state['running']}")
+    if not _state['running']:
+        return
+
+    try:
+        _tick_inner()
+        shortcut_xl.xl_log("_tick: frame OK")
+    except Exception as e:
+        shortcut_xl.xl_log(f"pong tick error: {e}")
+        import traceback
+        shortcut_xl.xl_log(traceback.format_exc())
+        _state['running'] = False
+        shortcut_xl.schedule_call(_restore_calc, 0.3)
+        return
+
+
+def _tick_inner():
+    s = _state
+
+    # Move ball
+    s['ball_x'] += s['ball_dx']
+    s['ball_y'] += s['ball_dy']
+
+    # Bounce top/bottom
+    if s['ball_y'] <= 0:
+        s['ball_y'] = 0
+        s['ball_dy'] = abs(s['ball_dy'])
+    elif s['ball_y'] >= HEIGHT - 1:
+        s['ball_y'] = HEIGHT - 1
+        s['ball_dy'] = -abs(s['ball_dy'])
+
+    # Left paddle check
+    if s['ball_x'] <= 1:
+        if s['paddle_l'] - 0.5 <= s['ball_y'] < s['paddle_l'] + PADDLE_H + 0.5:
+            s['ball_dx'] = abs(s['ball_dx'])
+            s['ball_x'] = 1
+            # Add spin based on where ball hit paddle
+            hit_pos = (s['ball_y'] - s['paddle_l']) / PADDLE_H
+            s['ball_dy'] = (hit_pos - 0.5) * 2.0
+        else:
+            s['score_r'] += 1
+            _reset_ball()
+
+    # Right paddle check
+    if s['ball_x'] >= WIDTH - 2:
+        if s['paddle_r'] - 0.5 <= s['ball_y'] < s['paddle_r'] + PADDLE_H + 0.5:
+            s['ball_dx'] = -abs(s['ball_dx'])
+            s['ball_x'] = WIDTH - 2
+            hit_pos = (s['ball_y'] - s['paddle_r']) / PADDLE_H
+            s['ball_dy'] = (hit_pos - 0.5) * 2.0
+        else:
+            s['score_l'] += 1
+            _reset_ball()
+
+    # AI: move paddles toward ball with slight delay
+    ball_y = s['ball_y']
+    for paddle in ('paddle_l', 'paddle_r'):
+        target = int(ball_y) - PADDLE_H // 2
+        diff = target - s[paddle]
+        # Add some imperfection
+        speed = 1 if abs(diff) < 3 else 2
+        if diff > 0:
+            s[paddle] = min(s[paddle] + speed, HEIGHT - PADDLE_H)
+        elif diff < 0:
+            s[paddle] = max(s[paddle] - speed, 0)
+
+    # Speed up slightly over time
+    if abs(s['ball_dx']) < 2.5:
+        s['ball_dx'] *= 1.005
+
+    _render()
+    shortcut_xl.schedule_call(_tick, 1.0 / FPS)
+
+
+def _restore_calc():
+    """Restore automatic calculation after the game ends."""
+    def _do(app):
+        app.Calculation = -4105  # xlCalculationAutomatic
+    shortcut_xl.xl_batch(_do)
+
+
+@xl_func
+def pong_start():
+    if _state['running']:
+        return "Already running!"
+    _state['running'] = True
+    _state['score_l'] = 0
+    _state['score_r'] = 0
+    _state['_formatted'] = False
+    _reset_ball()
+    shortcut_xl.schedule_call(_tick, 0.1)
+    return "PONG!"
+
+
+@xl_func
+def pong_stop():
+    _state['running'] = False
+    shortcut_xl.schedule_call(_restore_calc, 0.3)
+    return "Stopped"

package/xll/modules/shortcut_xl/_diff_highlight.py

@@ -0,0 +1,176 @@
+"""Diff highlighting — CF overlay + MessageBox approval for cell changes.
+
+After user code executes and dirty cells are collected, this module:
+1. Applies Conditional Formatting to highlight changed cells (yellow)
+2. Shows a Win32 MessageBox asking the user to keep or reject changes
+3. If rejected, reverts cells using oldValue/oldFormula from the diff
+4. Always cleans up CF rules before returning
+
+Performance: CF rules are applied via batched Union ranges (not per-cell),
+so highlighting cost is O(n / batch_size) COM calls, not O(n).
+Revert writes are per-cell but in-process COM (~microseconds each).
+"""
+
+import ctypes
+from shortcut_xl._log import xl_log
+
+# Win32 MessageBox constants
+_MB_YESNO = 0x04
+_MB_ICONQUESTION = 0x20
+_IDYES = 6
+
+# Excel constants
+_XL_EXPRESSION = 2          # xlExpression CF type
+_XL_CALC_MANUAL = -4135     # xlCalculationManual
+_HIGHLIGHT_COLOR = 0x00FFFF  # yellow (BGR for #FFFF00) — Track Changes color
+
+# Max length for comma-separated address string (Excel limit)
+_ADDR_BATCH_LIMIT = 255
+
+
+def _group_by_sheet(dirty_cells):
+    by_sheet = {}
+    for cell in dirty_cells:
+        by_sheet.setdefault(cell['sheet'], []).append(cell)
+    return by_sheet
+
+
+def _build_union(app, ws, addresses):
+    """Build a multi-area Range from address list, batching to stay under limits."""
+    if not addresses:
+        return None
+    batches = []
+    current = ""
+    for addr in addresses:
+        candidate = f"{current},{addr}" if current else addr
+        if len(candidate) > _ADDR_BATCH_LIMIT and current:
+            batches.append(current)
+            current = addr
+        else:
+            current = candidate
+    if current:
+        batches.append(current)
+
+    rng = ws.Range(batches[0])
+    for b in batches[1:]:
+        rng = app.Union(rng, ws.Range(b))
+    return rng
+
+
+def _apply_cf_highlights(app, by_sheet):
+    """Apply CF rules to highlight changed cells. Returns cleanup state."""
+    cf_state = []  # (ws, count_before) for cleanup
+    for sheet_name, cells in by_sheet.items():
+        try:
+            ws = app.Worksheets(sheet_name)
+            count_before = ws.Cells.FormatConditions.Count
+            rng = _build_union(app, ws, [c['address'] for c in cells])
+            if rng is None:
+                continue
+            rng.FormatConditions.Add(Type=_XL_EXPRESSION, Formula1="=TRUE")
+            rule = rng.FormatConditions(rng.FormatConditions.Count)
+            rule.Interior.Color = _HIGHLIGHT_COLOR
+            cf_state.append((ws, count_before))
+        except Exception as e:
+            xl_log(f"_apply_cf_highlights({sheet_name}): {e}")
+    return cf_state
+
+
+def _cleanup_cf(cf_state):
+    """Remove CF rules added during highlighting."""
+    for ws, count_before in cf_state:
+        try:
+            while ws.Cells.FormatConditions.Count > count_before:
+                ws.Cells.FormatConditions(
+                    ws.Cells.FormatConditions.Count).Delete()
+        except Exception as e:
+            xl_log(f"_cleanup_cf: {e}")
+
+
+def _revert_cells(app, dirty_cells):
+    """Restore old values/formulas for rejected changes.
+
+    Sets calc to manual during revert to avoid expensive recalcs
+    on each write, then restores original calc mode.
+    """
+    orig_calc = None
+    try:
+        orig_calc = app.Calculation
+        app.Calculation = _XL_CALC_MANUAL
+    except Exception:
+        pass
+
+    for sheet_name, cells in _group_by_sheet(dirty_cells).items():
+        try:
+            ws = app.Worksheets(sheet_name)
+            for cell in cells:
+                addr = cell['address']
+                try:
+                    if cell.get('oldFormula'):
+                        ws.Range(addr).Formula = cell['oldFormula']
+                    else:
+                        ws.Range(addr).Value = cell['oldValue']
+                except Exception as e:
+                    xl_log(f"_revert_cells({sheet_name}!{addr}): {e}")
+        except Exception as e:
+            xl_log(f"_revert_cells({sheet_name}): {e}")
+
+    if orig_calc is not None:
+        try:
+            app.Calculation = orig_calc
+        except Exception:
+            pass
+
+
+def highlight_and_approve(app, dirty_cells):
+    """Highlight changed cells with CF, show MessageBox for user approval.
+
+    Returns True if approved, False if rejected.
+    On rejection, all changes are reverted from dirty_cells' oldValue/oldFormula.
+    CF highlighting is always cleaned up before returning.
+    """
+    if not dirty_cells:
+        return True
+
+    by_sheet = _group_by_sheet(dirty_cells)
+    cf_state = []
+
+    try:
+        # Phase 1: Apply CF highlights
+        try:
+            app.ScreenUpdating = False
+        except Exception:
+            pass
+        cf_state = _apply_cf_highlights(app, by_sheet)
+        try:
+            app.ScreenUpdating = True
+        except Exception:
+            pass
+
+        # Phase 2: MessageBox — modal to Excel window
+        n = len(dirty_cells)
+        sheet_summary = ", ".join(
+            f"{name} ({len(cells)})" for name, cells in by_sheet.items()
+        )
+        msg = (
+            f"ShortcutXL modified {n} cell{'s' if n != 1 else ''} "
+            f"in: {sheet_summary}\n\n"
+            "Keep these changes?"
+        )
+        try:
+            hwnd = app.Hwnd
+        except Exception:
+            hwnd = 0
+        result = ctypes.windll.user32.MessageBoxW(
+            hwnd, msg, "ShortcutXL", _MB_YESNO | _MB_ICONQUESTION
+        )
+        approved = (result == _IDYES)
+
+        # Phase 3: Revert if rejected
+        if not approved:
+            _revert_cells(app, dirty_cells)
+
+        return approved
+
+    finally:
+        _cleanup_cf(cf_state)

package/xll/modules/shortcut_xl/_log.py

@@ -1,12 +1,12 @@
-"""Logging utility for ShortcutXL."""
-
-import os
-import datetime
-
-
-def xl_log(msg):
-    """Append a timestamped message to %TEMP%\\shortcutxl.log."""
-    log_path = os.path.join(os.environ.get("TEMP", "."), "shortcutxl.log")
-    timestamp = datetime.datetime.now().strftime("%Y-%m-%d %H:%M:%S.%f")[:-3]
-    with open(log_path, "a", encoding="utf-8") as f:
-        f.write(f"[{timestamp}] {msg}\n")
+"""Logging utility for ShortcutXL."""
+
+import os
+import datetime
+
+
+def xl_log(msg):
+    """Append a timestamped message to %TEMP%\\shortcutxl.log."""
+    log_path = os.path.join(os.environ.get("TEMP", "."), "shortcutxl.log")
+    timestamp = datetime.datetime.now().strftime("%Y-%m-%d %H:%M:%S.%f")[:-3]
+    with open(log_path, "a", encoding="utf-8") as f:
+        f.write(f"[{timestamp}] {msg}\n")

package/xll/modules/shortcut_xl/_registry.py

@@ -1,44 +1,44 @@
-"""@xl_func decorator — marks functions for registration as Excel UDFs.
-
-The C runtime scans _registry at xlAutoOpen time to register functions with Excel.
-"""
-
-import inspect
-
-# Internal registry: list of (name, callable, n_args)
-_registry = []
-
-
-def xl_func(fn=None, *, name=None):
-    """Decorator — mark a function as an Excel UDF.
-
-    Usage:
-        @xl_func
-        def my_func(a, b):
-            return a + b
-
-        @xl_func(name="myCustomName")
-        def my_func(a, b):
-            return a + b
-    """
-    def _register(f):
-        excel_name = name if name else f.__name__
-        sig = inspect.signature(f)
-        n_args = len([
-            p for p in sig.parameters.values()
-            if p.kind in (
-                inspect.Parameter.POSITIONAL_OR_KEYWORD,
-                inspect.Parameter.POSITIONAL_ONLY,
-            )
-        ])
-        # Check if already registered (e.g. after a hot-reload)
-        for i, (n, _, _) in enumerate(_registry):
-            if n == excel_name:
-                _registry[i] = (excel_name, f, n_args)
-                return f
-        _registry.append((excel_name, f, n_args))
-        return f
-
-    if fn is not None:
-        return _register(fn)
-    return _register
+"""@xl_func decorator — marks functions for registration as Excel UDFs.
+
+The C runtime scans _registry at xlAutoOpen time to register functions with Excel.
+"""
+
+import inspect
+
+# Internal registry: list of (name, callable, n_args)
+_registry = []
+
+
+def xl_func(fn=None, *, name=None):
+    """Decorator — mark a function as an Excel UDF.
+
+    Usage:
+        @xl_func
+        def my_func(a, b):
+            return a + b
+
+        @xl_func(name="myCustomName")
+        def my_func(a, b):
+            return a + b
+    """
+    def _register(f):
+        excel_name = name if name else f.__name__
+        sig = inspect.signature(f)
+        n_args = len([
+            p for p in sig.parameters.values()
+            if p.kind in (
+                inspect.Parameter.POSITIONAL_OR_KEYWORD,
+                inspect.Parameter.POSITIONAL_ONLY,
+            )
+        ])
+        # Check if already registered (e.g. after a hot-reload)
+        for i, (n, _, _) in enumerate(_registry):
+            if n == excel_name:
+                _registry[i] = (excel_name, f, n_args)
+                return f
+        _registry.append((excel_name, f, n_args))
+        return f
+
+    if fn is not None:
+        return _register(fn)
+    return _register