Skip to content

Fix headless startup window minimization - #831

Draft
qayshp wants to merge 3 commits into
BlueBubblesApp:developmentfrom
qayshp:agent/fix-headless-null-window
Draft

Fix headless startup window minimization#831
qayshp wants to merge 3 commits into
BlueBubblesApp:developmentfrom
qayshp:agent/fix-headless-null-window

Conversation

@qayshp

@qayshp qayshp commented Jul 23, 2026

Copy link
Copy Markdown

Summary

  • Skip window minimization when headless startup intentionally has no BrowserWindow.
  • Preserve the existing start-minimized behavior whenever a window is available.
  • Add a focused regression check for the headless/null-window, disabled, and ordinary minimization paths.

Root cause

Headless mode returns from AppWindow.build() without creating a BrowserWindow. During server initialization, preChecks() still reads the independent start_minimized setting and unconditionally calls this.window.minimize(). When both settings are enabled, the null window dereference rejects startup before the HTTP server begins listening.

The minimization decision now goes through a small null-safe helper. This keeps the normal GUI behavior unchanged while making the headless combination a no-op.

User impact

BlueBubbles can start headlessly from SSH, a LaunchAgent, or another session without a WindowServer connection even when start_minimized remains enabled. Existing GUI launches with start-minimized enabled still minimize their window.

Validation

Passed:

  • npm --workspace @bluebubbles/server run test:headless-window
  • Prettier check for all changed files
  • Targeted ESLint for src/server/index.ts and src/server/utils/WindowUtils.ts
  • Targeted TypeScript --noEmit check for WindowUtils.ts
  • git diff --check

The full repository checks still expose unrelated errors in unchanged origin/development files:

  • Full server lint: existing max-len errors in src/server/api/privateApi/modes/dylibPlugins/index.ts lines 143 and 158.
  • Production server build: existing NodeJS.Timer / clearInterval type mismatch in src/server/lib/ScheduledService.ts line 39.

Fixes #789.

Related: #733.

@qayshp qayshp left a comment

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Self-review: the null guard addresses the reported crash and the focused regression check covers both headless and ordinary window paths. I found one minor diagnostics follow-up to address before this draft is marked ready.

Comment thread packages/server/src/server/utils/WindowUtils.ts Outdated
@qayshp

qayshp commented Jul 23, 2026

Copy link
Copy Markdown
Author

Validation update

Validated on the current SIP-enabled Tahoe host:

  • Passed: npm --workspace @bluebubbles/server run test:headless-window
  • The focused check covers a null headless window, disabled start-minimized behavior, and ordinary window minimization.

A fresh live application startup was not completed. The normal production build remains blocked by the unrelated pre-existing ScheduledService.ts:39 NodeJS.Timer / clearInterval type error, so this result does not claim an end-to-end packaged-app pass.

@qayshp

qayshp commented Jul 28, 2026

Copy link
Copy Markdown
Author

Latest-head validation (235ae213):

  • Moved only the unchanged focused-test script entry to a distinct package.json anchor so this PR merges cleanly with the sibling Server PRs.
  • Re-ran the focused check under Node 20: passed.
  • Changed-file Prettier, targeted ESLint, full-server lint comparison, and git diff --check behaved as documented.
  • The production build reaches only the unchanged ScheduledService.ts:39 type error already present on the base branch.
  • A sequential merge simulation against current origin/development with Server Resolve Tahoe fallback service from chat metadata #832Restore legacy macOS update manifest generation #834 completed without conflicts.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant