chore: add server-side highlighting mode with highlight.php, update docs and build process

Add highlight.php dependency, new highlighting-mode setting (client/server), token class remapping for visual parity across both modes. Update build scripts to install production dependencies and exclude build-prism.min.js. Remove composer.lock from .gitignore. Update AGENTS.md, CLAUDE.md, README.md with server-mode details.

Author: ajaydsouza

.github/workflows/zipitup.yml

@@ -27,7 +27,7 @@ jobs:
         uses: actions/checkout@v6
 
       - name: Create artifact
-        run: composer zip build-prism.js
+        run: composer zip
       - name: Upload to release
         uses: softprops/action-gh-release@v2
         with:

AGENTS.md

@@ -1,6 +1,10 @@
 # AGENTS.md
 
-WordPress plugin extending the native Gutenberg `core/code` block with Prism.js syntax highlighting via JS block filters and a `render_block_core/code` PHP filter. Does not replace the block — existing posts stay valid.
+WordPress plugin extending the native Gutenberg `core/code` block with syntax highlighting via JS block filters and a `render_block_core/code` PHP filter. Does not replace the block — existing posts stay valid.
+
+Two highlighting modes:
+- **Client-side** (default): Prism.js runs in the browser. Loads the Prism JS bundle + theme CSS.
+- **Server-side**: highlight.php pre-renders token spans on the server. No JS loaded. Uses the same Prism theme CSS — token class remapping (`remap_token_classes()` in `class-blocks.php`) converts hljs-* span classes to Prism `token *` classes via `strtr`, giving exact visual parity across all 21 themes.
 
 ## Commands
 

CLAUDE.md

@@ -4,7 +4,11 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 ## Plugin Overview
 
-**WebberZone Code Block Highlighting** (plugin slug: `webberzone-code-block-highlighting`) extends the native Gutenberg `core/code` block with Prism.js syntax highlighting via JS block filters and a `render_block_core/code` PHP filter. Does not replace the block — existing posts stay valid. Namespace: `WebberZone\Code_Block_Highlighting`. Requires WordPress 6.6+, PHP 7.4+. No Freemius.
+**WebberZone Code Block Highlighting** (plugin slug: `webberzone-code-block-highlighting`) extends the native Gutenberg `core/code` block with syntax highlighting via JS block filters and a `render_block_core/code` PHP filter. Does not replace the block — existing posts stay valid. Namespace: `WebberZone\Code_Block_Highlighting`. Requires WordPress 6.6+, PHP 7.4+. No Freemius.
+
+Two highlighting modes:
+- **Client-side** (default): Prism.js runs in the browser. Loads the Prism JS bundle + theme CSS.
+- **Server-side**: highlight.php pre-renders token spans on the server. No JS loaded. Uses the same Prism theme CSS — token class remapping (`remap_token_classes()` in `class-blocks.php`) converts hljs-* span classes to Prism `token *` classes via `strtr`, giving exact visual parity across all 21 themes.
 
 WordPress.org: https://wordpress.org/plugins/webberzone-code-block-highlighting/
 webberzone.com: https://webberzone.com/plugins/webberzone-code-block-highlighting/
@@ -40,9 +44,9 @@ Bootstrap: `wzcbh()` singleton on `plugins_loaded` → instantiates `Frontend\Bl
 
 Key files:
 - `includes/class-main.php` — bootstrap and object wiring
-- `includes/frontend/class-blocks.php` — editor assets, REST route, `render_block_core/code`
-- `includes/frontend/class-styles-handler.php` — conditional Prism asset loading
-- `includes/admin/class-settings.php` — settings registration, theme resolution
+- `includes/frontend/class-blocks.php` — editor assets, REST route, `render_block_core/code` filter; `render_code_block_server()` for server mode; `remap_token_classes()` for hljs→Prism class mapping
+- `includes/frontend/class-styles-handler.php` — conditional asset loading for both modes: client (Prism JS + theme CSS) and server (theme CSS + `hljs-server-mode.css`, no JS)
+- `includes/admin/class-settings.php` — settings registration; `get_color_scheme_css()` always returns Prism CSS URL (no per-mode branch)
 - `includes/blocks/src/js/index.js` — block filter, Inspector Controls
 - `includes/blocks/src/js/frontend.js` — Prism grammars + plugins
 
@@ -64,9 +68,20 @@ Always `require` the generated `.asset.php` manifest before enqueueing block scr
 
 **If you change block attributes in JS**, update `render_code_block()` in `class-blocks.php` and the defaults flow as well.
 
+**Server-mode token remapping** — `remap_token_classes()` in `class-blocks.php` uses `strtr()` to convert every `class="hljs-*"` span emitted by highlight.php into the equivalent Prism `class="token *"` span. `strtr()` is safe here because highlight.php emits single-class spans only (no compound classes). Keys are ordered longest-first to prevent prefix collisions (e.g. `hljs-selector-tag` before a hypothetical `hljs-selector`).
+
+**highlight.php autoloader** — `\Highlight\Autoloader::register()` does not exist. Use `spl_autoload_register(static function(string $class_name): void { \Highlight\Autoloader::load($class_name); })`.
+
+**`hljs-server-mode.css`** — only handles `.wzcbh-highlighted-line` line highlighting. Font-size, line-numbers gutter, and word-wrap are all in `frontend.css` (webpack build), which loads in both modes.
+
+**Both modes use the same Prism theme CSS** — `Settings::get_color_scheme_css()` always returns the Prism CSS URL. There is no per-mode branch or hljs-specific theme mapping table.
+
 ## Asset loading
 
-Prism assets load only on pages containing at least one `core/code` block (`Styles_Handler::enqueue_assets()`). Use `wzcbh_force_load_assets` to override.
+Assets load only on pages containing at least one `core/code` block (`Styles_Handler::enqueue_assets()`). Use `wzcbh_force_load_assets` to override.
+
+- **Client mode**: `frontend.css` + Prism theme CSS + `wzcbh-prism-js` script bundle (includes all grammars and plugins)
+- **Server mode**: `frontend.css` + Prism theme CSS + `hljs-server-mode.css` (no JS; syntax already pre-rendered in HTML)
 
 ## Filters and routes
 

README.md

@@ -16,19 +16,29 @@ __License:__ [GPL-2.0+](http://www.gnu.org/licenses/gpl-2.0.html)
 
 __Plugin page:__ [WebberZone Code Block Highlighting](https://webberzone.com/plugins/webberzone-code-block-highlighting/) | [WordPress.org listing](https://wordpress.org/plugins/webberzone-code-block-highlighting/)
 
-Add beautiful syntax highlighting to the Gutenberg Code block — powered by Prism.js with 21 themes and 40 languages, zero configuration required.
+Syntax highlighting for the Gutenberg Code block — Prism.js, 21 themes, 40+ languages, plus an optional no-JavaScript server-side mode.
 
 ## Description
 
 __WebberZone Code Block Highlighting__ is the easiest way to add syntax highlighting to your WordPress site. It extends the native Gutenberg `core/code` block with [Prism.js](https://prismjs.com/) highlighting — no shortcodes, no block replacement, no risk of breaking existing posts.
 
-Simply activate the plugin and your code blocks will instantly display beautiful, readable syntax highlighting on the frontend. Choose from 35+ programming languages and 21 colour themes, all controlled from the block editor's Inspector Controls sidebar.
+Simply activate the plugin and your code blocks will instantly display beautiful, readable syntax highlighting on the frontend. Choose from 40+ programming languages and 21 colour themes, all controlled from the block editor's Inspector Controls sidebar.
+
+### Two highlighting modes
+
+Pick the rendering mode that best fits your site from the settings page:
+
+* __Client-side (default)__ — [Prism.js](https://prismjs.com/) highlights your code in the browser. Best for interactive features such as copy-to-clipboard and expand/collapse.
+* __Server-side (no JavaScript)__ — Code is pre-highlighted on the server with [highlight.php](https://github.com/scrivo/highlight.php), so no JavaScript is loaded on the frontend. Ideal for performance, Core Web Vitals, AMP-style setups, and strict content-security policies.
+
+Both modes use the same 21 Prism themes and produce visually identical output, so you can switch between client-side and server-side rendering at any time without changing how your code blocks look.
 
 ### Why use this plugin?
 
 * __Safe by design__ — Works as a filter on top of `core/code`. Existing posts are never invalidated. Deactivate the plugin and your blocks are still valid standard WordPress code blocks.
 * __Zero configuration__ — Activate and start writing. No setup wizard, no shortcodes.
-* __Smart asset loading__ — Prism CSS and JS only load on pages that actually contain code blocks. Pages without code stay fast.
+* __JavaScript-free option__ — Server-side highlighting renders syntax colours without loading any frontend JavaScript, keeping your pages lean and fast.
+* __Smart asset loading__ — Theme CSS (and, in client mode, Prism JS) only load on pages that actually contain code blocks. Pages without code stay fast.
 * __Per-block controls__ — Set language, theme, line numbers, word wrap, title, highlighted lines, and max height individually for each block.
 * __Developer-friendly__ — Filters to add languages, override themes, and force asset loading.
 
@@ -51,6 +61,7 @@ A11y Dark, Coldark Cold (Light), Coldark Dark, Dracula, Duotone Dark, Duotone Li
 
 ### Global settings
 
+* Highlighting mode — client-side (Prism.js) or server-side (highlight.php, no JavaScript)
 * Default colour scheme (theme)
 * Default language
 * Default line numbers toggle and start value
@@ -99,8 +110,11 @@ No. The plugin uses JavaScript and PHP filters to extend `core/code`. Deactivati
 __Which languages are supported?__
 40 out of the box. Use the `wzcbh_languages` filter to add or remove entries from the language picker — note the corresponding Prism.js grammar must also be available on the frontend.
 
+__What is the difference between client-side and server-side highlighting?__
+Client-side mode runs [Prism.js](https://prismjs.com/) in the browser and enables interactive toolbar features (copy-to-clipboard, expand/collapse). Server-side mode pre-renders the highlighted markup with [highlight.php](https://github.com/scrivo/highlight.php) so no JavaScript is loaded on the frontend — ideal for performance and strict content-security policies. Both modes share the same 21 themes and look identical, so you can switch freely from __Settings > Code Block Highlighting__.
+
 __Does Prism.js load on every page?__
-No. Assets are only enqueued on pages containing at least one code block. Use `wzcbh_force_load_assets` to override.
+No. Theme CSS and (in client-side mode) Prism JS are only enqueued on pages containing at least one code block. Use `wzcbh_force_load_assets` to override.
 
 __How do I highlight specific lines?__
 Enter a comma-separated list of lines or ranges in the __Highlight Lines__ field in the sidebar (e.g. `1,3-5,8`).

build-prism.min.js

@@ -42,6 +42,7 @@ package-lock.json
 phpstan-bootstrap.php
 build-zip.sh
 build-prism.js
+build-prism.min.js
 CODE_OF_CONDUCT.md
 CONTRIBUTING.md
 ISSUE_TEMPLATE.md
@@ -50,6 +51,13 @@ CLAUDE.md
 AGENTS.md
 EOF
 
+# Install production-only PHP dependencies into the build copy.
+# composer.json/lock are excluded from rsync, so copy them temporarily.
+echo "Installing production PHP dependencies..."
+cp composer.json composer.lock "$TEMP_DIR/"
+composer install --working-dir="$TEMP_DIR" --no-dev --quiet
+rm "$TEMP_DIR/composer.json" "$TEMP_DIR/composer.lock"
+
 # Create zip
 echo "Creating zip file..."
 cd "$BUILD_DIR"

build-zip.sh

@@ -1,7 +1,7 @@
 {
     "name": "webberzone/webberzone-code-block-highlighting",
     "description": "Extends the Gutenberg Code block with syntax highlighting powered by Prism.js.",
-    "version": "1.0.0",
+    "version": "1.2.0",
     "type": "wordpress-plugin",
     "keywords": [
         "code block",
@@ -19,7 +19,8 @@
         }
     ],
     "require": {
-        "php": ">=7.4"
+        "php": ">=7.4",
+        "scrivo/highlight.php": "^9.18"
     },
     "require-dev": {
         "szepeviktor/phpstan-wordpress": "^1",

composer.json

@@ -178,10 +178,21 @@ public static function get_settings_sections(): array {
 	public static function get_registered_settings(): array {
 		return array(
 			'general' => array(
+				array(
+					'id'      => 'highlighting-mode',
+					'name'    => __( 'Highlighting Mode', 'webberzone-code-block-highlighting' ),
+					'desc'    => __( 'Client-side: Prism.js runs in the browser (default, supports all block features). Server-side: highlight.php pre-renders syntax on the server — no JavaScript required.', 'webberzone-code-block-highlighting' ),
+					'type'    => 'radio',
+					'default' => 'client',
+					'options' => array(
+						'client' => __( 'Client-side (Prism.js)', 'webberzone-code-block-highlighting' ),
+						'server' => __( 'Server-side (highlight.php)', 'webberzone-code-block-highlighting' ),
+					),
+				),
 				array(
 					'id'      => 'color-scheme',
 					'name'    => __( 'Color Scheme', 'webberzone-code-block-highlighting' ),
-					'desc'    => __( 'Choose the syntax highlighting theme for all code blocks. This styling is applied only on the frontend and not in the block editor.', 'webberzone-code-block-highlighting' ),
+					'desc'    => __( 'Choose the syntax highlighting theme. The same Prism.js theme is used in both client-side and server-side modes.', 'webberzone-code-block-highlighting' ),
 					'type'    => 'select',
 					'default' => 'prism-onedark',
 					'options' => self::$color_schemes,
@@ -310,10 +321,8 @@ public function enqueue_language_data( string $hook ): void {
 	/**
 	 * Get the URL (or filesystem path) to the active color scheme CSS file.
 	 *
-	 * Returns the plain unminified LTR path. Frontend enqueuing (with SCRIPT_DEBUG
-	 * and RTL awareness) is handled by Styles_Handler.
-	 *
-	 * Falls back to the default One Dark theme if the chosen file does not exist.
+	 * Returns the plain unminified LTR path; enqueuing with SCRIPT_DEBUG and RTL
+	 * awareness is handled by Styles_Handler.
 	 *
 	 * @since 1.0.0
 	 *

includes/admin/class-settings.php

@@ -0,0 +1,94 @@
+pre code.hljs {
+	display: block;
+	overflow-x: auto;
+	padding: 1em;
+}
+code.hljs {
+	padding: 3px 5px;
+}
+/*!
+  Theme: a11y-dark
+  Author: @ericwbailey
+  Maintainer: @ericwbailey
+
+  Based on the Tomorrow Night Eighties theme: https://github.com/isagalaev/highlight.js/blob/master/src/styles/tomorrow-night-eighties.css
+*/
+.hljs {
+	background: #2b2b2b;
+	color: #f8f8f2;
+}
+/* Comment */
+.hljs-comment,
+.hljs-quote {
+	color: #d4d0ab;
+}
+/* Red */
+.hljs-variable,
+.hljs-template-variable,
+.hljs-tag,
+.hljs-name,
+.hljs-selector-id,
+.hljs-selector-class,
+.hljs-regexp,
+.hljs-deletion {
+	color: #ffa07a;
+}
+/* Orange */
+.hljs-number,
+.hljs-built_in,
+.hljs-literal,
+.hljs-type,
+.hljs-params,
+.hljs-meta,
+.hljs-link {
+	color: #f5ab35;
+}
+/* Yellow */
+.hljs-attribute {
+	color: #ffd700;
+}
+/* Green */
+.hljs-string,
+.hljs-symbol,
+.hljs-bullet,
+.hljs-addition {
+	color: #abe338;
+}
+/* Blue */
+.hljs-title,
+.hljs-section {
+	color: #00e0e0;
+}
+/* Purple */
+.hljs-keyword,
+.hljs-selector-tag {
+	color: #dcc6e0;
+}
+.hljs-emphasis {
+	font-style: italic;
+}
+.hljs-strong {
+	font-weight: bold;
+}
+@media screen and (-ms-high-contrast: active) {
+	.hljs-addition,
+	.hljs-attribute,
+	.hljs-built_in,
+	.hljs-bullet,
+	.hljs-comment,
+	.hljs-link,
+	.hljs-literal,
+	.hljs-meta,
+	.hljs-number,
+	.hljs-params,
+	.hljs-string,
+	.hljs-symbol,
+	.hljs-type,
+	.hljs-quote {
+		color: highlight;
+	}
+	.hljs-keyword,
+	.hljs-selector-tag {
+		font-weight: bold;
+	}
+}