Skip to content

docs: plain-language parity page and stale-claim fixes - #29

Merged
ipfizz merged 3 commits into
mainfrom
docs/readable-parity
Sep 29, 2026
Merged

ipfizz merged 3 commits into
mainfrom
docs/readable-parity

Conversation

@ipfizz

@ipfizz ipfizz commented Sep 28, 2026

Copy link
Copy Markdown
Owner

Rewrites the Electron parity page (/docs/migrating/parity) so a developer can read it without knowing Bunmaska's internals.

What changed

  • Layout: the table keeps one plain sentence per module. A new "Module by module" section follows it, with one heading per module. Each section answers four questions:
    • Does it work like Electron?
    • What is different, and on which OS?
    • What happens if my app calls it: does it throw, do nothing, or return a placeholder?
    • What can I do about it?
  • Wording: internal terms (the WinCairo C API, GDK, SNI, "TS-only", "gated", "honest residue") are replaced by their effect, or explained in a few words the first time they appear.
  • New sections:
    • Linux opt-in switches: the four environment variables that turn features on, and where the app sets them.
    • Why some things can't work on a given OS.
    • A to-do list grouped by OS.
  • Stale claims corrected against the code:
    • macOS now installs Electron's default menu for apps that set none. The page said there was no default menu.
    • Main-process IPC throws on Map, Set, ArrayBuffer and typed arrays (checked by running the encoder); it does not turn them into plain objects. ipc-main.md and webContents.send said the same wrong thing and are fixed too.
    • safeStorage shares one key on Windows as well as macOS and Linux.
    • Windows webContents and powerMonitor are partial, not full.
    • sendInputEvent on Windows now carries mouse buttons and scan codes; the page and web-contents.md said it didn't.
    • The Linux power-save blocker has its own switch, BUNMASKA_ENABLE_LINUX_POWER_BLOCKER.
    • The screen.ts doc comment said macOS reports no work area or display origins; it does.
  • Newly documented gaps:
    • The Windows closed-window memory is freed only when the app exits.
    • Windows move and resize events arrive only when a drag ends.
    • Linux center and setAlwaysOnTop do nothing.
    • A 4th dialog button can't be clicked on Windows.
    • shell.openExternal resolves false instead of rejecting.

How it was checked

A writer rewrote the page. Three reviewers then read it: a fact-checker compared every claim with the code and cited file:line, an Electron developer who had never seen the codebase flagged anything unclear, and a style checker covered markup, anchors and dashes. The writer then revised it using their notes. bun run validate passes in the repo and in website/.

🤖 Generated with Claude Code

@ipfizz
ipfizz merged commit a8eaec8 into main Sep 29, 2026
4 checks passed
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