feat: add wp_bootstrap_should_render_template filter for plugin decoupling (v1.0.4)

Allows plugins and child themes to prevent the theme's TemplateController
from rendering specific requests, enabling clean separation of concerns.

Co-Authored-By: Claude <noreply@anthropic.com>

CHANGELOG.md

@@ -2,6 +2,24 @@
 
 All notable changes to this project will be documented in this file.
 
+## [1.0.4] - 2026-02-11
+
+### Added
+
+- `wp_bootstrap_should_render_template` filter in `TemplateController::render()` — allows plugins and child themes to prevent the theme from rendering a specific request, enabling clean separation of concerns when plugins handle their own page rendering
+
+## [1.0.3] - 2026-02-11
+
+### Fixed
+
+- Double `<h1>` headings on pages where plugins provide their own titles — `page.html.twig` now wraps `<h1>` in `{% if post.title is not empty %}` guard so plugins can suppress it by passing empty `post.title`
+
+## [1.0.2] - 2026-02-10
+
+### Fixed
+
+- Missing HTML `<title>` tag on all pages — theme never declared `add_theme_support('title-tag')`, so WordPress's `_wp_render_title_tag()` hook was inactive during `wp_head()` output in Twig templates
+
 ## [1.0.1] - 2026-02-09
 
 ### Added

CLAUDE.md

@@ -34,7 +34,7 @@ This project is proudly **"vibe-coded"** using Claude.AI - the entire codebase w
 
 **Note for AI Assistants:** Clean this section after the specific features are done or new releases are made. Effective changes are tracked in `CHANGELOG.md`. Do not add completed versions here - document them in the Session History section at the end of this file.
 
-Current version is **v1.0.1**. See `PLAN.md` for details.
+Current version is **v1.0.4**. See `PLAN.md` for details.
 
 ## Technical Stack
 
@@ -193,6 +193,58 @@ Build steps (in order):
 
 ## Session History
 
+### Session 12 — v1.0.4 Template Render Filter (2026-02-11)
+
+**Completed:** Added `wp_bootstrap_should_render_template` filter to `TemplateController::render()` for clean plugin/theme separation.
+
+**What was added:**
+
+- New `wp_bootstrap_should_render_template` filter at the top of `TemplateController::render()` — returns `true` by default, but plugins can return `false` to prevent the theme from rendering a request
+- Enables the wp-jobroom plugin to handle its own custom post types and routes without the theme's `TemplateController` racing to render first
+- Theme remains 100% standalone — the filter is a no-op when no plugin hooks into it
+
+**Key learnings:**
+
+- WordPress `template_redirect` hook priority ordering is the primary mechanism for plugin/theme rendering coordination: plugin Router at priority 5, theme TemplateController at default priority 10
+- Adding a simple filter check (`apply_filters('wp_bootstrap_should_render_template', true)`) is the cleanest decoupling mechanism — no cross-project class detection needed
+
+### Session 11 — v1.0.3 Conditional Page Title (2026-02-11)
+
+**Completed:** Made `<h1>` on page template conditional to prevent double headings when plugins provide their own titles.
+
+**What was fixed:**
+
+- `views/pages/page.html.twig` now wraps `<h1>{{ post.title }}</h1>` in `{% if post.title is not empty %}` guard
+- When a plugin passes empty `post.title` via `render_via_theme_twig()`, the theme's `<h1>` is skipped
+- Prevents duplicate headings on pages where plugin templates render their own `<h1>` with richer context (icons, badges, meta)
+
+**Key learnings:**
+
+- Plugins that delegate rendering to the parent theme via `TwigService` should be able to opt out of the theme's `<h1>` by passing empty `post.title`
+- The `is not empty` Twig test correctly handles both `null` and empty string `''`
+
+### Session 10 — v1.0.2 Title Tag Fix (2026-02-10)
+
+**Completed:** Fixed missing HTML `<title>` tag on all pages rendered by the theme's Twig pipeline.
+
+**What was fixed:**
+
+- Added `add_theme_support('title-tag')` to `wp_bootstrap_setup()` in `functions.php`
+
+**Root cause:**
+
+- The theme's `base.html.twig` calls `{{ wp_head() }}` which fires the `wp_head` action
+- WordPress hooks `_wp_render_title_tag()` to `wp_head` at priority 1, which outputs the `<title>` tag
+- However, this hook only fires when the theme declares `add_theme_support('title-tag')`
+- The theme never made this declaration, so `wp_head()` output included styles and scripts but no `<title>` element
+- All pages rendered by `TemplateController` (via `base.html.twig`) were affected
+
+**Key learnings:**
+
+- `add_theme_support('title-tag')` is required even for themes that render `wp_head()` via Twig — WordPress does not output `<title>` without it
+- The absence of a `<title>` tag is invisible in the rendered page but affects SEO, browser tab display, and bookmarking
+- This support declaration has been standard since WordPress 4.1 and should always be included in `after_setup_theme`
+
 ### Session 9 — v1.0.1 Bootstrap Icons (2026-02-09)
 
 **Completed:** Bootstrap Icons web font integration via SCSS build pipeline.

README.md

@@ -84,7 +84,7 @@ The theme uses a dual-rendering approach:
 - **Site Editor (admin):** FSE block templates in `templates/` and `parts/` for visual editing
 - **Frontend (public):** Twig templates in `views/` render Bootstrap 5 HTML via the `template_redirect` hook
 
-The `TemplateController` intercepts frontend requests and renders the appropriate Twig template with data gathered by `ContextBuilder`. FSE templates remain untouched for the WordPress admin editor.
+The `TemplateController` intercepts frontend requests and renders the appropriate Twig template with data gathered by `ContextBuilder`. Plugins can hook into the `wp_bootstrap_should_render_template` filter to prevent rendering for specific requests (e.g., when a plugin handles its own custom post types). FSE templates remain untouched for the WordPress admin editor.
 
 ### Style Variation Bridge
 

functions.php

@@ -23,6 +23,9 @@ if ( file_exists( get_template_directory() . '/vendor/autoload.php' ) ) {
  */
 if ( ! function_exists( 'wp_bootstrap_setup' ) ) :
     function wp_bootstrap_setup() {
+        // Add support for automatic document title tag.
+        add_theme_support( 'title-tag' );
+
         // Add support for post formats.
         add_theme_support( 'post-formats', array(
             'aside', 'audio', 'chat', 'gallery', 'image',

inc/Template/TemplateController.php

@@ -37,6 +37,11 @@ class TemplateController
             return;
         }
 
+        // Allow plugins or child themes to prevent rendering for this request.
+        if (! apply_filters('wp_bootstrap_should_render_template', true)) {
+            return;
+        }
+
         $template = $this->resolveTemplate();
         if (! $template) {
             return;

style.css

@@ -7,7 +7,7 @@ Description: A modern WordPress Block Theme built from scratch with Bootstrap 5.
 Requires at least: 6.7
 Tested up to: 6.7
 Requires PHP: 8.3
-Version: 1.0.1
+Version: 1.0.4
 License: GNU General Public License v2 or later
 License URI: http://www.gnu.org/licenses/gpl-2.0.html
 Text Domain: wp-bootstrap

views/pages/page.html.twig

@@ -10,7 +10,9 @@
             </figure>
         {% endif %}
 
+        {% if post.title is not empty %}
             <h1>{{ post.title }}</h1>
+        {% endif %}
 
         <div class="post-content">
             {{ post.content|raw }}