Update CLAUDE.md with condensed architecture documentation, increase supported language count to 40 in README, adjust line-highlight opacity and remove redundant toolbar color override in frontend CSS

Author: ajaydsouza

CLAUDE.md

@@ -1,6 +1,6 @@
 # CLAUDE.md
 
-WordPress plugin that extends the native Gutenberg `core/code` block with Prism.js syntax highlighting. The editor integration is implemented by replacing the `core/code` block edit/save behaviour via a JS block filter, while frontend output is normalized and enhanced through the `render_block_core/code` PHP filter.
+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.
 
 ## Commands
 
@@ -20,174 +20,70 @@ npm run start          # Watch mode for block/editor/frontend bundles
 npm run zip            # Plugin zip
 ```
 
-## Current feature scope
-
-The current implementation follows the active plan in `PLAN.md`, not the broader experimental ideas in `OLD-FEATURE-PLAN.md`.
-
-- Extends `core/code` with per-block attributes:
-  - `language`
-  - `lineNumbers`
-  - `lineNumbersStart`
-  - `wordWrap`
-  - `title`
-  - `_legacyTitle` — read-only migration attribute; copies `title` from old `code-syntax-block` format on first load, then clears itself
-  - `highlightLines` — maps to `data-line` on `<pre>`, consumed by Prism line-highlight plugin
-  - `maxHeight` — inline `style="max-height:{n}px;overflow-y:auto"` on `<pre>` (CSS only, no Prism)
-- Adds Inspector Controls for:
-  - language selection
-  - file name/title
-  - line numbers toggle + start line
-  - word wrap
-  - highlight lines (e.g. `1,3-5`)
-  - max height in px
-  - save current settings as defaults
-- Saves defaults through the REST route `wz-cbh/v1/default-settings`
-- Frontend integrates Prism plugins for:
-  - line numbers
-  - line highlight
-  - toolbar
-  - show language
-  - copy to clipboard
-- Registers a custom Prism toolbar label that reads from `data-title`
-- Registers a `wz-cbh-expand` Prism toolbar button that appears when `max-height` is set; toggles the block between collapsed (original inline style) and expanded (inline style cleared), updating `aria-expanded` on each toggle
-- Supports global settings for:
-  - color scheme
-  - copy to clipboard
-  - show language label
-  - show file name
-  - default language
-  - default line numbers toggle
-  - default line numbers start
-  - default word wrap
-  - font size
-- Ships with `One Dark` as the default theme slug: `prism-onedark`
-
-Do not assume features from `OLD-FEATURE-PLAN.md` exist unless they are implemented in code.
+## Source of truth
+
+- Active implementation plan: `PLAN.md`
+- Backlog/reference only: `OLD-FEATURE-PLAN.md` — do not assume features exist unless implemented in code.
 
 ## Architecture
 
 **Namespace:** `WebberZone\Code_Block_Highlighting`
 
-**Autoloader:** `includes/autoloader.php`
-
-**Bootstrap flow:**
-
-- Main plugin file loads the autoloader.
-- `wz_cbh()` resolves the `Main` singleton on `plugins_loaded`.
-- `Main` loads `includes/options-api.php`.
-- `Main` instantiates:
-  - `Frontend\Blocks`
-  - `Frontend\Styles_Handler`
-- `Admin\Admin` is created on `init` only when `is_admin()`.
+Bootstrap: `wz_cbh()` singleton on `plugins_loaded` → instantiates `Frontend\Blocks`, `Frontend\Styles_Handler` → `Admin\Admin` on `init` (admin only).
 
-**Key PHP classes:**
+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/blocks/src/js/index.js` — block filter, Inspector Controls
+- `includes/blocks/src/js/frontend.js` — Prism grammars + plugins
 
-- `includes/class-main.php` — plugin bootstrap and object wiring
-- `includes/frontend/class-blocks.php` — editor asset registration, REST route, `render_block_core/code`
-- `includes/frontend/class-styles-handler.php` — conditional frontend Prism asset loading
-- `includes/admin/class-settings.php` — settings registration, theme resolution, language autocomplete wiring
+Always `require` the generated `.asset.php` manifest before enqueueing block scripts.
 
-**JS entry points:**
+## Non-obvious implementation details
 
-- `includes/blocks/src/js/index.js` — replaces `core/code` edit/save and adds Inspector Controls
-- `includes/blocks/src/js/frontend.js` — Prism core, supported grammars, toolbar/copy/show-language plugins, frontend toolbar behaviour
+**`_legacyTitle` attribute** — read-only migration attribute; copies `title` from old `code-syntax-block` format on first load, then clears itself.
 
-**Build output:**
+**`maxHeight`** — CSS-only: serialized as inline `style` by the block save function, not touched by the PHP render filter.
 
-- `includes/blocks/build/index.js`
-- `includes/blocks/build/frontend.js`
-- corresponding `.asset.php` manifests and extracted CSS files
+**`wz_cbh_languages` filter** — controls the editor UI dropdown only. Does not affect which Prism grammars are bundled. Adding a slug without a matching grammar import in `frontend.js` results in plain-text output.
 
-Always `require` the generated `.asset.php` file before enqueueing block scripts.
+**Editor canvas styling** — `enqueue_editor_canvas_styles()` extracts only `background` and `color` from the active Prism theme CSS and re-injects them with `.block-editor-block-list__layout` prepended to win the specificity race against the editor's own `pre` styles. Layout properties are intentionally excluded.
 
-## Data flow
+**Default color scheme:** `prism-onedark`
 
-- Language list is provided by `Frontend\Blocks::get_languages()`
-- Editor globals are injected with `wp_add_inline_script()`:
-  - `cbhLanguages`
-  - `cbhDefaultLang`
-  - `cbhDefaultSettings`
-- Frontend globals are injected with `wp_add_inline_script()`:
-  - `cbhSettings`
-- Block attributes are saved in block markup and normalized again in `render_code_block()`
-- Default settings are stored in plugin options through the REST endpoint
+**If you change block attributes in JS**, update `render_code_block()` in `class-blocks.php` and the defaults flow as well.
 
 ## Asset loading
 
-`Frontend\Styles_Handler::enqueue_assets()` only loads Prism on the frontend when at least one `core/code` block is present in the current queried posts.
-
-Use `wz_cbh_force_load_assets` to bypass conditional loading.
-
-The editor canvas styling is handled separately in `Frontend\Blocks::enqueue_editor_canvas_styles()`, which:
+Prism assets load only on pages containing at least one `core/code` block (`Styles_Handler::enqueue_assets()`). Use `wz_cbh_force_load_assets` to override.
 
-- enqueues editor CSS into the block editor iframe
-- extracts only `background` and `color` declarations from the active Prism theme
-- re-injects them with stronger selectors so the editor canvas matches the chosen frontend theme without breaking editor layout
+## Filters and routes
 
-## Key filters, options, and routes
-
-- `wz_cbh_languages` — filter supported Prism languages (`slug => label`)
-- `wz_cbh_color_scheme_css_url` — filter the resolved Prism theme CSS URL
-- `wz_cbh_force_load_assets` — force frontend Prism assets to load
+- `wz_cbh_languages` — language picker UI list (`slug => label`); UI only, not grammar loader
+- `wz_cbh_color_scheme_css_url` — override the Prism theme CSS URL
+- `wz_cbh_force_load_assets` — force Prism assets to load on every page
 - REST route: `wz-cbh/v1/default-settings`
-- Settings option key: `wz_cbh_settings`
-- Settings prefix: `wz_cbh`
-- Settings page slug: `wz_cbh_settings`
-
-## Current option IDs
-
-These option IDs are registered in `includes/admin/class-settings.php`:
-
-- `color-scheme`
-- `copy-to-clipboard`
-- `show-language-label`
-- `show-file-name`
-- `default-lang`
-- `default-line-numbers`
-- `default-line-numbers-start`
-- `default-word-wrap`
-- `font-size`
-
-The default color scheme is `prism-onedark`.
+- Settings key: `wz_cbh_settings`
 
-## Frontend rendering rules
-
-`Frontend\Blocks::render_code_block()` currently:
-
-- adds `language-{slug}` to `<code>`
-- adds `line-numbers` to `<pre>` when enabled
-- adds `data-start` to `<pre>` when line numbering starts from a value other than `1`
-- adds `word-wrap` to `<pre>` when enabled
-- adds `data-title` to `<pre>` for the custom toolbar label
-- adds `data-line` to `<pre>` from `highlightLines` attribute (consumed by Prism line-highlight plugin)
-- `maxHeight` is CSS-only: serialized as inline `style` by the block save function, not touched by PHP
-
-If you change block attributes in JS, update the PHP rendering logic and defaults flow as well.
-
-## Accessibility notes
+## Adding a Prism theme
 
-The active plan targets strong accessibility support. Current frontend code already includes:
+1. Add the theme mapping in `build-prism.js`
+2. Copy the CSS to `includes/assets/`
+3. Register the slug in `includes/admin/class-settings.php`
+4. Run `npm run build:prism`
 
-- decorative toolbar language labels marked `aria-hidden`
-- a custom title label in the toolbar
-- Prism copy-to-clipboard integration controlled by plugin settings
-- expand/collapse button with `aria-expanded` state management
+## Adding a language
 
-If you extend toolbar behaviour, preserve keyboard access and screen reader behaviour.
+1. Add `import 'prismjs/components/prism-{slug}'` to `frontend.js` (respect dependency order)
+2. Add `'slug' => 'Label'` to `get_languages()` in `class-blocks.php`
+3. Run `npm run build`
 
-## Adding a Prism theme
+## Accessibility
 
-1. Add the theme mapping in `build-prism.js`
-2. Ensure the generated CSS file is copied to `includes/assets/`
-3. Register the theme slug in `includes/admin/class-settings.php`
-4. Run `npm run build:prism`
+Toolbar language labels are `aria-hidden`. Expand/collapse button uses `aria-expanded`. When extending toolbar behaviour, preserve keyboard access and screen reader support.
 
-## Notes for future work
+## Before adding new per-block controls
 
-- Prefer `PLAN.md` as the source of truth for current implementation direction
-- Treat `OLD-FEATURE-PLAN.md` as backlog/reference only
-- Before adding new per-block controls, verify:
-  - the JS attribute schema
-  - the save output
-  - the PHP render filter
-  - frontend Prism plugin support
+Verify: JS attribute schema → save output → `render_code_block()` in PHP → frontend Prism plugin support.

README.md

@@ -16,7 +16,7 @@ __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 18 themes and 35+ languages, zero configuration required.
+Add beautiful syntax highlighting to the Gutenberg Code block — powered by Prism.js with 18 themes and 40 languages, zero configuration required.
 
 ## Description
 
@@ -34,7 +34,7 @@ Simply activate the plugin and your code blocks will instantly display beautiful
 
 ### Supported languages
 
-35+ languages out of the box: Bash, C, C++, C#, CSS, Dart, Docker, F#, Go, GraphQL, Haskell, HTML, Java, JavaScript, JSON, JSX, Kotlin, Markdown, Nginx, Objective-C, PHP, PowerShell, Python, Ruby, Rust, Sass, SQL, Swift, TOML, TSX, TypeScript, Vim, XML, YAML, and more. Use the `wz_cbh_languages` filter to register additional languages.
+40 languages out of the box: Apache Config, Bash, C, C++, C#, CSS, Dart, Docker, F#, Go, GraphQL, Groovy, Haskell, HTML, Java, JavaScript, JSON, JSX, Kotlin, Lua, Markdown, Nginx, Objective-C, Perl, PHP, PowerShell, Python, R, Ruby, Rust, Sass, Scala, SQL, Swift, TOML, TSX, TypeScript, Vim, XML, and YAML. Use the `wz_cbh_languages` filter to add or remove entries from the language picker.
 
 ### Included themes (18)
 
@@ -97,7 +97,7 @@ __Does this plugin replace the core Code block?__
 No. The plugin uses JavaScript and PHP filters to extend `core/code`. Deactivating it leaves behind valid, standard WordPress blocks.
 
 __Which languages are supported?__
-35+ out of the box. Use the `wz_cbh_languages` filter to register additional Prism.js grammars.
+40 out of the box. Use the `wz_cbh_languages` filter to add or remove entries from the language picker — note the corresponding Prism.js grammar must also be available on the frontend.
 
 __Does Prism.js load on every page?__
 No. Assets are only enqueued on pages containing at least one code block. Use `wz_cbh_force_load_assets` to override.