shortcutxl 0.2.0

package/xll/modules/pong.py

@@ -0,0 +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"

package/xll/modules/shortcut_xl/__init__.py

@@ -0,0 +1,18 @@
+"""ShortcutXL — Python helpers for the Excel XLL add-in.
+
+Public API
+----------
+@xl_func          — decorator to register a function as an Excel UDF
+xl_app()          — return the Excel Application COM object
+run_managed(fn)   — run fn(app) on main thread with tracking + state management
+xl_batch(fn)      — run fn(app) on the main thread with ScreenUpdating off
+schedule_call(fn) — schedule fn() on a background thread
+xl_log(msg)       — append to %TEMP%\\shortcutxl.log
+format_cell_diff  — format dirty cells into a human-readable summary
+"""
+
+from ._log import xl_log
+from ._registry import xl_func, _registry
+from ._com import xl_app
+from ._managed import run_managed, xl_batch, schedule_call
+from ._format import format_cell_diff

package/xll/modules/shortcut_xl/_categorize.py

@@ -0,0 +1,200 @@
+"""Cell issue categorization — port of cell-categorizer.ts.
+
+Detects hardcoded numbers, formula errors, large percentages,
+and hardcoded numbers inside formulas.
+"""
+
+import re
+
+# Issue types — also used as dict keys in categorize_cells() result
+GOOD = 'good'
+HARDCODED_NUMBER = 'hardcodes'
+HARDCODED_NUMBER_IN_FORMULA = 'hardcodes in formulas'
+LARGE_PERCENTAGE = 'large %'
+INVALID_FORMULA = 'formula errs'
+ALL_PROBLEMS = 'all problems'
+
+# Number format characters that indicate date/time (skip these as hardcoded)
+_DATE_TIME_CHARS = ('d', 'm', 'y', 'h', 's')
+
+# Number format characters/strings that indicate currency/accounting (skip these)
+# Must stay in sync with _format.py currency regex.
+_CURRENCY_CHARS = ('$', '£', '€', '¥', '₹', '₩', '₪', '₱', '฿', 'kr')
+
+
+def _is_numeric(value):
+    """Check if a value is numeric (int, float, Decimal, etc.)."""
+    if isinstance(value, bool):
+        return False
+    if isinstance(value, (int, float)):
+        return True
+    # COM may return Decimal or other numeric types
+    try:
+        float(value)
+        return True
+    except (TypeError, ValueError):
+        return False
+
+
+def _to_float(value):
+    """Coerce a numeric value to float."""
+    if isinstance(value, (int, float)):
+        return value
+    return float(value)
+
+
+def is_hardcoded_number(cell):
+    """Check if a cell contains a hardcoded number (no formula, numeric value,
+    not a date/time/currency format, not a COM error code)."""
+    if cell.get('formula'):
+        return False
+    value = cell.get('value')
+    if not _is_numeric(value):
+        return False
+    if is_com_error(value):
+        return False
+    fmt = (cell.get('numberFormat') or '').lower()
+    # Skip dates/times
+    if any(ch in fmt for ch in _DATE_TIME_CHARS):
+        return False
+    # Skip currency/accounting
+    if any(ch in fmt for ch in _CURRENCY_CHARS):
+        return False
+    return True
+
+
+# Matches standalone numbers in formulas, excluding cell refs / named ranges.
+_HARDCODED_NUM_RE = re.compile(
+    r'(?<![A-Z$!])(?<![A-Z]\d)\b\d+\.?\d*\b(?![A-Z])', re.IGNORECASE)
+
+
+def has_hardcoded_numbers_in_formula(formula):
+    """Check if a formula contains hardcoded numbers."""
+    # Remove string literals to avoid false positives
+    cleaned = re.sub(r'"[^"]*"', '', formula)
+    return bool(_HARDCODED_NUM_RE.search(cleaned))
+
+
+_ERROR_PATTERNS = (
+    '#ERROR', '#REF', '#VALUE', '#DIV/0', '#NUM', '#N/A', '#NAME', '#NULL')
+
+# COM returns Excel error values as negative integers (CVErr codes).
+# Map them to their string equivalents so categorization works.
+_COM_ERROR_CODES = {
+    -2146826281: '#DIV/0!',
+    -2146826246: '#N/A',
+    -2146826259: '#NAME?',
+    -2146826265: '#REF!',
+    -2146826273: '#VALUE!',
+    -2146826252: '#NUM!',
+    -2146826288: '#NULL!',
+    -2146826245: '#GETTING_DATA',
+}
+
+
+def _is_error_value(s):
+    """Check if a string is an Excel error value (e.g. '#REF!', '#N/A').
+
+    Excel error values always start with '#' and may have a trailing '!'
+    or '?'.  We check that the string starts with a known error prefix
+    and contains no spaces (real errors never do)."""
+    if not s or ' ' in s:
+        return False
+    return any(s.startswith(e) for e in _ERROR_PATTERNS)
+
+
+def is_com_error(value):
+    """Check if a value is a COM error code (negative integer)."""
+    return isinstance(value, int) and value in _COM_ERROR_CODES
+
+
+def com_error_to_str(value):
+    """Convert a COM error code to its Excel error string, or None."""
+    return _COM_ERROR_CODES.get(value)
+
+
+def has_formula_error(cell):
+    """Check if a cell has a formula error.
+
+    Handles both string error values (#DIV/0!, #REF!, etc.) and
+    COM integer error codes (-2146826281, etc.) returned by win32com.
+    """
+    value = cell.get('value')
+    if is_com_error(value):
+        return True
+    value_str = str(value or '')
+    formula_str = str(cell.get('formula') or '')
+    return _is_error_value(value_str) or _is_error_value(formula_str)
+
+
+def is_large_percentage(cell):
+    """Check if a cell contains a large percentage (>= 100%, hardcoded)."""
+    fmt = cell.get('numberFormat') or ''
+    if '%' not in fmt:
+        return False
+    if cell.get('formula'):
+        return False
+    value = cell.get('value')
+    if not _is_numeric(value):
+        return False
+    # In spreadsheets, 1.0 = 100%
+    return abs(_to_float(value)) >= 1
+
+
+def categorize_cell(cell):
+    """Return (cell, issues_list) for a single cell dict."""
+    issues = []
+    if is_large_percentage(cell):
+        issues.append(LARGE_PERCENTAGE)
+    if is_hardcoded_number(cell):
+        issues.append(HARDCODED_NUMBER)
+    is_error = has_formula_error(cell)
+    if is_error:
+        issues.append(INVALID_FORMULA)
+    # Only flag hardcoded numbers in formula when there's no error —
+    # error formulas need the error fixed first, flagging "=1/0" for
+    # containing hardcoded 1 and 0 is just noise.
+    if not is_error and cell.get('formula') and has_hardcoded_numbers_in_formula(cell['formula']):
+        issues.append(HARDCODED_NUMBER_IN_FORMULA)
+    return issues
+
+
+def categorize_cells(dirty_cells):
+    """Categorize a list of dirty cell dicts into groups.
+
+    Returns a dict with keys:
+      good, large_percentages, hardcoded_numbers,
+      hardcoded_in_formulas, invalid_formulas, all_problems
+    Each value is a list of (cell, issues) tuples (except good which is just cells).
+    """
+    good = []
+    large_pct = []
+    hardcoded = []
+    hardcoded_in_formula = []
+    invalid = []
+    all_problems = []
+
+    for cell in dirty_cells:
+        issues = categorize_cell(cell)
+        if not issues:
+            good.append(cell)
+        else:
+            entry = (cell, issues)
+            all_problems.append(entry)
+            if LARGE_PERCENTAGE in issues:
+                large_pct.append(entry)
+            if HARDCODED_NUMBER in issues:
+                hardcoded.append(entry)
+            if HARDCODED_NUMBER_IN_FORMULA in issues:
+                hardcoded_in_formula.append(entry)
+            if INVALID_FORMULA in issues:
+                invalid.append(entry)
+
+    return {
+        GOOD: good,
+        LARGE_PERCENTAGE: large_pct,
+        HARDCODED_NUMBER: hardcoded,
+        HARDCODED_NUMBER_IN_FORMULA: hardcoded_in_formula,
+        INVALID_FORMULA: invalid,
+        ALL_PROBLEMS: all_problems,
+    }

package/xll/modules/shortcut_xl/_com.py

@@ -0,0 +1,108 @@
+"""Excel COM helpers — locate the Excel Application object."""
+
+import ctypes
+from ctypes import wintypes
+from ._log import xl_log
+
+# AccessibleObjectFromWindow native object ID
+_OBJID_NATIVEOM = -16
+
+# Excel window class names (hierarchy: XLMAIN → XLDESK → EXCEL7)
+_WC_XLMAIN = "XLMAIN"
+_WC_XLDESK = "XLDESK"
+_WC_EXCEL7 = "EXCEL7"
+
+
+class _GUID(ctypes.Structure):
+    _fields_ = [
+        ('Data1', ctypes.c_ulong),
+        ('Data2', ctypes.c_ushort),
+        ('Data3', ctypes.c_ushort),
+        ('Data4', ctypes.c_byte * 8),
+    ]
+
+
+# IID_IDispatch = {00020400-0000-0000-C000-000000000046}
+_IID_IDISPATCH = _GUID(
+    0x00020400, 0x0000, 0x0000,
+    (ctypes.c_byte * 8)(0xC0, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x46))
+
+
+_user32 = ctypes.windll.user32
+
+
+def _find_own_xlmain():
+    """Find the XLMAIN window belonging to our own process.
+
+    The XLL runs in-process, so our PID == Excel's PID.
+    EnumWindows + GetWindowThreadProcessId ensures we find the right
+    instance even when multiple Excels are open.
+
+    Uses local variables captured by a closure instead of module-level
+    mutable globals, making this safe for concurrent calls."""
+    target_pid = ctypes.windll.kernel32.GetCurrentProcessId()
+    result = ctypes.c_void_p(0)
+
+    @ctypes.WINFUNCTYPE(wintypes.BOOL, wintypes.HWND, wintypes.LPARAM)
+    def callback(hwnd, _lparam):
+        buf = ctypes.create_unicode_buffer(32)
+        _user32.GetClassNameW(hwnd, buf, 32)
+        if buf.value != _WC_XLMAIN:
+            return True
+        pid = wintypes.DWORD()
+        _user32.GetWindowThreadProcessId(hwnd, ctypes.byref(pid))
+        if pid.value == target_pid:
+            result.value = hwnd
+            return False
+        return True
+
+    _user32.EnumWindows(callback, 0)
+    return result.value
+
+
+def _ensure_com_init():
+    """Initialize COM on the current thread (idempotent)."""
+    import pythoncom
+    pythoncom.CoInitialize()
+
+
+def xl_app():
+    """Return the Excel Application COM object.
+
+    Performs a fresh HWND lookup every call. The cost is negligible
+    (microseconds) and avoids stale-reference bugs from caching.
+
+    Uses EnumWindows + PID matching to find this process's Excel,
+    not just the first XLMAIN window on the desktop."""
+    _ensure_com_init()
+    import pythoncom
+    import win32com.client
+
+    # Use windll (not oledll) so we get the HRESULT as a return value
+    # instead of an auto-raised OSError — lets us fall through to the
+    # GetActiveObject fallback on failure.
+    oleacc = ctypes.windll.oleacc
+
+    xlmain = _find_own_xlmain()
+    if xlmain:
+        xldesk = _user32.FindWindowExW(xlmain, 0, _WC_XLDESK, None)
+        excel7 = _user32.FindWindowExW(xldesk, 0, _WC_EXCEL7, None) if xldesk else 0
+        if excel7:
+            punk = ctypes.c_void_p()
+            hr = oleacc.AccessibleObjectFromWindow(
+                excel7, _OBJID_NATIVEOM, ctypes.byref(_IID_IDISPATCH), ctypes.byref(punk))
+            if hr == 0 and punk.value:
+                iunk = pythoncom.ObjectFromAddress(punk.value)
+                disp = iunk.QueryInterface(pythoncom.IID_IDispatch)
+                window = win32com.client.Dispatch(disp)
+                return window.Application
+
+    # Fallback — try ROT, but NEVER create a new instance.
+    xl_log("xl_app: HWND approach failed, trying GetActiveObject")
+    try:
+        return win32com.client.GetActiveObject("Excel.Application")
+    except Exception as e:
+        raise RuntimeError(
+            "Could not find a running Excel instance. "
+            "Make sure Excel is open before loading the XLL."
+        ) from e