openpetswithchatandmcp/docs/bug-squashing.md

# Bug Squashing Week

This document tracks reported desktop bugs, root-cause findings, fix attempts, and community confirmation. Keep this updated before and after each release so we know what worked, what did not, and what still needs tester feedback.

## Tracker format

Each bug should record:

- **Report:** user-visible symptom and affected version/platform.
- **Status:** investigating, fix planned, fixed-awaiting-confirmation, confirmed fixed, not fixed.
- **Likely cause:** current best explanation with confidence.
- **Fix attempts:** code changes or release versions that attempted to address it.
- **Result:** local verification plus community feedback.
- **Next action:** what to try next if still not confirmed.

---

## Windows transparent familiar block and lost interaction

- **GitHub issue:** https://github.com/alvinunreal/familiaros/issues/18
- **Platform:** Windows
- **Reported version(s):** `2.0.5`; also reproduced by reporter when building from source.
- **Status:** first fix implemented locally; awaiting checks, release, and community confirmation.

### Bug A: gray block behind the familiar

#### Report

The app opens normally on Windows, but the familiar is surrounded by a gray rectangular block instead of a transparent background.

#### Current rendering path

- Familiar windows are transparent frameless Electron `BrowserWindow`s.
- Main options are in `apps/desktop/src/familiar-window.ts`:
  - `transparent: true`
  - `frame: false`
  - `backgroundColor: "#00000000"`
  - `hasShadow: false`
  - `show: false`
- Familiar HTML/CSS sets transparent page background:
  - `html, body { ... background: transparent; ... }`
- The familiar shell currently uses CSS `filter: drop-shadow(...)`.
- The speech/status bubble currently uses CSS `backdrop-filter: blur(...)`.

#### Likely cause

Windows/Electron transparent-window compositing is probably producing an opaque backing rectangle.

Most suspicious triggers:

1. CSS `filter: drop-shadow(...)` on `.familiar-shell` inside a transparent layered window.
2. CSS `backdrop-filter: blur(...)` on `.bubble` inside a transparent layered window.
3. Showing the transparent window before the first clean renderer paint.

Confidence: **medium-high**.

Electron has documented transparent-window limitations, and related reports exist for Windows transparent windows showing black/gray/invalid backgrounds, especially around GPU/compositor behavior and filter/backdrop-filter effects.

Useful references:

- Electron custom window styles / transparent window limitations: https://www.electronjs.org/docs/latest/tutorial/custom-window-styles
- Electron `BrowserWindow` lifecycle / `ready-to-show`: https://www.electronjs.org/docs/latest/api/browser-window
- Backdrop/filter transparent-window issue pattern: https://github.com/electron/electron/issues/26029
- Windows transparent background reports: https://github.com/electron/electron/issues/40515
- Windows transparency regression examples: https://github.com/electron/electron/issues/48592

#### Planned fix attempts

Try these in order:

1. Gate/remove `backdrop-filter` on Windows (including `.bubble.is-pinned`).
2. Gate/remove or simplify `.familiar-shell` `drop-shadow` on Windows.
3. Delay showing the familiar until first successful load/render (`ready-to-show` or an explicit renderer-ready signal).
4. If still broken, test Windows-specific GPU/compositor mitigations. Do **not** start with global `app.disableHardwareAcceleration()` unless the safer CSS/lifecycle fixes fail, because it may vary by machine and can regress other rendering.

#### Verification plan

Ask Windows testers to confirm:

- Built-in familiar has no gray/black rectangle.
- Installed/gallery familiars have no gray/black rectangle.
- Familiar bubbles do not create a gray/black rectangle when visible.
- Behavior after app restart is still correct.

#### Results log

| Date | Version/Build | Attempt | Local result | Community result | Notes |
| --- | --- | --- | --- | --- | --- |
| 2026-05-14 | unreleased | Gate Windows `.familiar-shell` `drop-shadow` and `.bubble` `backdrop-filter` to `none` | Pending checks | Pending | First low-risk compositor mitigation; needs Windows tester confirmation. |
| 2026-06-17 | unreleased | Also gate `.bubble.is-pinned` `backdrop-filter` on Windows; add packaging contract assertion | Implemented | Pending | Extends compositor mitigation to pinned plugin bubbles; tracked in `check-packaging-contract.ts`. |

---

### Bug B: cannot move or right-click familiar after changing familiar

#### Report

On Windows, the familiar can initially be moved and right-clicked. After changing to another familiar, it cannot be moved or right-clicked anymore. Exiting and launching the app again restores interaction.

#### Current input path

- Default familiar window is reused instead of recreated.
- Familiar change calls `refreshDefaultPetContent()`.
- `refreshDefaultPetContent()` reloads the existing familiar window content with `loadFile(...)`.
- Input handling uses Electron `setIgnoreMouseEvents(true, { forward: true })` on Windows/macOS so transparent background clicks pass through.
- The renderer preload sends hit-test and drag IPC based on `elementFromPoint(...).closest(".familiar-shell, .bubble")`.
- Current passthrough setup only runs once after the first load:
  - `window.webContents.once("did-finish-load", () => setPassthrough(true));`

#### Likely cause

The `BrowserWindow` keeps OS-level mouse passthrough state across `loadFile(...)` reloads, but our code only re-arms/reset it once. After familiar change, Windows can leave the window in ignored/pass-through mode or lose forwarded mouse events. Then mouse events do not reach the renderer, so drag and context-menu handling never start.

Confidence: **high**.

This matches Electron reports where `setIgnoreMouseEvents(true, { forward: true })` forwarding breaks after reload/refresh or becomes stuck.

Useful references:

- Electron custom interactions / click-through windows: https://www.electronjs.org/docs/latest/tutorial/custom-window-interactions
- Electron `BrowserWindow#setIgnoreMouseEvents`: https://www.electronjs.org/docs/latest/api/browser-window
- Forwarding breaks after refresh pattern: https://github.com/electron/electron/issues/15376
- Modern click-through/reload stuck report: https://github.com/electron/electron/issues/49982
- Windows forwarding/hover instability: https://github.com/electron/electron/issues/30808

#### Planned fix attempts

Try these in order:

1. Make passthrough reload-safe:
   - Reset `setIgnoreMouseEvents(false)` before every familiar content navigation/reload.
   - Clear any active drag state before navigation/reload.
   - Re-apply passthrough after every load, not only the first load.
2. Add an explicit renderer-ready IPC from `familiar-preload.cjs` after mouse handlers are installed, then resync passthrough from main.
3. If Windows still fails, stop using full `loadFile(...)` as the familiar-switch primitive:
   - update DOM/sprite data in-place, or
   - recreate the familiar window on familiar change while preserving position and visibility.

#### Verification plan

Ask Windows testers to confirm:

- Familiar can be dragged immediately after launch.
- Familiar right-click menu opens immediately after launch.
- Change from built-in familiar to installed familiar, then drag and right-click still work.
- Change from installed familiar back to built-in familiar, then drag and right-click still work.
- Repeat familiar switching multiple times without restarting.
- Try while a bubble/status badge is visible.

#### Results log

| Date | Version/Build | Attempt | Local result | Community result | Notes |
| --- | --- | --- | --- | --- | --- |
| 2026-05-14 | unreleased | Reset passthrough before familiar content reload, re-arm after every load, and add renderer-ready IPC | Pending checks | Pending | Targets Electron `setIgnoreMouseEvents(..., { forward: true })` reload/forwarding flake. |

---

## Implementation notes for upcoming fix

Recommended first patch scope:

1. Update familiar window passthrough lifecycle in `apps/desktop/src/familiar-window.ts`.
2. Update `apps/desktop/familiar-preload.cjs` if adding renderer-ready IPC.
3. Gate Windows-specific visual effects in `createPetWindowCss(...)`.
4. Add or update contract checks in `apps/desktop/src/check-packaging-contract.ts` so future changes do not regress the Windows workaround.

Potential release note wording after implementation:

> Fixed Windows familiar window transparency and interaction reliability when switching familiars. This release removes fragile transparent-window visual effects on Windows and reinitializes click-through/drag handling after familiar reloads. Please report whether gray familiar backgrounds or lost drag/right-click behavior still occur on your Windows machine.