{"_id":"@covas-labs/electron-overlay","_rev":"7-4a6760268449e405549becf1ed9cf100","name":"@covas-labs/electron-overlay","dist-tags":{"bootstrap":"0.0.0-bootstrap.0","latest":"0.5.2"},"versions":{"0.0.0-bootstrap.0":{"name":"@covas-labs/electron-overlay","version":"0.0.0-bootstrap.0","_id":"@covas-labs/electron-overlay@0.0.0-bootstrap.0","maintainers":[{"name":"lucaelin","email":"npm@luca.lsys.ac"}],"homepage":"https://github.com/COVAS-Labs/electron-overlay#readme","bugs":{"url":"https://github.com/COVAS-Labs/electron-overlay/issues"},"dist":{"shasum":"5409695b6d30889a528f12c6473f1fccf3392231","tarball":"https://registry.npmjs.org/@covas-labs/electron-overlay/-/electron-overlay-0.0.0-bootstrap.0.tgz","fileCount":3,"integrity":"sha512-6QeXY66D5EbkzYfXh7jHJn7LMQeUenJQOI+TLd3l09j7mdcGCwiqHmKIaG1kexOyfRaqqpTbuLO1jyPO/KhPgQ==","signatures":[{"sig":"MEUCIQD84CcN1FYzxR1cY43OiOHlXqvFzXM8yFrFFy0KEYp5TQIgDivKzilmTaZ5ug/ezd4S7sXe+1qmZaHDypPk7YKcRiE=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":607},"main":"index.js","gitHead":"fc7f1f223662df24263eddde6016ca5b6892dc37","_npmUser":{"name":"lucaelin","email":"npm@luca.lsys.ac"},"repository":{"url":"git+https://github.com/COVAS-Labs/electron-overlay.git","type":"git"},"_npmVersion":"11.17.0","description":"Bootstrap placeholder for the electron-overlay release pipeline.","directories":{},"_nodeVersion":"24.19.0","publishConfig":{"access":"public","registry":"https://registry.npmjs.org"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/electron-overlay_0.0.0-bootstrap.0_1786112453892_0.9738261903132024","host":"s3://npm-registry-packages-npm-production"}},"0.1.0":{"name":"@covas-labs/electron-overlay","version":"0.1.0","_id":"@covas-labs/electron-overlay@0.1.0","maintainers":[{"name":"lucaelin","email":"npm@luca.lsys.ac"}],"homepage":"https://github.com/COVAS-Labs/electron-overlay#readme","bugs":{"url":"https://github.com/COVAS-Labs/electron-overlay/issues"},"dist":{"shasum":"ebc034e94e29a6f3396a59bcb84332b334d3b3e4","tarball":"https://registry.npmjs.org/@covas-labs/electron-overlay/-/electron-overlay-0.1.0.tgz","fileCount":4,"integrity":"sha512-wTnNlExZdUvDbsNqy/nBvmxwm3MPlEtX1L2NgOQv9chyyMf0BFOJBoRGuTSmPH2oQcBezTFEcqkAQx0L++5pmQ==","signatures":[{"sig":"MEQCIFMAm/KICMBHn0OeoprlTLuhxy0Jvflc9qoO2iX3cL8cAiBBM6EO5dVsqR77bRSazTsghXlI234EI5m4K1xm0nlAuA==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@covas-labs%2felectron-overlay@0.1.0","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":9902},"main":"dist/index.js","type":"module","types":"dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"gitHead":"fc7f1f223662df24263eddde6016ca5b6892dc37","_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:07b36809-da6f-4847-b700-7ba9a3533646"}},"repository":{"url":"git+https://github.com/COVAS-Labs/electron-overlay.git","type":"git"},"_npmVersion":"12.0.2","description":"Native window policy controller for Electron overlays on Linux, Windows, and macOS.","directories":{},"_nodeVersion":"24.18.0","publishConfig":{"access":"public","registry":"https://registry.npmjs.org"},"_hasShrinkwrap":false,"peerDependencies":{"electron":">=37"},"optionalDependencies":{"@covas-labs/electron-overlay-prebuilt-linux-x64":"0.1.0","@covas-labs/electron-overlay-prebuilt-win32-x64":"0.1.0","@covas-labs/electron-overlay-prebuilt-darwin-arm64":"0.1.0"},"_npmOperationalInternal":{"tmp":"tmp/electron-overlay_0.1.0_1786114230712_0.904872391015692","host":"s3://npm-registry-packages-npm-production"}},"0.2.1":{"name":"@covas-labs/electron-overlay","version":"0.2.1","license":"MIT","_id":"@covas-labs/electron-overlay@0.2.1","maintainers":[{"name":"lucaelin","email":"npm@luca.lsys.ac"}],"homepage":"https://github.com/COVAS-Labs/electron-overlay#readme","bugs":{"url":"https://github.com/COVAS-Labs/electron-overlay/issues"},"dist":{"shasum":"d5fc9ee8788ae26c7cc23763d26c824215fff938","tarball":"https://registry.npmjs.org/@covas-labs/electron-overlay/-/electron-overlay-0.2.1.tgz","fileCount":5,"integrity":"sha512-t7Cd0Leori++eVoruji6uzzPh6mtvq4d7USGH+SRZxpORySutCXF4QMDLyQaNVxasSIM++Dkognxb5BEhIvjWA==","signatures":[{"sig":"MEYCIQD+jgy/EnFtAktSrepadlC3AxN5qfubbuP8fk2DJ1q59gIhAJfSetuLo6ytUg7o36sLfDO7FQFwBY8lBdBVW13p/9N3","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@covas-labs%2felectron-overlay@0.2.1","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":22848},"main":"dist/index.js","type":"module","_from":"file:/home/runner/work/electron-overlay/electron-overlay/artifacts/download/covas-labs-electron-overlay-0.2.1.tgz","types":"dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:07b36809-da6f-4847-b700-7ba9a3533646"}},"_resolved":"/home/runner/work/electron-overlay/electron-overlay/artifacts/download/covas-labs-electron-overlay-0.2.1.tgz","_integrity":"sha512-t7Cd0Leori++eVoruji6uzzPh6mtvq4d7USGH+SRZxpORySutCXF4QMDLyQaNVxasSIM++Dkognxb5BEhIvjWA==","repository":{"url":"git+https://github.com/COVAS-Labs/electron-overlay.git","type":"git"},"_npmVersion":"11.6.2","description":"Cross-platform window policy controller for Electron overlays.","directories":{},"_nodeVersion":"24.18.0","publishConfig":{"access":"public","registry":"https://registry.npmjs.org"},"_hasShrinkwrap":false,"peerDependencies":{"electron":">=37"},"optionalDependencies":{"@covas-labs/electron-overlay-prebuilt-linux-x64":"0.2.1","@covas-labs/electron-overlay-prebuilt-win32-x64":"0.2.1","@covas-labs/electron-overlay-prebuilt-darwin-arm64":"0.2.1"},"_npmOperationalInternal":{"tmp":"tmp/electron-overlay_0.2.1_1786150656059_0.9177081836488583","host":"s3://npm-registry-packages-npm-production"}},"0.3.0":{"name":"@covas-labs/electron-overlay","version":"0.3.0","license":"MIT","_id":"@covas-labs/electron-overlay@0.3.0","maintainers":[{"name":"lucaelin","email":"npm@luca.lsys.ac"}],"homepage":"https://github.com/COVAS-Labs/electron-overlay#readme","bugs":{"url":"https://github.com/COVAS-Labs/electron-overlay/issues"},"dist":{"shasum":"b53c2f34573475d2375a89ac150d54874632fe52","tarball":"https://registry.npmjs.org/@covas-labs/electron-overlay/-/electron-overlay-0.3.0.tgz","fileCount":6,"integrity":"sha512-0fBuPmM0gxfGoFxf6LQmbAH1n8AjOfcpsO4GDrQw4ak5Q6l6kwUzOvZs4capNuOweCUApvc5kOXqDiLao2cgww==","signatures":[{"sig":"MEUCIA4e7gB+lUNpIXO0l7kBu4xH1AzYR74Y9J16QzQ02c5ZAiEA1FMOPGgL0Kbi9GyaYVukwcSZY4kAmBUTdS2sHhmdqrQ=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@covas-labs%2felectron-overlay@0.3.0","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":32804},"main":"dist/index.js","type":"module","_from":"file:/home/runner/work/electron-overlay/electron-overlay/artifacts/download/covas-labs-electron-overlay-0.3.0.tgz","types":"dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:07b36809-da6f-4847-b700-7ba9a3533646"}},"_resolved":"/home/runner/work/electron-overlay/electron-overlay/artifacts/download/covas-labs-electron-overlay-0.3.0.tgz","_integrity":"sha512-0fBuPmM0gxfGoFxf6LQmbAH1n8AjOfcpsO4GDrQw4ak5Q6l6kwUzOvZs4capNuOweCUApvc5kOXqDiLao2cgww==","repository":{"url":"git+https://github.com/COVAS-Labs/electron-overlay.git","type":"git"},"_npmVersion":"11.6.2","description":"Cross-platform window policy controller for Electron overlays.","directories":{},"_nodeVersion":"24.18.0","publishConfig":{"access":"public","registry":"https://registry.npmjs.org"},"_hasShrinkwrap":false,"peerDependencies":{"electron":">=37"},"optionalDependencies":{"@covas-labs/electron-overlay-prebuilt-linux-x64":"0.3.0","@covas-labs/electron-overlay-prebuilt-win32-x64":"0.3.0","@covas-labs/electron-overlay-prebuilt-darwin-arm64":"0.3.0"},"_npmOperationalInternal":{"tmp":"tmp/electron-overlay_0.3.0_1786232083762_0.03037915767180066","host":"s3://npm-registry-packages-npm-production"}},"0.4.0":{"name":"@covas-labs/electron-overlay","version":"0.4.0","license":"MIT","_id":"@covas-labs/electron-overlay@0.4.0","maintainers":[{"name":"lucaelin","email":"npm@luca.lsys.ac"}],"homepage":"https://github.com/COVAS-Labs/electron-overlay#readme","bugs":{"url":"https://github.com/COVAS-Labs/electron-overlay/issues"},"dist":{"shasum":"0d8b769f9613e4a8e559e9e0c75d55f8582eceaf","tarball":"https://registry.npmjs.org/@covas-labs/electron-overlay/-/electron-overlay-0.4.0.tgz","fileCount":6,"integrity":"sha512-QAM+bKCnoN6porTuCXbXtufPZ9FZ82bEwsRd9GPNYsaK/o4YRqTAq9EioyCk3Ss3XYRIGd3EQSCHSdKg02fbfA==","signatures":[{"sig":"MEUCIEv/hB4oTYHm4RRhwFTfnZApKQ/+sifXMb0gK2s0RmxdAiEAl4OQVCa1hDX4woFgJWQv9BZ/h+2mGT2n+aWgYZJJIN4=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@covas-labs%2felectron-overlay@0.4.0","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":57507},"main":"dist/index.js","type":"module","_from":"file:/home/runner/work/electron-overlay/electron-overlay/artifacts/download/covas-labs-electron-overlay-0.4.0.tgz","types":"dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:07b36809-da6f-4847-b700-7ba9a3533646"}},"_resolved":"/home/runner/work/electron-overlay/electron-overlay/artifacts/download/covas-labs-electron-overlay-0.4.0.tgz","_integrity":"sha512-QAM+bKCnoN6porTuCXbXtufPZ9FZ82bEwsRd9GPNYsaK/o4YRqTAq9EioyCk3Ss3XYRIGd3EQSCHSdKg02fbfA==","repository":{"url":"git+https://github.com/COVAS-Labs/electron-overlay.git","type":"git"},"_npmVersion":"11.6.2","description":"Cross-platform window policy controller for Electron overlays.","directories":{},"_nodeVersion":"24.18.0","publishConfig":{"access":"public","registry":"https://registry.npmjs.org"},"_hasShrinkwrap":false,"peerDependencies":{"electron":">=37"},"optionalDependencies":{"@covas-labs/electron-overlay-prebuilt-linux-x64":"0.4.0","@covas-labs/electron-overlay-prebuilt-win32-x64":"0.4.0","@covas-labs/electron-overlay-prebuilt-darwin-arm64":"0.4.0"},"_npmOperationalInternal":{"tmp":"tmp/electron-overlay_0.4.0_1786296709681_0.8656309718013946","host":"s3://npm-registry-packages-npm-production"}},"0.4.1":{"name":"@covas-labs/electron-overlay","version":"0.4.1","license":"MIT","_id":"@covas-labs/electron-overlay@0.4.1","maintainers":[{"name":"lucaelin","email":"npm@luca.lsys.ac"}],"homepage":"https://github.com/COVAS-Labs/electron-overlay#readme","bugs":{"url":"https://github.com/COVAS-Labs/electron-overlay/issues"},"dist":{"shasum":"b89f5696438fe60373ccc910ac728e5c651a6563","tarball":"https://registry.npmjs.org/@covas-labs/electron-overlay/-/electron-overlay-0.4.1.tgz","fileCount":6,"integrity":"sha512-sDWW9Fi2PSEU9TiQl2a6w6UhlDmznqAWkE212/nQNDfzYsgbH/voYuLfiOTWyr/HTj5YMkxdgm+bh3TuqSaFyA==","signatures":[{"sig":"MEUCIQDzBQl0IiUYBL3PGtqlOTebGOqvVt9KZe37fiCCPhBYRAIgMXf/JB+L0SDJroikRFLxQWaIyUHCiB+6XqWhXS0j32s=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@covas-labs%2felectron-overlay@0.4.1","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":57507},"main":"dist/index.js","type":"module","_from":"file:/home/runner/work/electron-overlay/electron-overlay/artifacts/download/covas-labs-electron-overlay-0.4.1.tgz","types":"dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:07b36809-da6f-4847-b700-7ba9a3533646"}},"_resolved":"/home/runner/work/electron-overlay/electron-overlay/artifacts/download/covas-labs-electron-overlay-0.4.1.tgz","_integrity":"sha512-sDWW9Fi2PSEU9TiQl2a6w6UhlDmznqAWkE212/nQNDfzYsgbH/voYuLfiOTWyr/HTj5YMkxdgm+bh3TuqSaFyA==","repository":{"url":"git+https://github.com/COVAS-Labs/electron-overlay.git","type":"git"},"_npmVersion":"11.6.2","description":"Cross-platform window policy controller for Electron overlays.","directories":{},"_nodeVersion":"24.18.0","publishConfig":{"access":"public","registry":"https://registry.npmjs.org"},"_hasShrinkwrap":false,"peerDependencies":{"electron":">=37"},"optionalDependencies":{"@covas-labs/electron-overlay-prebuilt-linux-x64":"0.4.1","@covas-labs/electron-overlay-prebuilt-win32-x64":"0.4.1","@covas-labs/electron-overlay-prebuilt-darwin-arm64":"0.4.1"},"_npmOperationalInternal":{"tmp":"tmp/electron-overlay_0.4.1_1786313845350_0.9969408412555618","host":"s3://npm-registry-packages-npm-production"}},"0.5.2":{"name":"@covas-labs/electron-overlay","version":"0.5.2","description":"Cross-platform window policy controller for Electron overlays.","license":"MIT","repository":{"type":"git","url":"git+https://github.com/COVAS-Labs/electron-overlay.git"},"type":"module","main":"dist/index.js","types":"dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"peerDependencies":{"electron":">=37"},"optionalDependencies":{"@covas-labs/electron-overlay-prebuilt-linux-x64":"0.5.2","@covas-labs/electron-overlay-prebuilt-win32-x64":"0.5.2","@covas-labs/electron-overlay-prebuilt-darwin-arm64":"0.5.2"},"publishConfig":{"registry":"https://registry.npmjs.org","access":"public"},"_id":"@covas-labs/electron-overlay@0.5.2","bugs":{"url":"https://github.com/COVAS-Labs/electron-overlay/issues"},"homepage":"https://github.com/COVAS-Labs/electron-overlay#readme","_integrity":"sha512-18fWtK8I0+z5bjFG6Ob13Ao0HrxXMrpAd4dqy018Hxf3GC6abs3NltPd5m026MrGQ98KlrRAmBGpIsBNdLqByw==","_resolved":"/home/runner/work/electron-overlay/electron-overlay/artifacts/download/covas-labs-electron-overlay-0.5.2.tgz","_from":"file:/home/runner/work/electron-overlay/electron-overlay/artifacts/download/covas-labs-electron-overlay-0.5.2.tgz","_nodeVersion":"24.18.0","_npmVersion":"11.6.2","dist":{"integrity":"sha512-18fWtK8I0+z5bjFG6Ob13Ao0HrxXMrpAd4dqy018Hxf3GC6abs3NltPd5m026MrGQ98KlrRAmBGpIsBNdLqByw==","shasum":"37d79f29ab8d40bd0565b69c866a3800a7be0f10","tarball":"https://registry.npmjs.org/@covas-labs/electron-overlay/-/electron-overlay-0.5.2.tgz","fileCount":6,"unpackedSize":59671,"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@covas-labs%2felectron-overlay@0.5.2","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIDVy1a71BVueXpKCUE54mk1Ib9J35AUQfM/oz1cmd+BgAiEApIx/4c4ZX5R90wZDxi1vORMV7sULeGDwZ7GuptTOyCU="}]},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:07b36809-da6f-4847-b700-7ba9a3533646"}},"directories":{},"maintainers":[{"name":"lucaelin","email":"npm@luca.lsys.ac"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/electron-overlay_0.5.2_1786476467617_0.8018393461979707"},"_hasShrinkwrap":false}},"time":{"created":"2026-08-07T14:20:53.682Z","modified":"2026-08-11T19:27:48.107Z","0.0.0-bootstrap.0":"2026-08-07T14:20:54.041Z","0.1.0":"2026-08-07T14:50:30.846Z","0.2.1":"2026-08-08T00:57:36.198Z","0.3.0":"2026-08-08T23:34:43.906Z","0.4.0":"2026-08-09T17:31:49.827Z","0.4.1":"2026-08-09T22:17:25.502Z","0.5.2":"2026-08-11T19:27:47.763Z"},"bugs":{"url":"https://github.com/COVAS-Labs/electron-overlay/issues"},"license":"MIT","homepage":"https://github.com/COVAS-Labs/electron-overlay#readme","repository":{"type":"git","url":"git+https://github.com/COVAS-Labs/electron-overlay.git"},"description":"Cross-platform window policy controller for Electron overlays.","maintainers":[{"name":"lucaelin","email":"npm@luca.lsys.ac"}],"readme":"# @covas-labs/electron-overlay\n\nA policy controller for transparent Electron overlay windows on Linux, Windows, and macOS. Linux X11/XWayland uses the native addon; native Wayland supports an Electron compatibility backend and an experimental separately owned layer-shell surface.\n\n## Supported platforms\n\nThe published prebuilt packages support Linux x64, Windows x64, and macOS arm64. Other platform and architecture combinations do not currently have a released native addon. The Linux package contains separate X11 and layer-shell modules so Wayland libraries are loaded only when the experimental backend is requested.\n\n## Usage\n\nCreate the `BrowserWindow` without bypassing the window manager:\n\n```js\nimport { BrowserWindow, screen } from 'electron';\nimport {\n  configure,\n  displayToNativeRect,\n  displayToOverlayRect\n} from '@covas-labs/electron-overlay';\n\nconst display = screen.getPrimaryDisplay();\nconst backend = 'auto';\nconst window = new BrowserWindow({\n  x: 0,\n  y: 0,\n  width: 1,\n  height: 1,\n  frame: false,\n  transparent: true,\n  backgroundColor: '#00000000',\n  focusable: false,\n  show: false,\n  webPreferences: { preload: overlayPreloadPath }\n});\n\nconst overlay = configure(window, {\n  backend,\n  bounds: displayToOverlayRect(display, window, backend),\n  parent: { title: 'Elite - Dangerous', match: 'contains' },\n  position: 'bounds',\n  clickThrough: true,\n  alwaysOnTop: true,\n  preserveCompositing: true\n});\n\nawait window.loadURL(overlayUrl);\noverlay.reapply();\nwindow.showInactive();\noverlay.reapply();\n\nwindow.on('closed', () => overlay.close());\n```\n\nPassing the `BrowserWindow` lets `auto` select `wayland-electron` in a native Wayland session. The legacy buffer form remains supported for native backends:\n\n```js\nconst overlay = configure(window.getNativeWindowHandle(), {\n  bounds: displayToNativeRect(display),\n  position: 'bounds'\n});\n```\n\nBuffer targets always select the platform addon in `auto` mode for backward compatibility. If the application passes a `BrowserWindow` and forces X11 with `app.commandLine.appendSwitch('ozone-platform', 'x11')`, use `backend: 'x11'` because appended Electron switches are not visible through Node's `process.argv`.\n\n`getBackendSelection(window, backend)` reports the selected backend, whether the result is certain or inferred, and the command-line or environment evidence used. Session environment detection remains an inference; applications that explicitly choose Electron's Ozone platform should pass the matching backend.\n\nFor one-time parent sizing on a backend that reports `externalParent`, configure with `position: 'parent'`. If the target is not running yet, attach it later without moving the overlay:\n\n```js\noverlay.attachParent(\n  { title: 'Elite - Dangerous', match: 'contains' },\n  { reposition: false }\n);\n```\n\n`attachParent()` returns `null` when no mapped matching client exists. Matching defaults to case-insensitive `contains`; active matches win, followed by the topmost matching client.\n\nOn `wayland-electron`, `position: 'parent'` is rejected, `attachParent()` returns `null`, and `useParentBounds()` returns `false`. A parent query cannot identify an arbitrary external Wayland surface without compositor cooperation.\n\n## Capabilities\n\n```ts\nconst capabilities = overlay.getCapabilities();\n```\n\nThe result reports:\n\n```ts\ninterface OverlayCapabilities {\n  backend:\n    | 'win32'\n    | 'macos'\n    | 'x11'\n    | 'wayland-electron';\n  clickThrough: boolean;\n  aboveFullscreen: boolean;\n  externalParent: boolean;\n  parentDiscovery: boolean;\n  globalPositioning: boolean;\n  boundsCoordinateSpace: 'native-pixels' | 'electron-screen';\n}\n```\n\n`getCapabilities(window, backend)` can inspect a backend before creating an overlay. `displayToOverlayRect(display, window, backend)` returns bounds in the same backend and coordinate space that `configure(window, { backend })` will use. Wayland Electron bounds use Electron screen coordinates; their global `x` and `y` are advisory because the compositor controls top-level placement.\n\nThe compatibility backend reports `aboveFullscreen: false`, `externalParent: false`, `parentDiscovery: false`, and `globalPositioning: false`. It does not emulate X11's `WM_TRANSIENT_FOR`, restacking, or EWMH policy.\n\n## Experimental layer-shell surface\n\n`createLayerShellOverlay()` owns a new native Wayland surface. Bind a separately created offscreen `BrowserWindow` after the compositor has configured the output size. Enable shared textures to prefer direct Linux DMA-BUF import; paced `capturePage()` readback automatically feeds the `wl_shm` fallback when DMA-BUF is unavailable or rejected:\n\n```ts\nimport { BrowserWindow } from 'electron';\nimport {\n  createLayerShellOverlay,\n  getLayerShellCapabilities\n} from '@covas-labs/electron-overlay';\n\nconsole.log(getLayerShellCapabilities());\n\nconst overlay = await createLayerShellOverlay({\n  placement: {\n    type: 'output',\n    output: 'DP-1',\n    anchor: 'fill'\n  },\n  namespace: 'my-overlay',\n  initializationTimeoutMs: 5000\n});\n\nconst window = new BrowserWindow({\n  width: overlay.getState().width,\n  height: overlay.getState().height,\n  show: false,\n  transparent: true,\n  webPreferences: {\n    offscreen: {\n      useSharedTexture: true,\n      deviceScaleFactor: 1\n    }\n  }\n});\n\noverlay.attachOffscreenWindow(window);\nawait window.loadURL(overlayUrl);\n\nconsole.log(overlay.getState());\noverlay.close();\nwindow.destroy();\n```\n\nThe surface uses the overlay layer, exclusive zone `-1`, keyboard interactivity `none`, and an empty input region. The preferred path consumes Electron shared-texture metadata from `paint`, duplicates its DMA-BUF descriptor, negotiates the exact DRM format/modifier advertised by `zwp_linux_dmabuf_v1`, and imports it as a transient `wl_buffer`. The Electron texture remains leased until that buffer is released, dropped, rejected, or closed. Only `rgba` and `bgra` single-plane textures are currently imported.\n\nThe fallback path copies complete premultiplied BGRA frames into double-buffered `WL_SHM_FORMAT_ARGB8888` storage. If shared-texture rendering does not provide a bitmap, capture readback is paced and coalesced before SHM submission. `attachOffscreenWindow()` sizes the renderer to the compositor configuration, requests an initial frame, follows later size changes, removes listeners on close or rebind, and closes the layer surface if the renderer is destroyed. The native thread retains only the newest uncommitted frame for either transport. The controller never destroys the caller's BrowserWindow.\n\n`overlay.getState()` reports the most recently committed `bufferBackend`, DMA-BUF advertisement and usability, negotiated protocol versions, submitted DMA-BUF frames, import failures, and the latest nonfatal import failure. Successful SHM fallback is not reported as a terminal overlay error.\n\nThe API fails explicitly on non-Linux systems, when the Linux layer-shell binary is unavailable, when the compositor does not advertise `zwlr_layer_shell_v1`, or when the required output name is absent. Initialization defaults to a five-second deadline. Use `wayland-electron` as the application-level fallback.\n\nLayer-shell controller methods:\n\n```ts\nattachOffscreenWindow(window): void\ngetState(): LayerShellOverlayState\ngetCapabilities(): LayerShellCapabilities\nclose(): void\n```\n\n## Controller API\n\n```ts\nattachParent(query, { reposition?: false }): ParentInfo | null\ndetachParent(): void\nsetBounds(nativePixelBounds): void\nuseParentBounds(): boolean\nsetClickThrough(enabled): void\nsetAlwaysOnTop(enabled): void\nreapply(): void\ngetState(): OverlayState\ngetCapabilities(): OverlayCapabilities\nclose(): void\n```\n\nOn Linux, the addon sets `WM_TRANSIENT_FOR`, utility/state/focus hints, and an empty XFixes input region. On Windows it uses an owned tool window with no-activate, transparent hit testing, and topmost placement. On macOS it uses `NSWindow` mouse ignoring, levels, spaces behavior, and Core Graphics discovery.\n\nmacOS does not expose a supported cross-process transient-owner relationship. `attachParent()` therefore records the matching window and can adopt its geometry, while `alwaysOnTop` supplies stacking. Window-title discovery may require Screen Recording permission on recent macOS versions.\n","readmeFilename":"README.md"}