From f99d9d9ff7e30222127677b8dd9e2f798770f73a Mon Sep 17 00:00:00 2001 From: Akhilesh Thite Date: Wed, 7 May 2025 10:10:23 +0530 Subject: [PATCH 1/2] docs: add browser://theme protocol, and syntax highlighting to theming.md --- docs/theming.md | 107 ++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 104 insertions(+), 3 deletions(-) diff --git a/docs/theming.md b/docs/theming.md index 6db6f8f..8ef1f60 100644 --- a/docs/theming.md +++ b/docs/theming.md @@ -51,11 +51,112 @@ You can replace the various values with any valid CSS values like Hex codes: `#F More styles will be added here as needed. If you feel we should standardize on some sort of style, feel free to open an issue talking about what it is and why it should be added. -### Highlight.js +## Syntax Highlighting Font -For convenience, Agregore bundles highlight.js and a default theme for it. +Agregore now uses a custom font for syntax highlighting in code blocks. The font file is located at `browser://theme/FontWithASyntaxHighlighter-Regular.woff2`. -You can load it up using `agregore://theme/highlight.js` and `agregore://theme/highlight.css`. +To use this font for `code` elements, you can include the following CSS in your stylesheet: + +```css +@font-face { + font-family: 'FontWithASyntaxHighlighter'; + src: url('browser://theme/FontWithASyntaxHighlighter-Regular.woff2') format('woff2'); +} + +code { + font-family: 'FontWithASyntaxHighlighter', monospace; +} +``` + +This font provides built-in syntax highlighting for code blocks, making it easier to read and understand code snippets. + +## 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 Agregore and other compatible browsers, such as [Peersky](https://peersky.p2plabs.xyz/). This protocol ensures consistent theming across different browsers by serving CSS files with a common set of variables based on the [Base16 theme framework](https://github.com/chriskempson/base16). It allows developers to build applications that adapt to the browser's theme without needing browser-specific code, making it suitable for any browser that implements the protocol. + +### Purpose + +The goal of the `browser://theme/` protocol is to: + +- Enable cross-browser compatibility for theming in any browser, including innovative browsers like Agregore and Peersky. +- Provide a unified set of theme variables using Base16 conventions, complementing Agregore’s existing `--ag-theme-*` variables. +- Allow web applications to import styles or variables without hardcoding browser-specific protocols (e.g., `agregore://` or `peersky://`). + +### Implementation + +#### Protocol Handler + +The `browser://theme/` protocol is implemented in Agregore via a custom Electron protocol handler (`theme-handler.js`). It serves CSS files from the `pages/theme/` directory when requests are made to URLs like `browser://theme/vars.css` or `browser://theme/style.css`. + +- **Location**: Files are stored in `pages/theme/` (e.g., `vars.css`, `style.css`). +- **URL Structure**: Requests to `browser://theme/` map to `pages/theme/`. +- **Example**: `browser://theme/vars.css` serves `pages/theme/vars.css`. + +#### Base16 Integration + +To ensure cross-browser compatibility, the theme protocol uses the Base16 theme framework, which defines 16 color variables (`--base00` to `--base0F`). These variables are declared in `vars.css` alongside Agregore’s existing theme variables. + +- **Variables**: `vars.css` defines: + - `--base00` to `--base07`: Core UI colors (backgrounds, text, etc.). + - `--base08` to `--base0F`: Accent colors for highlights or interactive elements. +- **Component Variables**: Agregore-specific variables (e.g., `--ag-theme-background`) are defined in terms of Base16 variables for consistency (e.g., `--ag-theme-background: var(--base00);`). Peersky-specific variables (e.g., `--peersky-background-color`) are also supported for cross-browser apps. + +### Cross-Browser Compatibility + +The `browser://theme/` protocol enables apps built for Peersky to work seamlessly in Agregore (and vice versa) by: + +1. **Standardized Protocol**: Both browsers implement `browser://theme/` to serve their theme CSS files. +2. **Base16 Variables**: Apps can use Base16 variables (e.g., `--base00`) directly or map browser-specific variables (e.g., `--peersky-background-color`) to Base16 variables. For example: + - In Peersky: `--peersky-background-color: var(--base00);` + - In Agregore: `--base00: #111111;` + - Result: A Peersky app using `--peersky-background-color` renders with Agregore’s `--base00` color (`#111111`). +3. **Fallbacks**: Apps can import `browser://theme/vars.css` to ensure all Base16 and browser-specific variables are available. + +This approach ensures that apps adapt to the host browser’s theme without requiring separate stylesheets for each browser. + +### Usage + +In addition to Agregore’s existing `--ag-theme-*` variables, developers can use Base16 variables for broader compatibility. Examples: + +- **Import Variables with Base16**: + ```html + + ``` + +- **Use Peersky Variables in Agregore**: + ```html + + ``` + +### Available Files + +- `browser://theme/vars.css`: Defines Base16 variables (`--base00` to `--base0F`), Agregore-specific variables (e.g., `--ag-theme-background`), and Peersky-specific variables for compatibility. +- `browser://theme/style.css`: Provides default styles for web apps, importing `vars.css` and applying Base16 and Agregore variables. +- `browser://theme/FontWithASyntaxHighlighter-Regular.woff2`: Custom font for syntax highlighting (see Syntax Highlighting Font section). + +### Customization + +Agregore’s theme variables can still be customized via the `.agregorerc` file, as described above. To align with Base16, you can specify colors that match the Base16 palette (e.g., setting `"background": "#111111"` to match `--base00`). + +### Development Guidelines + +- **Use Base16 Variables**: Prefer Base16 variables (e.g., `--base00`) for new styles to ensure cross-browser compatibility. +- **Add New Files**: Place additional CSS files in `pages/theme/` to make them accessible via `browser://theme/`. +- **Test Cross-Browser**: Verify apps work in both Agregore and Peersky, checking that variables like `--peersky-background-color` render correctly. +- **Update Documentation**: Modify this file if new theme files or variables are added. --- From d67bf0a272a34a68b5e3877c4c721e7ea9d948c6 Mon Sep 17 00:00:00 2001 From: Akhilesh Thite Date: Mon, 12 May 2025 07:43:27 +0530 Subject: [PATCH 2/2] docs: update theming.md for Peersky and Agregore vars.css usage --- docs/theming.md | 123 +++++++++++++++++++++++------------------------- 1 file changed, 59 insertions(+), 64 deletions(-) diff --git a/docs/theming.md b/docs/theming.md index 8ef1f60..d332e2c 100644 --- a/docs/theming.md +++ b/docs/theming.md @@ -5,20 +5,20 @@ Agregore provides CSS variables for themeing the browser at the URL `agregore:// The contents of this look something like: ```css - :root { - --ag-color-purple: #6e2de5; - --ag-color-black: #111; - --ag-color-white: #F2F2F2; - --ag-color-green: #2de56e; - } +:root { + --ag-color-purple: #6e2de5; + --ag-color-black: #111; + --ag-color-white: #f2f2f2; + --ag-color-green: #2de56e; +} - :root { - --ag-theme-font-family: system-ui; - --ag-theme-background: var(--ag-color-black); - --ag-theme-text: var(--ag-color-white); - --ag-theme-primary: var(--ag-color-purple); - --ag-theme-secondary: var(--ag-color-green); - } +:root { + --ag-theme-font-family: system-ui; + --ag-theme-background: var(--ag-color-black); + --ag-theme-text: var(--ag-color-white); + --ag-theme-primary: var(--ag-color-purple); + --ag-theme-secondary: var(--ag-color-green); +} ``` These can be imported anywhere you'd like to use browser styling. @@ -59,12 +59,12 @@ To use this font for `code` elements, you can include the following CSS in your ```css @font-face { - font-family: 'FontWithASyntaxHighlighter'; - src: url('browser://theme/FontWithASyntaxHighlighter-Regular.woff2') format('woff2'); + font-family: "FontWithASyntaxHighlighter"; + src: url("browser://theme/FontWithASyntaxHighlighter-Regular.woff2") format("woff2"); } code { - font-family: 'FontWithASyntaxHighlighter', monospace; + font-family: "FontWithASyntaxHighlighter", monospace; } ``` @@ -74,90 +74,85 @@ This font provides built-in syntax highlighting for code blocks, making it easie ### Overview -The `browser://theme/` protocol provides a standardized way for web applications to access browser-level CSS styles and theme variables in Agregore and other compatible browsers, such as [Peersky](https://peersky.p2plabs.xyz/). This protocol ensures consistent theming across different browsers by serving CSS files with a common set of variables based on the [Base16 theme framework](https://github.com/chriskempson/base16). It allows developers to build applications that adapt to the browser's theme without needing browser-specific code, making it suitable for any browser that implements the protocol. +The `browser://theme/` protocol provides a standardized way for web applications to access browser-level CSS styles and theme variables in Agregore and other compatible browsers, such as [Peersky](https://peersky.p2plabs.xyz/). 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, making it suitable for any browser that implements the protocol. -### Purpose +## Purpose The goal of the `browser://theme/` protocol is to: -- Enable cross-browser compatibility for theming in any browser, including innovative browsers like Agregore and Peersky. -- Provide a unified set of theme variables using Base16 conventions, complementing Agregore’s existing `--ag-theme-*` variables. -- Allow web applications to import styles or variables without hardcoding browser-specific protocols (e.g., `agregore://` or `peersky://`). +- 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 -### Implementation +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/base.css`. -#### Protocol Handler +- **Location**: Files are stored in `src/pages/theme/` (e.g., `vars.css`, `base.css`, `index.css`). +- **URL Structure**: Requests to `browser://theme/` map to `src/pages/theme/`. +- **Example**: `browser://theme/vars.css` serves `src/pages/theme/vars.css`. -The `browser://theme/` protocol is implemented in Agregore via a custom Electron protocol handler (`theme-handler.js`). It serves CSS files from the `pages/theme/` directory when requests are made to URLs like `browser://theme/vars.css` or `browser://theme/style.css`. +### Theme Variable Standardization -- **Location**: Files are stored in `pages/theme/` (e.g., `vars.css`, `style.css`). -- **URL Structure**: Requests to `browser://theme/` map to `pages/theme/`. -- **Example**: `browser://theme/vars.css` serves `pages/theme/vars.css`. +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. -#### Base16 Integration +Each browser implements these standardized variables by mapping them to their internal theme variables. For example: -To ensure cross-browser compatibility, the theme protocol uses the Base16 theme framework, which defines 16 color variables (`--base00` to `--base0F`). These variables are declared in `vars.css` alongside Agregore’s existing theme variables. +- 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. -- **Variables**: `vars.css` defines: - - `--base00` to `--base07`: Core UI colors (backgrounds, text, etc.). - - `--base08` to `--base0F`: Accent colors for highlights or interactive elements. -- **Component Variables**: Agregore-specific variables (e.g., `--ag-theme-background`) are defined in terms of Base16 variables for consistency (e.g., `--ag-theme-background: var(--base00);`). Peersky-specific variables (e.g., `--peersky-background-color`) are also supported for cross-browser apps. +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 Peersky to work seamlessly in Agregore (and vice versa) by: +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. -1. **Standardized Protocol**: Both browsers implement `browser://theme/` to serve their theme CSS files. -2. **Base16 Variables**: Apps can use Base16 variables (e.g., `--base00`) directly or map browser-specific variables (e.g., `--peersky-background-color`) to Base16 variables. For example: - - In Peersky: `--peersky-background-color: var(--base00);` - - In Agregore: `--base00: #111111;` - - Result: A Peersky app using `--peersky-background-color` renders with Agregore’s `--base00` color (`#111111`). -3. **Fallbacks**: Apps can import `browser://theme/vars.css` to ensure all Base16 and browser-specific variables are available. +For example: -This approach ensures that apps adapt to the host browser’s theme without requiring separate stylesheets for each browser. +- 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. -### Usage +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). -In addition to Agregore’s existing `--ag-theme-*` variables, developers can use Base16 variables for broader compatibility. Examples: +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 ` ``` +- **Import Default Styles**: + + ```html + + ``` + - **Use Peersky Variables in Agregore**: ```html ``` -### Available Files - -- `browser://theme/vars.css`: Defines Base16 variables (`--base00` to `--base0F`), Agregore-specific variables (e.g., `--ag-theme-background`), and Peersky-specific variables for compatibility. -- `browser://theme/style.css`: Provides default styles for web apps, importing `vars.css` and applying Base16 and Agregore variables. -- `browser://theme/FontWithASyntaxHighlighter-Regular.woff2`: Custom font for syntax highlighting (see Syntax Highlighting Font section). - -### Customization - -Agregore’s theme variables can still be customized via the `.agregorerc` file, as described above. To align with Base16, you can specify colors that match the Base16 palette (e.g., setting `"background": "#111111"` to match `--base00`). - -### Development Guidelines - -- **Use Base16 Variables**: Prefer Base16 variables (e.g., `--base00`) for new styles to ensure cross-browser compatibility. -- **Add New Files**: Place additional CSS files in `pages/theme/` to make them accessible via `browser://theme/`. -- **Test Cross-Browser**: Verify apps work in both Agregore and Peersky, checking that variables like `--peersky-background-color` render correctly. -- **Update Documentation**: Modify this file if new theme files or variables are added. - --- [Back](/)