{"id":49538397,"url":"https://github.com/osmn-byhn/widget-core-linux","last_synced_at":"2026-05-02T13:04:34.910Z","repository":{"id":347492333,"uuid":"1194240223","full_name":"osmn-byhn/widget-core-linux","owner":"osmn-byhn","description":"WidgetCore is a high-performance, cross-platform library built with Node.js and C++ for creating interactive and persistent desktop widgets. It leverages native OS webview engines (WebView2 on Windows, WKWebView on macOS, and WebKitGTK on Linux) to provide a seamless, lightweight, and hardware-accelerated widget experience.","archived":false,"fork":false,"pushed_at":"2026-04-07T23:21:25.000Z","size":5176,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-08T00:18:33.144Z","etag":null,"topics":["bridge","core","desktop-widget","library","linux","macos","native","project-completed","widget","windows"],"latest_commit_sha":null,"homepage":"https://widget-core.osmanbeyhan.com/","language":"Makefile","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/osmn-byhn.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-28T04:50:59.000Z","updated_at":"2026-04-07T23:21:29.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/osmn-byhn/widget-core-linux","commit_stats":null,"previous_names":["osmn-byhn/widget-core","osmn-byhn/widget-core-linux"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/osmn-byhn/widget-core-linux","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/osmn-byhn%2Fwidget-core-linux","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/osmn-byhn%2Fwidget-core-linux/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/osmn-byhn%2Fwidget-core-linux/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/osmn-byhn%2Fwidget-core-linux/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/osmn-byhn","download_url":"https://codeload.github.com/osmn-byhn/widget-core-linux/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/osmn-byhn%2Fwidget-core-linux/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32534975,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-02T12:25:33.646Z","status":"ssl_error","status_checked_at":"2026-05-02T12:24:51.733Z","response_time":132,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bridge","core","desktop-widget","library","linux","macos","native","project-completed","widget","windows"],"created_at":"2026-05-02T13:04:26.999Z","updated_at":"2026-05-02T13:04:34.903Z","avatar_url":"https://github.com/osmn-byhn.png","language":"Makefile","funding_links":[],"categories":[],"sub_categories":[],"readme":"# WidgetCore-Linux 🐧\n\n**@osmn-byhn/widget-core-linux** is a high-performance, Linux-native library designed for developers who want to create beautiful, interactive, and persistent desktop widgets without the overhead of heavy frameworks. \n\nBuilt with **Node.js** and **C++**, it leverages **WebKitGTK** to provide a lightweight alternative to Electron, optimized specifically for the Linux desktop experience.\n\n---\n\n## 🏗️ Architecture: Hybrid Power\n\nWidgetCore uses a sophisticated hybrid model to ensure both developer productivity and runtime efficiency.\n\n```mermaid\ngraph TD\n    A[Node.js Runtime] --\u003e B[DesktopWidget API]\n    B --\u003e C[WidgetRegistry (Persistence)]\n    B --\u003e D[AutostartManager (Systemd/XDG)]\n    B --\u003e E[Native C++ Addon (N-API)]\n    E --\u003e F[GTK3 Windowing]\n    E --\u003e G[WebKitGTK Rendering]\n    F --\u003e H[Wayland (gtk-layer-shell)]\n    F --\u003e I[X11 (EWMH/Xlib)]\n```\n\n---\n\n## ⚡ Why WidgetCore-Linux?\n\nUnlike generic cross-platform frameworks, WidgetCore-Linux is built from the ground up for the Linux ecosystem.\n\n| Feature | WidgetCore-Linux | Electron |\n| :--- | :--- | :--- |\n| **Memory Footprint** | ~15MB - 30MB | 150MB+ |\n| **Windowing** | Native GTK Layers | Chromium Windowing |\n| **Wayland Support** | Native `gtk-layer-shell` | XWayland / Ozone |\n| **System Integration** | Linux-specific Autostart | Generic |\n| **Security** | Hardware-level Sandboxing | Software-level Isolation |\n\n---\n\n## ✨ Features at a Glance\n\n- **🚀 Performance First**: Direct access to GTK widgets and WebKit rendering without Chromium's overhead.\n- **🖼️ Aggressive Transparency**: Deep integration with window managers to ensure widgets blend perfectly with any wallpaper.\n- **🖇️ Universal Linux Support**: Binary compatibility for Wayland and X11 (including GNOME, KDE, LXQt, and Tiling WMs).\n- **🖱️ Flexible Interactivity**: Seamlessly toggle between \"Click-through\" passive mode and \"Interactive\" desktop utility mode.\n- **💾 Zero-Config Persistence**: Built-in registry that remembers your widgets' positions, sizes, and states across reboots.\n- **🔒 Security Shield**: A built-in security layer that sandboxes the widget's JS environment, blocking sensitive Node.js APIs by default.\n\n---\n\n## 🔒 Security Shield Architecture\n\nSecurity is non-negotiable for desktop widgets that might load external content. Our \"Security Shield\" provides:\n\n1. **Protocol Filtering**: Restricts content to `http:`, `https:`, or vetted `file:` paths.\n2. **Context Isolation**: Each widget runs its JS in a separate WebKit context.\n3. **Keyword Inspection**: Prevents execution of strings containing dangerous keywords like `require`, `process`, or `child_process`.\n4. **API Freezing**: Injects a protective script that locks down sensitive globals before the widget content loads.\n\n---\n\n## 🚀 Getting Started\n\n### Installation\n\n```bash\nnpm install @osmn-byhn/widget-core-linux\n```\n\n### Basic Usage: Remote Widget\n\n```typescript\nimport { DesktopWidget } from '@osmn-byhn/widget-core-linux';\n\n// Load a remote dashboard\nconst widget = new DesktopWidget('https://your-dashboard.com', {\n  width: 400,\n  height: 600,\n  x: 100,\n  y: 100,\n  opacity: 0.9,\n  interactive: true\n});\n\n// Ensure it starts when the system boots\nawait widget.makePersistent({ name: 'My Dashboard' });\n```\n\n### Advanced Usage: Local HTML with Blur\n\n```typescript\nconst clockHTML = `\n  \u003cdiv style=\"font-size: 50px; color: white; filter: drop-shadow(0 0 10px blue);\"\u003eTime: \u003cspan id=\"t\"\u003e\u003c/span\u003e\u003c/div\u003e\n  \u003cscript\u003e\n    setInterval(() =\u003e document.getElementById('t').innerText = new Date().toLocaleTimeString(), 1000);\n  \u003c/script\u003e\n`;\n\nconst clock = new DesktopWidget(\"\", {\n  html: clockHTML,\n  width: 400,\n  height: 200,\n  x: 800,\n  y: 10,\n  blur: true, // Enable backdrop-blur via WebKit\n  scroll: false\n});\n```\n\n---\n\n## 🛠️ API Documentation\n\n### `DesktopWidget(url, options)`\n\n| Option | Type | Default | Description |\n| :--- | :--- | :--- | :--- |\n| `width` | `number` | **Required** | Window width. |\n| `height` | `number` | **Required** | Window height. |\n| `x` | `number` | **Required** | Initial X position. |\n| `y` | `number` | **Required** | Initial Y position. |\n| `opacity` | `number` | `1.0` | Global widget transparency (0-1). |\n| `blur` | `boolean` | `false` | Apply CSS backdrop-blur to the window. |\n| `sticky` | `boolean` | `true` | Pin to desktop (always below other windows). |\n| `interactive` | `boolean` | `true` | Allow clicks/scrolls. |\n| `scroll` | `boolean` | `true` | Show/hide scrollbars. |\n| `permissions` | `string[]` | `[]` | List of allowed system capabilities. |\n\n---\n\n## 🐧 Distribution \u0026 Environment\n\nWidgetCore-Linux handles the complexity of Linux desktop protocols automatically.\n\n- **Wayland Support**: Uses `gtk-layer-shell` to anchor widgets to the desktop background layer.\n- **X11 Support**: Manages `_NET_WM_STATE_BELOW` atoms and sends periodic heartbeats to ensure the window stays at the bottom of the stack.\n- **Autostart**: Implements XDG Autostart specification by generating `.desktop` files in `~/.config/autostart/`.\n\n### System Requirements\n\nEnsure you have the following development libraries installed:\n\n- **Debian/Ubuntu**: `libwebkit2gtk-4.0-dev`, `libgtk-3-dev`, `libgtk-layer-shell-dev`\n- **Arch**: `webkit2gtk`, `gtk3`, `gtk-layer-shell`\n- **Fedora**: `webkit2gtk4.0-devel`, `gtk3-devel`, `gtk-layer-shell-devel`\n\n---\n\n## 🧪 Development \u0026 Testing\n\nWe use **Vitest** for unit testing and **Xvfb** for headless GUI verification.\n\n```bash\n# Install and build\nnpm install\nnpm run build\n\n# Run tests\nnpm test\n\n# Headless GUI test (requires xvfb)\nxvfb-run -a node test_cyberpunk.js\n```\n\n---\n\n## 📝 License \u0026 Authors\n\n**MIT License.** Copyright (c) 2026 **Osman Beyhan**.\n\nSpecial thanks to the [Web Widgets Community](https://github.com/web-widgets-community) for inspiring the widget engine.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fosmn-byhn%2Fwidget-core-linux","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fosmn-byhn%2Fwidget-core-linux","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fosmn-byhn%2Fwidget-core-linux/lists"}