feat: Initial scaffold of Toolbar

[josephfusco]

Zero-build toolbar implementation for headless WordPress applications.

Package Structure

@wpengine/hwp-toolbar

• Pure JavaScript implementation, no transpilation required
• Framework-agnostic core with React adapter
• WordPress context management (user session, post state, preview mode)

WordPress Plugins

• hwp-cors-local – Local development CORS headers
• hwp-frontend-links – Admin bar frontend routing
• hwp-wp-env-helpers – Docker environment REST API patches

Implementation

Vanilla

import { Toolbar } from '@wpengine/hwp-toolbar';

const toolbar = new Toolbar({
  position: 'bottom',
  onPreviewChange: (enabled) => console.log('Preview:', enabled)
});

toolbar.setWordPressContext({
  user: { id: 1, name: 'Admin' },
  post: { id: 42, title: 'Hello World' }
});

React

import { useToolbar } from '@wpengine/hwp-toolbar/react';

function MyToolbar() {
  const { state, nodes } = useToolbar(toolbar);
  return <div>User: {state.user?.name}</div>;
}

Technical Details

• Direct source consumption – No build pipeline, modules served as-is
• Deterministic port assignment – Hash-based calculation prevents conflicts
• Modular architecture – Core, renderer, and framework adapters decoupled
• Composer integration – Reusable plugin distribution
• Complete examples – Vanilla/Vite and React/Next.js 15 implementations

Running Examples

# Vanilla
cd examples/vanilla/toolbar-demo && npm run example:start  # localhost:3644

# Next.js
cd examples/next/toolbar-demo && npm run example:start     # localhost:3975

[changeset-bot]

⚠️ No Changeset found

Latest commit: 085b439

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[Copilot]

Pull Request Overview

This PR introduces a comprehensive headless WordPress toolkit with a modular plugin architecture and production-ready toolbar package. It transforms the previous template-based approach into a maintainable, reusable system with dynamic configuration and comprehensive documentation.

• Creates three single-responsibility WordPress plugins for CORS, frontend links, and wp-env helpers
• Introduces the @wpengine/hwp-toolbar package with framework-agnostic design and React hooks
• Updates examples to use the new plugin architecture with dynamic port calculation
• Provides complete documentation and production-ready configuration patterns

Reviewed Changes

Copilot reviewed 44 out of 47 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
packages/toolbar/*	Core toolbar package with TypeScript, React hooks, and vanilla renderer
plugins/*	Three modular WordPress plugins for headless development
examples//toolbar-demo/	Updated demo applications using new architecture
scripts/get-ports.js	Dynamic port calculation system for multi-example setup
IMPLEMENTATION_BREAKDOWN.md	Comprehensive implementation documentation

Comments suppressed due to low confidence (1)

plugins/hwp-wp-env-helpers/hwp-wp-env-helpers.php:1

• Direct $_SERVER access should be validated. Consider using sanitize_text_field() or checking if the key exists before accessing.

<?php

---

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

[josephfusco]

@ahuseyn I'm working on resolving these last build issues but i'll mark it ready for review now :)

[github-actions]

📦 Plugin Artifacts Ready!

Download from GitHub Actions run

Available plugins:

• ✅ hwp-cli.zip
• ✅ hwp-cors-local.zip
• ✅ hwp-frontend-links.zip
• ✅ hwp-wp-env-helpers.zip

See the "Artifacts" section at the bottom of the Actions run page

[Copilot]

Pull Request Overview

Copilot reviewed 55 out of 58 changed files in this pull request and generated 5 comments.

---

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

[Copilot]

When the WordPress connection fails, the error handling only checks response.ok but doesn't provide specific guidance about the likely cause. Consider adding more specific error messages for common scenarios like CORS issues or WordPress not running.

[Copilot]

Pull Request Overview

Copilot reviewed 56 out of 59 changed files in this pull request and generated 6 comments.

---

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

[Copilot]

The event target may not be an Element in all cases. Consider checking if e.target is an Element before calling contains().

Suggested change

	if (!container.contains(e.target)) {
	if (!(e.target instanceof Element) || !container.contains(e.target)) {

[Copilot]

Hardcoded user ID 1 could expose admin information. Consider using /wp/v2/users/me with proper authentication or implementing user validation.

Suggested change

	// Demo: Using user ID 1 (wp-env default admin) for simplicity
	// Production: Use /wp/v2/users/me with Application Passwords or OAuth
	// Note: This is acceptable in demos where auth setup would add unnecessary complexity
	return fetchFromWordPress('/wp/v2/users/1');
	}
	// Use /wp/v2/users/me to get the current authenticated user.
	// Requires proper authentication (e.g., Application Passwords or OAuth).
	return fetchFromWordPress('/wp/v2/users/me');
	}

[Copilot]

Direct access to $_SERVER['REQUEST_METHOD'] without sanitization. Consider using WordPress functions like $_SERVER['REQUEST_METHOD'] check after validating the request context.

Suggested change

	if ( $_SERVER['REQUEST_METHOD'] === 'OPTIONS' ) {
	if ( function_exists( 'get_request_method' ) ? get_request_method() === 'OPTIONS' : ( isset( $_SERVER['REQUEST_METHOD'] ) && $_SERVER['REQUEST_METHOD'] === 'OPTIONS' ) ) {

[Copilot]

Pull Request Overview

Copilot reviewed 56 out of 59 changed files in this pull request and generated 9 comments.

---

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

[Copilot]

When using register(id, onClick) pattern, the label is set to the id but labelOrNode is actually the onClick function. The label should remain as id and onClick should be labelOrNode.

[Copilot]

Global function assignment pollutes the global namespace. Consider using a module pattern or attaching to a namespaced object instead of directly to window.

Suggested change

	window.login = async () => {
	window.demoApp = window.demoApp || {};
	window.demoApp.login = async () => {

[Copilot]

Direct access to $_SERVER superglobal without sanitization. Consider using WordPress functions like get_server_var() or sanitize the input.

Suggested change

	if ( $_SERVER['REQUEST_METHOD'] === 'OPTIONS' ) {
	if ( get_server_var( 'REQUEST_METHOD' ) === 'OPTIONS' ) {

[Copilot]

The click outside handler is added/removed on every trigger click but never properly cleaned up if the dropdown is destroyed. This could lead to memory leaks.

[theodesp]

@josephfusco awesome job.
Please resolve copilot comments.