Windows Companion — Architecture & Audit Doc

flowchart TB
  subgraph ENTRY["Entry points"]
    RUNPY["run_companion.py
(sys.path shim + main())"]
    MAIN["main.py
main()"]
  end

  subgraph GUARD["Single-instance guard (main.py)"]
    MUTEX["_acquire_single_instance()
Local named mutex"]
    PROBE["_another_companion_running()
GET /status on 38743-38747"]
  end

  subgraph COMLAYER["COM layer (excel_com.py)"]
    WORKER["ComWorker
STA thread + Queue, 2s timeout"]
    COMEXCEL["ComExcel
real backend: GetActiveObject only"]
    FAKEEXCEL["FakeExcel
in-memory test backend"]
    EVBUF["EventBuffer
(events.py) coalesce+cap"]
    SPANBUF["SpanBuffer
(events.py) spotlight spans"]
  end

  subgraph HTTPLAYER["HTTP server (server.py)"]
    BIND["bind_server()
first free port 38743-38747"]
    HANDLER["Handler(BaseHTTPRequestHandler)
routes /status /pair /workspace /file
/open /open-many /record/* /spotlight*"]
    COMPANION_STATE["Companion
shared state: paired, recording,
excel_cached, spotlight_active"]
    WATCHDOG["_watchdog thread
check_idle() every 2s"]
  end

  subgraph AUTHMOD["Auth (auth.py)"]
    AUTHCLS["Auth
token check() / pair()"]
    TOKENFILE["%APPDATA%\\ExcelRewind\\token.txt"]
    DIALOG["confirm_pairing_dialog()
native MessageBoxW Yes/No"]
  end

  subgraph TRAYMOD["Tray (tray.py)"]
    TRAYRUN["run() — pystray icon
Status / Quit menu"]
    TRAYFALLBACK["_run_ctypes()
Shell_NotifyIcon fallback"]
  end

  subgraph WINFOCUSMOD["winfocus.py"]
    FOCUS["bring_to_foreground()
find_window_by_title()"]
  end

  RUNPY --> MAIN
  MAIN --> PROBE --> MUTEX
  MAIN --> WORKER
  WORKER --> COMEXCEL
  COMEXCEL --> EVBUF
  COMEXCEL --> SPANBUF
  MAIN --> AUTHCLS
  AUTHCLS --> TOKENFILE
  AUTHCLS --> DIALOG
  COMEXCEL -.spotlight foreground.-> FOCUS
  MAIN --> COMPANION_STATE
  COMPANION_STATE --> WORKER
  COMPANION_STATE --> AUTHCLS
  MAIN --> BIND --> HANDLER
  HANDLER --> COMPANION_STATE
  MAIN --> WATCHDOG --> COMPANION_STATE
  MAIN --> TRAYRUN
  TRAYRUN -.import fails.-> TRAYFALLBACK
  TRAYRUN --> COMPANION_STATE

  FAKEEXCEL -.tests only.-> WORKER

flowchart LR
  ADDIN["Excel add-in
(apps/addin-excel/src/companion.ts)"] -->|"HTTP/1.1 JSON, loopback,
Bearer token"| HANDLER["server.py Handler
do_GET / do_POST"]
  HANDLER -->|"lambda b: b.method(...)
queued on ComWorker"| WORKER["ComWorker._q (Queue)"]
  WORKER -->|"fn(backend) on STA thread"| COMEXCEL["ComExcel"]
  COMEXCEL -->|"GetActiveObject('Excel.Application')
Workbooks / SaveCopyAs / Range.Goto"| EXCEL["Running Excel.exe
(COM Application object)"]
  EXCEL -->|"SheetChange / WindowActivate /
SheetSelectionChange events (sync callback)"| SINK["_Events sink
(DispatchWithEvents)"]
  SINK -->|"cell {workbook,sheet,addr,value,formula}"| EVBUF["EventBuffer.add()"]
  SINK -->|"focus/select spans"| SPANBUF["SpanBuffer.focus()/select()"]
  EVBUF -->|"poll(since) -> {events[], dropped}"| HANDLER
  SPANBUF -->|"poll() -> spans[]"| HANDLER
  HANDLER -->|"JSON response"| ADDIN
  COMEXCEL -->|"bytes via SaveCopyAs(tmp) -> read -> delete tmp"| HANDLER
  HANDLER -->|"application/octet-stream"| ADDIN

flowchart LR
  ADDIN["add-in: attached reference
workbook bytes (base64)"] -->|"POST /open or /open-many
{name, data_b64}"| HANDLER["server.py"]
  HANDLER -->|"base64.b64decode + 100MB cap"| BYTES["raw bytes"]
  BYTES -->|"_open_ref(name, data)"| COMEXCEL["ComExcel"]
  COMEXCEL -->|"write file"| REFDIR["%TEMP%\\ExcelRewind\\refs\\<safe-name>"]
  COMEXCEL -->|"unblock_file(): remove :Zone.Identifier ADS"| REFDIR
  COMEXCEL -->|"Workbooks.Open(path, ReadOnly=True)"| EXCEL["Excel.exe"]
  COMEXCEL -->|"maximize + refocus primary"| EXCEL
  COMEXCEL -->|"{opened, alreadyOpen} or per-file error"| HANDLER --> ADDIN

sequenceDiagram
  participant OS as "Windows (shortcut/autostart/explorer.exe)"
  participant Main as "main.py main()"
  participant Probe as "_another_companion_running()"
  participant Mutex as "CreateMutexW"
  participant Worker as "ComWorker/ComExcel"
  participant HTTP as "bind_server()"
  participant Tray as "tray.run()"

  OS->>Main: launch ExcelRewindCompanion.exe
  Main->>Probe: GET /status on 38743..38747 (300ms each)
  alt a live companion (any version) answers with product marker
    Probe-->>Main: True
    Main->>OS: MessageBoxW "already running"
    Main->>Main: sys.exit(0)
  else nothing answers
    Main->>Mutex: CreateMutexW("Local\ExcelRewindCompanion.SingleInstance")
    alt ERROR_ALREADY_EXISTS
      Mutex-->>Main: already held
      Main->>OS: MessageBoxW "already running"
      Main->>Main: sys.exit(0)
    else acquired
      Main->>Worker: ComExcel() + ComWorker(backend) — spawns STA thread
      Main->>Main: Auth() loads/creates token.txt
      Main->>HTTP: bind_server() — first free port in range
      Main->>Main: spawn _watchdog thread (check_idle every 2s)
      Main->>Main: write companion-port.txt
      Main->>Main: register atexit + SIGINT/SIGTERM/SIGBREAK -> _shutdown
      Main->>Tray: run_tray(companion, port, _shutdown) — blocks main thread
      Note over Tray: pystray import/init failure -> _run_ctypes fallback,
total tray failure -> httpd.serve_forever() headless
    end
  end

sequenceDiagram
  participant Addin as "add-in companion.ts"
  participant Handler as "server.py Handler"
  participant Auth as "auth.py Auth"
  participant User as "Windows user"

  Addin->>Handler: scanPorts() — GET /status on each port/scheme
  Handler-->>Addin: 200 {product:"excelrewind-companion", version, excelDetected}
  Addin->>Handler: POST /pair (Origin: https://addin.excelrewind.com)
  Handler->>Handler: _origin_host_ok() — Origin allow-listed AND Host = loopback:port
  alt origin/host check fails
    Handler-->>Addin: 403 forbidden-origin
  else ok
    Handler->>Auth: pair(origin)
    alt a dialog is already open
      Auth-->>Handler: raise PairingBusy
      Handler-->>Addin: 409 pairing-in-progress
    else
      Auth->>User: MessageBoxW "Allow <origin> to connect to the Companion?"
(force-foregrounded via AttachThreadInput)
      alt user clicks Yes
        User-->>Auth: IDYES
        Auth-->>Handler: token (32 hex chars)
        Handler->>Handler: companion.mark_seen() — paired=True
        Handler-->>Addin: 200 {token}
        Addin->>Addin: localStorage.setItem('rewind.companion-token', token)
      else user clicks No / dialog times out
        User-->>Auth: IDNO / non-6
        Auth-->>Handler: None
        Handler-->>Addin: 403 pairing-declined
      end
    end
  end

sequenceDiagram
  participant Addin as "add-in (records primary itself)"
  participant Handler as "server.py"
  participant Companion as "Companion (shared state)"
  participant Worker as "ComWorker (STA queue)"
  participant Com as "ComExcel"
  participant Excel as "Excel.exe (COM events)"

  Addin->>Handler: POST /record/start {exclude:"Primary.xlsx", captureChanges:true}
  Handler->>Companion: start_record(exclude, captureChanges)
  Companion->>Worker: submit(b.start_record)
  Worker->>Com: start_record(exclude, capture_changes)
  Com->>Excel: DispatchWithEvents(app, _Events) — hooks OnSheetChange/
OnWindowActivate/OnSheetSelectionChange
  Com-->>Handler: recording started (Application ref retained while recording)
  Handler-->>Addin: 200 {recording:true, exclude}

  loop every ~2-3s while recording
    Excel-->>Com: OnSheetChange(sh, target) [sync COM callback]
    Com->>Com: EventBuffer.add() per changed cell (coalesced 500ms/cell)
    Addin->>Handler: GET /record/events?since=<seq>
    Handler->>Companion: _touch_poll() (feeds R12 idle watchdog)
    Handler->>Worker: submit(b.poll_events(since))
    Worker->>Com: PumpWaitingMessages() then buffer.poll(since)
    Com-->>Handler: {events:[...], dropped, spotlights:[...]}
    Handler-->>Addin: 200 JSON
  end

  alt add-in stops polling for >30s (R12)
    Companion->>Companion: _watchdog.check_idle() detects idle > RECORD_IDLE_TIMEOUT
    Companion->>Worker: submit(b.stop_record) — auto-stop
  else add-in explicitly stops
    Addin->>Handler: POST /record/stop
    Handler->>Companion: stop_record()
    Companion->>Worker: submit(b.stop_record)
    Worker->>Com: stop_record() — pump, close final span, drop sink + app ref
    Com-->>Handler: completed spotlight spans[]
    Handler-->>Addin: 200 {recording:false, spotlights:[...]}
  end

sequenceDiagram
  participant Installer as "ExcelRewind-Setup.nsi StopCompanion"
  participant PS as "hidden PowerShell"
  participant Handler as "server.py /shutdown"
  participant Main as "main._shutdown()"
  participant Worker as "ComWorker/ComExcel"

  Installer->>PS: Invoke-RestMethod POST http://127.0.0.1:<port>/shutdown
for port in 38743..38747
  PS->>Handler: POST /shutdown (no bearer token, no Origin header)
  Handler->>Handler: _origin_host_ok() — Origin absent is OK, Host must be loopback:port
  alt origin present but not allow-listed
    Handler-->>PS: 403 forbidden-origin
  else ok (local CLI has no Origin)
    Handler-->>PS: 200 {stopping:true} (responds BEFORE tearing down)
    Handler->>Main: spawn thread -> sleep 0.3s -> shutdown_hook()
    Main->>Main: _shutdown(): stop_event.set(), httpd.shutdown()
    Main->>Worker: worker.close() — submit shutdown(), join STA thread
    Worker->>Worker: ComExcel.shutdown(): drop sink, release Application ref,
CoUninitialize() ON the STA thread
  end
  Installer->>Installer: Sleep 1500ms
  Installer->>Installer: taskkill /IM ExcelRewindCompanion.exe (graceful WM_CLOSE)
  Installer->>Installer: Sleep 1500ms
  Installer->>Installer: taskkill /F /IM ExcelRewindCompanion.exe (final fallback)
  Note over Installer,Worker: Per main.py, the COM ref is only held DURING active
recording, /shutdown makes even that case clean, and a
force-kill while idle already holds no ref (ghost-Excel fix).

sequenceDiagram
  participant Viewer as "add-in replay (or web viewer, via add-in bridge)"
  participant Handler as "server.py"
  participant Com as "ComExcel"
  participant Excel as "Excel windows"
  participant Win as "winfocus.py"

  Viewer->>Handler: POST /spotlight {name, sheet, range}
  Handler->>Com: spotlight(name, sheet, rng) via ComWorker
  Com->>Com: capture current ActiveWorkbook.Name as _spotlight_prev (once)
  Com->>Excel: wb.Activate(), sheet.Activate(), app.Goto(range, True)
  Com->>Win: bring_to_foreground(hwnd) — AttachThreadInput dance
(defeats the foreground-lock timeout)
  alt named workbook is not open
    Com-->>Handler: raise FileNotFoundError
    Handler-->>Viewer: 404 not-open (replay continues without the freeze)
  else opened
    Com-->>Handler: restore-target name
    Handler-->>Viewer: 200 {spotlighted:true, restore}
  end

  Viewer->>Handler: POST /spotlight/clear (when the freeze dwell ends)
  Handler->>Com: clear_spotlight()
  Com->>Excel: re-Activate the pre-spotlight workbook
  Handler-->>Viewer: 200 {cleared:true, restored}

  Note over Handler: If the viewer crashes/closes mid-freeze and never clears,
the 2s watchdog auto-clears after SPOTLIGHT_IDLE_TIMEOUT=15s
so focus can never be stranded on the source workbook.

flowchart LR
  ADDIN["addin-excel
(apps/addin-excel/src/companion.ts)"] <-->|"loopback HTTP/1.1 JSON,
Bearer token, CORS-locked"| COMPANION["companion-win"]
  COMPANION -->|"COM: GetActiveObject,
Workbooks/Range/Application events"| EXCEL["Microsoft Excel
(local process, already running)"]
  COMPANION -->|"user32.dll: MessageBoxW,
SetForegroundWindow, Shell_NotifyIcon"| WINOS["Windows OS APIs"]
  INSTALLER["installer-deploy
(ExcelRewind-Setup.nsi)"] -->|"POST /shutdown (no auth),
then taskkill ladder"| COMPANION
  INSTALLER -->|"stages Nuitka .dist folder
into the installer payload"| COMPANION