Merge pull request #43 from p2plabsxyz/theme-protocol

feat(theme-handler): implement browser://theme protocol handler

Author: akhileshthite

README.md

@@ -24,10 +24,11 @@
   - [x] Reload
   - [x] Browser protocol (peersky://)
   - [x] Home page (peersky://home)
+  - [x] Cross browser themeing ([browser://theme/](https://github.com/p2plabsxyz/peersky-browser/blob/main/docs/Theme.md))
   - [x] Search engine
     - DuckDuckGo (default)
     - Ecosia
-  - [ ] [Tabs?](https://github.com/p2plabsxyz/peersky-browser/issues/11)
+  - [ ] [Tabs](https://github.com/p2plabsxyz/peersky-browser/issues/11)
 
 - [x] IPFS protocol handler:
 
@@ -104,7 +105,7 @@
   - [ ] Change themes
   - [ ] Clear browser cache
 
-- [ ] Web extensions:
+- [ ] [Web extensions](https://github.com/p2plabsxyz/peersky-browser/issues/19):
   - [ ] Ability to add and manage extensions
   - [ ] Default extensions
     - [Ad-blocker](https://github.com/gorhill/uBlock)

docs/README.md

@@ -0,0 +1,3 @@
+# Peersky Browser Documentation
+
+- [Theme Protocol](Theme.md)

docs/Theme.md

@@ -0,0 +1,93 @@
+# Theme Protocol (`browser://theme/`)
+
+## Overview
+
+The `browser://theme/` protocol provides a standardized way for web applications to access browser-level CSS styles and theme variables in [Peersky](https://peersky.p2plabs.xyz/) and other compatible browsers, such as [Agregore](https://agregore.mauve.moe/). This protocol ensures consistent theming across different browsers by serving CSS files with a common set of variables. It allows developers to build applications that adapt to the browser's theme without needing browser-specific code.
+
+![DWeb Scratchpad in Peersky and Agregore](./images/browser-theme-protocol-example.png)
+
+## Purpose
+
+The goal of the `browser://theme/` protocol is to:
+
+- Enable cross-browser compatibility for theming in any browser, including p2p browsers like Peersky and Agregore.
+- Provide a unified set of theme variables using standardized `--browser-theme-` prefixes.
+- Allow web applications to import styles or variables without hardcoding browser-specific protocols (e.g., `peersky://` or `agregore://`).
+
+## Implementation
+
+### Protocol Handler
+
+The `browser://theme/` protocol is implemented in Peersky via a custom Electron protocol handler (`theme-handler.js`). It serves CSS files from the `src/pages/theme/` directory when requests are made to URLs like `browser://theme/vars.css` or `browser://theme/style.css`.
+
+- **Location**: Files are stored in `src/pages/theme/` (e.g., `vars.css`, `style.css`, `base.css`, `index.css`).
+- **URL Structure**: Requests to `browser://theme/<filename>` map to `src/pages/theme/<filename>`.
+- **Example**: `browser://theme/vars.css` serves `src/pages/theme/vars.css`.
+
+### Theme Variable Standardization
+
+The `browser://theme/` protocol provides standardized theme variables prefixed with `--browser-theme-`, such as `--browser-theme-font-family`, `--browser-theme-background`, `--browser-theme-text-color`, `--browser-theme-primary-highlight`, and `--browser-theme-secondary-highlight`. These variables allow web applications to adapt to the host browser's theme without needing browser-specific code.
+
+Each browser implements these standardized variables by mapping them to their internal theme variables. For example:
+
+- In Peersky, `--browser-theme-background` is mapped to `--base01`, which is part of the Base16 color palette [Base16 Framework](https://github.com/chriskempson/base16).
+- In Agregore, `--browser-theme-background` is mapped to `--ag-theme-background`, which is defined in Agregore's theme configuration.
+
+This ensures that applications built for one browser can work seamlessly in another, as long as they use the standardized `--browser-theme-` variables.
+
+### Cross-Browser Compatibility
+
+The `browser://theme/` protocol enables apps built for one browser to work seamlessly in another by providing standardized theme variables prefixed with `--browser-theme-`. These variables are mapped to each browser's internal theme variables, ensuring consistent theming across different browsers.
+
+For example:
+
+- In Peersky, `--browser-theme-background` is mapped to `--base01`, which is part of the Base16 color palette.
+- In Agregore, `--browser-theme-background` is mapped to `--ag-theme-background`, which is defined in Agregore's theme configuration.
+
+As a result, an app using `--browser-theme-background` will render with the appropriate background color for each browser, whether it's based on Base16 (as in Peersky) or another theme system (as in Agregore).
+
+Additionally, apps can use the full set of variables provided by each browser for more advanced theming, but for cross-browser compatibility, it's recommended to use the standardized `--browser-theme-` variables.
+
+## Usage
+
+### Importing Theme Styles
+
+Web applications can import theme styles or variables using `<style>` tags or `<link>` elements. Examples:
+
+- **Import Variables**:
+
+  ```html
+  <style>
+    @import url("browser://theme/vars.css");
+    body {
+      background-color: var(--browser-theme-background);
+      color: var(--browser-theme-text-color);
+    }
+  </style>
+  ```
+
+- **Import Default Styles**:
+
+  ```html
+  <link rel="stylesheet" href="browser://theme/style.css" />
+  ```
+
+- **Use Browser-Specific Variables** (for Agregore apps in Peersky):
+  ```html
+  <style>
+    @import url("browser://theme/vars.css");
+    body {
+      background-color: var(
+        --ag-theme-background
+      ); /* Maps to --browser-theme-background */
+    }
+  </style>
+  ```
+
+## Theme Files (`browser://theme/`)
+
+- `vars.css`: Defines standardized `--browser-theme-`, Base16, and Peersky-specific CSS variables for theming.
+- `base.css`: Applies minimal default styles for unstyled pages, auto-injected by preload.
+- `style.css`: Opt-in comprehensive styling for web apps
+- `index.css`: Styles Peersky’s browser UI (e.g., navigation bar, URL input).
+- `home.css`: Styles Peersky’s home page with a background image and sidebar.

docs/images/browser-theme-protocol-example.png

@@ -1,6 +1,6 @@
 {
   "name": "peersky-browser",
-  "version": "1.0.0-beta.3",
+  "version": "1.0.0-beta.4",
   "description": "A minimal local-first p2p web browser: access, communicate, and publish offline.",
   "keywords": [
     "peersky",
@@ -152,6 +152,7 @@
     "mime-types": "^2.1.35",
     "multiformats": "^13.3.2",
     "node-cache": "^5.1.2",
+    "scoped-fs": "^1.4.1",
     "web3protocol": "^0.6.0"
   },
   "devDependencies": {

package-lock.json

@@ -1,6 +1,7 @@
 import { app, session, protocol as globalProtocol } from "electron";
+import { createHandler as createBrowserHandler } from "./protocols/peersky-protocol.js";
+import { createHandler as createBrowserThemeHandler } from "./protocols/theme-handler.js";
 import { createHandler as createIPFSHandler } from "./protocols/ipfs-handler.js";
-import { createHandler as createBrowserHandler } from "./protocols/browser-protocol.js";
 import { createHandler as createHyperHandler } from "./protocols/hyper-handler.js";
 import { createHandler as createWeb3Handler } from "./protocols/web3-handler.js";
 import { ipfsOptions, hyperOptions } from "./protocols/config.js";
@@ -31,12 +32,13 @@ const BROWSER_PROTOCOL = {
 let windowManager;
 
 globalProtocol.registerSchemesAsPrivileged([
+  { scheme: "peersky", privileges: BROWSER_PROTOCOL },
+  { scheme: "browser", privileges: BROWSER_PROTOCOL },
   { scheme: "ipfs", privileges: P2P_PROTOCOL },
   { scheme: "ipns", privileges: P2P_PROTOCOL },
   { scheme: "pubsub", privileges: P2P_PROTOCOL },
   { scheme: "hyper", privileges: P2P_PROTOCOL },
   { scheme: "web3", privileges: P2P_PROTOCOL },
-  { scheme: "peersky", privileges: BROWSER_PROTOCOL },
 ]);
 
 app.whenReady().then(async () => {
@@ -93,11 +95,18 @@ app.on("before-quit", (event) => {
 async function setupProtocols(session) {
   const { protocol: sessionProtocol } = session;
 
+  app.setAsDefaultProtocolClient("peersky");
+  app.setAsDefaultProtocolClient("browser");
   app.setAsDefaultProtocolClient("ipfs");
   app.setAsDefaultProtocolClient("ipns");
   app.setAsDefaultProtocolClient("hyper");
   app.setAsDefaultProtocolClient("web3");
-  app.setAsDefaultProtocolClient("peersky");
+
+  const browserProtocolHandler = await createBrowserHandler();
+  sessionProtocol.registerStreamProtocol("peersky", browserProtocolHandler, BROWSER_PROTOCOL);
+
+  const browserThemeHandler = await createBrowserThemeHandler();
+  sessionProtocol.registerStreamProtocol("browser", browserThemeHandler, BROWSER_PROTOCOL);
 
   const ipfsProtocolHandler = await createIPFSHandler(ipfsOptions, session);
   sessionProtocol.registerStreamProtocol("ipfs", ipfsProtocolHandler, P2P_PROTOCOL);
@@ -109,9 +118,6 @@ async function setupProtocols(session) {
 
   const web3ProtocolHandler = await createWeb3Handler();
   sessionProtocol.registerStreamProtocol("web3", web3ProtocolHandler, P2P_PROTOCOL);
-
-  const browserProtocolHandler = await createBrowserHandler();
-  sessionProtocol.registerStreamProtocol("peersky", browserProtocolHandler, BROWSER_PROTOCOL);
 }
 
 app.on("window-all-closed", () => {

package.json

@@ -3,4 +3,13 @@
 <meta http-equiv="X-UA-Compatible" content="IE=edge" />
 <meta name="viewport" content="width=device-width, initial-scale=1.0" />
 <title>Peersky Browser | 404</title>
+<style>
+  @import url("browser://theme/vars.css");
+
+  body {
+    background-color: var(--browser-theme-background);
+    color: var(--browser-theme-text-color);
+    text-align: center;
+  }
+</style>
 <p>404 Page not found!</p>

src/main.js

@@ -3,8 +3,8 @@
 <meta http-equiv="X-UA-Compatible" content="IE=edge" />
 <meta name="viewport" content="width=device-width, initial-scale=1.0" />
 <style>
-  @import url("peersky://static/css/home.css");
-  @import url("peersky://static/css/index.css");
+  @import url("browser://theme/home.css");
+  @import url("browser://theme/index.css");
 </style>
 <title>Home</title>
 <div class="home-background">

src/pages/404.html

@@ -3,7 +3,7 @@
 <meta http-equiv="X-UA-Compatible" content="IE=edge" />
 <meta name="viewport" content="width=device-width, initial-scale=1.0" />
 <style>
-  @import url("peersky://static/css/index.css");
+  @import url("browser://theme/index.css");
 </style>
 <title>Peersky Browser</title>
 <nav-box id="navbox"></nav-box>