Byrde — BlueCrocus site builder

WordPress plugin for full-site pages and posts. Standalone templates; the active theme does not render Byrde documents. Visual work: (1) tokens + library definitions, (2) studio canvas with Blocks and Pages libraries.

Features

• Byrde Pages — CPT byrde_landing internally; kinds page | post | legal. URLs at /, /{slug}, /blog/{slug}
• Studio — Library (Blocks | Pages), canvas, stack reorder/shuffle, token toolbar
• PageTemplates — Landing, Contact, About, Pricing, Blog index/post, Legal
• SiteDesign — Light/dark tokens, font pairings, radius. CSS variables only
• Contact Form — Validation, honeypot, attribution, Postmark / wp_mail(), byrde_lead CPT
• SEO — Indexable by default; JSON-LD from published PageDocument
• Auto-Updates — Self-hosted JSON (updates.bluecrocus.ca), not GitHub as live channel

Requirements

• WordPress 6.0+ (tested up to 6.7)
• PHP 8.0+
• Node.js 20+

Installation

From GitHub Release (Recommended)

1. Download byrde.zip from the latest release
2. In WordPress, go to Plugins → Add New → Upload Plugin
3. Upload the ZIP and activate

From Source

git clone git@github.com:tales-bluecrocus/byrde.git
cd byrde
composer install --no-dev
cd front-end
npm install
npm run build

Then symlink or copy the byrde/ folder into wp-content/plugins/.

Configuration

Plugin Settings

Go to Settings → Theme Settings in the WordPress admin. Configure:

• Brand — Logo, phone number, email
• Brand Colors — Dark/light mode primary, accent, and text colors
• Button Style — Border width, radius, shadow, text colors per mode
• Google Reviews — Rating, review count, reviews URL
• Footer — Tagline, description, address, business hours, copyright
• Social Links — Facebook, Instagram, YouTube, Yelp, Google
• SEO — Site name, tagline, description, keywords, OG image
• Schema — LocalBusiness type, address, geo coordinates, opening hours, service radius
• Analytics — GA4 Measurement ID, GTM Container ID, Meta Pixel ID, Google Ads conversion labels
• Legal — Privacy policy, terms, cookie settings URLs
• Contact Form — Postmark API token, to/from/CC/BCC emails, subject line

Visual Editor

Go to Byrde Pages → New from template, then Edit with Byrde.

The studio lets you:

• Insert sections from the Blocks library and instantiate Pages from templates
• Shuffle a section for another definition in the same category
• Reorder / delete / clear the stack
• Edit block slots (no free CSS)
• Change SiteDesign tokens (primary, radius, fonts, light/dark)
• Save draft (PageDocument) and Publish

Tech Stack

Layer	Technology
CMS	WordPress 6.x
Backend	PHP 8.0+ with PSR-4 autoloading (Composer)
Frontend	React 19 + TypeScript 5.9
Build	Vite 7 (multi-entry, content-hashed filenames)
Styling	Tailwind CSS 4
UI Components	shadcn/ui (Radix primitives)
Icons	Lucide React + FontAwesome (brand icons)
Carousel	Embla Carousel (with autoplay)
Drag & Drop	@dnd-kit
Color Picker	react-colorful
State Management	React Context API
Settings	Native WordPress options (byrde_theme_settings)
Email	Postmark API (primary) + wp_mail() (fallback)
Auto-Updates	Plugin Update Checker v5 via self-hosted JSON metadata

Project Structure

byrde/
├── byrde.php                     # Plugin entry point (constants, autoload, boot)
├── src/                          # PHP classes (PSR-4, namespace Byrde\)
│   ├── Plugin.php                # Bootstrap: instantiates all modules
│   ├── Core/                     # Constants, Helpers, Logo
│   ├── Assets/                   # AssetManager (enqueue, preload, critical CSS)
│   ├── Settings/                 # Theme settings CRUD + Cache (12 hosting/CDN purge layers)
│   ├── Security/                 # Cleanup (XML-RPC), Validators, RateLimiter, CookieConsent
│   ├── Content/                  # CPT, TemplateLoader, SEO, Shortcodes, LegalPages
│   ├── API/                      # REST endpoints, ContactForm, Abilities (MCP)
│   ├── Admin/                    # SettingsPage, PageEditor, Onboarding
│   └── Migration/                # Theme→Plugin migration, color schema migrations (v2→v4)
├── front-end/                    # React application
│   ├── index.html                # Production entry (lightweight, no editor)
│   ├── editor.html               # Editor entry (includes ThemeEditor)
│   ├── vite.config.ts            # Production build config
│   ├── vite.config.editor.ts     # Editor build config (separate output)
│   ├── src/
│   │   ├── main.tsx              # Production bootstrap (+ onboarding lazy load)
│   │   ├── editor-main.tsx       # Editor bootstrap (imports ThemeEditor)
│   │   ├── App.tsx               # Shared app (7 nested context providers)
│   │   ├── components/           # React components (one per section)
│   │   │   ├── ThemeEditor/      # Visual editor sidebar + panels
│   │   │   ├── Onboarding/       # Setup wizard
│   │   │   └── ui/               # shadcn/ui primitives
│   │   ├── context/              # React Contexts (Settings, GlobalConfig, SectionTheme, HeaderConfig, Content, Sidebar)
│   │   ├── hooks/                # Custom hooks (useSettings, useSectionPalette, useAnalytics)
│   │   ├── lib/                  # Utilities (analytics, phone formatting)
│   │   └── utils/                # Color utilities, headline rendering
│   └── dist/                     # Production build (generated, hashed filenames)
│       └── .vite/manifest.json   # Asset manifest for PHP resolution
├── templates/
│   ├── template-landing.php      # Standalone HTML for landing pages (React mount)
│   └── template-legal.php        # Server-rendered legal pages (no React)
├── docs/                         # Additional documentation
├── .claude/agents/               # Claude Code specialized agents
│   ├── backend.md                # @backend — PHP, REST API, WordPress
│   ├── frontend.md               # @frontend — React, TypeScript, Vite, shadcn
│   ├── devops.md                 # @devops — Build, release, CI/CD
│   ├── reviewer.md               # @reviewer — Code review, security, a11y
│   ├── marketing.md              # @marketing — SEO, analytics, PPC tracking
│   └── design.md                 # @design — UI/UX, design system, WCAG
├── .config/                      # Release & build scripts
│   ├── bump-version.sh           # Auto-increment version (patch/minor/major)
│   ├── create-release.sh         # Create a tagged release
│   └── build-zip.sh              # Build local ZIP for manual upload
└── .github/workflows/
    └── release.yml               # GitHub Actions: build + release on tag push

Sections

Section	Component	Editable Content
Header	Header.tsx	Logo shape/color, fixed behavior, CTA button, Google Review badge
Topbar	Header.tsx (Topbar)	Message, icon, phone/email visibility, gradient/bg image
Hero	Hero.tsx	Headline, subheadline, badges, benefits, CTA, background image
Hero Form	HeroForm.tsx	Form title, subtitle, button text, fields
Featured Testimonial	FeaturedTestimonial.tsx	Quote, author, badge, CTA
Services	ServicesGrid.tsx	Headline, services list (icon, title, description)
Mid-Page CTA	MidPageCTA.tsx	Badge, headline, features list, CTA
Service Areas	ServiceAreas.tsx	Headline, areas list (with highlights), CTA
Testimonials	TestimonialsGrid.tsx	Headline, testimonials list (quote, author, rating)
FAQ	FAQ.tsx	Headline, FAQ list (question/answer), contact card
Footer CTA	FooterCTA.tsx	Headline, subheadline, CTA, reassurance text
Footer	Footer.tsx	Description, copyright, social links, contact info

REST API

Base URL: /wp-json/byrde/v1

Method	Endpoint	Description	Auth	Rate Limit
GET	/pages/{id}/theme	Get color/palette config	edit_post	—
PUT	/pages/{id}/theme	Save color/palette config	edit_post	10/min
GET	/pages/{id}/content	Get section content	edit_post	—
PUT	/pages/{id}/content	Save section content	edit_post	10/min
PUT	/pages/{id}/save-all	Atomic save (theme + content)	edit_post	10/min
GET	/settings	Get plugin settings	Public	—
PUT	/settings	Update plugin settings	manage_options	5/min
POST	/upload-image	Upload an image	upload_files	5/min
POST	/contact	Submit contact form	Public	10/5min (IP)
POST	/onboarding/complete	Mark onboarding done	manage_options	—

All authenticated endpoints require the X-WP-Nonce header.

Development

Prerequisites

node -v  # v20+
php -v   # 8.0+
composer -V

Frontend Development

cd front-end
npm install
npm run dev    # Vite dev server with HMR (open /editor.html for editor)

Production Build

cd front-end
npm run build  # Outputs to front-end/dist/ (two entries: production + editor)

PHP Autoload

composer dump-autoload  # Regenerate PSR-4 autoload after adding classes

Tests

cd front-end
npm test             # Run all tests
npm run test:watch   # Watch mode
npm run test:coverage # Coverage report

Releasing

Automated Release (via GitHub Actions)

# Bump patch version (1.1.0 → 1.1.1)
.config/bump-version.sh patch

# Bump minor version (1.1.0 → 1.2.0)
.config/bump-version.sh minor

# Bump major version (1.1.0 → 2.0.0)
.config/bump-version.sh major

# Or specify an exact version
.config/create-release.sh 2.0.0

This will:

1. Update the version in byrde.php (header + constant)
2. Commit and create an annotated git tag
3. Push to GitHub
4. GitHub Actions builds the frontend and packages the release ZIP

GitHub Releases are used for source-of-truth packaging only — they are not the update channel. To ship the update to live sites, upload the built ZIP and a matching metadata.json to updates.bluecrocus.ca (see below).

Manual ZIP + Metadata (for upload to the update server)

.config/build-zip.sh
# Output: ../byrde.zip + ../byrde-metadata.json

Then upload:

1. byrde.zip → https://updates.bluecrocus.ca/byrde/byrde-{VERSION}.zip
2. byrde-metadata.json → overwrite https://updates.bluecrocus.ca/byrde/metadata.json

Once metadata.json is live, sites running Byrde pick up the update on their next poll (or immediately via Check for updates).

How Auto-Updates Work

The plugin uses the Plugin Update Checker library (via Composer) against a self-hosted JSON metadata endpoint — not GitHub Releases/VCS. Byrde\Update\Checker registers the checker in Plugin::setup_update_checker().

1. WordPress polls https://updates.bluecrocus.ca/byrde/metadata.json every ~12h (WP core's built-in update schedule), or immediately when the admin clicks Check for updates on the Plugins screen
2. If metadata.json reports a newer version, WordPress shows the same native update notice as wordpress.org-hosted plugins
3. The admin clicks Update now and WordPress downloads the ZIP from download_url and installs it — one click, no manual upload

Metadata format

See docs/update-metadata.example.json. Fields: name, slug, version, download_url, homepage, requires, tested, requires_php, last_updated, sections.description, sections.changelog.

Overriding the metadata URL

By default the checker uses Constants::UPDATE_METADATA_URL. Override per-environment via, in order of precedence:

1. wp-config.php constant: define( 'BYRDE_UPDATE_METADATA_URL', 'https://example.com/byrde/metadata.json' );
2. Filter: add_filter( 'byrde_update_metadata_url', fn () => 'https://example.com/byrde/metadata.json' );

If the resolved URL is empty, the checker is a no-op (no updates checked).

Security

• Input validation and sanitization on all REST endpoints
• Rate limiting per user (saves, uploads) and per IP (contact form)
• Content size limits (512KB theme config, 1MB content, 5MB images)
• Item count limits (50 services, 100 testimonials, 50 FAQs, 100 service areas)
• MIME type verification and dimension checks on file uploads (max 3840x2160)
• Nonce-based authentication for all admin endpoints
• Permission checks per page (edit_post capability)
• Honeypot field on contact form
• XML-RPC disabled by default (byrde_disable_xmlrpc filter to override)
• Asset isolation on landing pages (two-layer: dequeue + tag filter)

Claude Code Agents

The project includes 6 specialized Claude Code agents in .claude/agents/:

Agent	Focus	Use For
@backend	PHP, REST API, WordPress	Classes, endpoints, validation, settings, CPT, migrations
@frontend	React, TypeScript, Vite	Components, hooks, contexts, color system, shadcn/ui
@devops	Build, release, CI/CD	GitHub Actions, Vite config, versioning, ZIP packaging
@reviewer	Code review, security	PR review, WCAG audit, performance check, code quality
@marketing	SEO, analytics, PPC	GA4/GTM tracking, attribution, JSON-LD, conversion setup
@design	UI/UX, design system	Visual quality, responsive, color system, accessibility

18 agent skills are also installed (.agents/skills/) covering WordPress, React, shadcn/ui, analytics, PPC, debugging, design review, and MCP.