Skip to content

Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.

feat(integrations): add a WordPress block/shortcode plugin for <agent-3d>, pinned to the release ledger

nirholasa80ce225d0e9
diff --git a/integrations/wordpress/three-ws-agent/README.md b/integrations/wordpress/three-ws-agent/README.md
new file mode 100755
index 000000000..d555e12b2
--- /dev/null
+++ b/integrations/wordpress/three-ws-agent/README.md
@@ -0,0 +1,41 @@
+# three.ws Agent (WordPress plugin)
+
+A Gutenberg block (`three-ws/agent-3d`) and a `[three_ws_agent]` shortcode that embed the
+[`<agent-3d>`](../../../docs/web-component.md) custom element: a live, animated 3D AI agent in
+one script tag. No build step, no npm, no bundler; the editor script is plain ES5-safe JS
+against the `wp.*` globals WordPress already ships.
+
+## Layout
+
+| File | Role |
+|---|---|
+| [`three-ws-agent.php`](three-ws-agent.php) | Plugin bootstrap: headers, requires the four `includes/` files. |
+| [`includes/pinned-release.php`](includes/pinned-release.php) | **Generated.** The `<agent-3d>` version, CDN URL and SRI hash this release ships against. Run `npm run build:site-builder-embeds` from the repo root to regenerate after a new `npm run release:lib`. Never edit by hand. |
+| [`includes/render.php`](includes/render.php) | `three_ws_agent_render()`: the one function that builds the `<agent-3d>` tag and registers/enqueues the pinned loader script with `type="module"`, `integrity` and `crossorigin`. Shared by the block and the shortcode so both always emit identical markup. |
+| [`includes/block.php`](includes/block.php) | Registers `three-ws/agent-3d` from `blocks/agent-3d/block.json` with a server `render_callback`. |
+| [`includes/shortcode.php`](includes/shortcode.php) | `[three_ws_agent]`, for the classic editor, widgets and theme templates. |
+| [`blocks/agent-3d/`](blocks/agent-3d/) | `block.json` (attributes, supports), `index.js` (editor UI: `InspectorControls` + `ServerSideRender`, so the editor preview is the exact PHP-rendered output), `index.asset.php` (hand-written script-dependency manifest, in place of a `@wordpress/scripts` build), `style.css`. |
+
+## Why `ServerSideRender` instead of a client-side editor preview
+
+The block's `edit()` renders [`ServerSideRender`](https://github.com/WordPress/gutenberg/tree/trunk/packages/server-side-render) pointed at the same block name, which calls `three_ws_agent_block_render()` over the REST API. The editor preview is therefore never a second, divergent implementation of the markup; it is the same PHP the front end runs, which is also why the block has no `save()` markup of its own (`save` returns `null`; the block is always server-rendered).
+
+## SRI pin
+
+`includes/pinned-release.php` is one of three files [`scripts/build-site-builder-embeds.mjs`](../../../scripts/build-site-builder-embeds.mjs) writes from [`data/agent-3d-releases.json`](../../../data/agent-3d-releases.json) (the other two are the Framer and Webflow components' `pinned-release.ts`). `npm run check:site-builder-embeds` fails the build if any of the three has drifted from the ledger; it is wired into `npm run gate`.
+
+## Testing
+
+No PHP dependency beyond WordPress core (no Composer, no PHPUnit scaffold in this plugin). Verified with a real local WordPress install and the official [Plugin Check](https://wordpress.org/plugins/plugin-check/) plugin:
+
+```bash
+# from the repo root
+scripts/wordpress-plugin-check.sh
+```
+
+The script spins up `mysql:8` and `wordpress:php8.2-apache` in Docker, mounts this directory as a plugin, installs and activates Plugin Check via WP-CLI, and runs `wp plugin check three-ws-agent`. See that script for the exact commands; its output is reproduced in [`docs/wordpress-embed.md`](../../../docs/wordpress-embed.md).
+
+## Submitting to the WordPress.org plugin directory
+
+Submission (a third-party upload under an owner-controlled WordPress.org account) is an owner
+action: see [`marketing/growth/submissions/site-builders.md`](../../../marketing/growth/submissions/site-builders.md).
diff --git a/integrations/wordpress/three-ws-agent/blocks/agent-3d/block.json b/integrations/wordpress/three-ws-agent/blocks/agent-3d/block.json
new file mode 100755
index 000000000..308d9b597
--- /dev/null
+++ b/integrations/wordpress/three-ws-agent/blocks/agent-3d/block.json
@@ -0,0 +1,29 @@
+{
+ "$schema": "https://schemas.wp.org/trunk/block.json",
+ "apiVersion": 3,
+ "name": "three-ws/agent-3d",
+ "title": "three.ws Agent",
+ "category": "embed",
+ "icon": "universal-access-alt",
+ "description": "Embed a live, animated three.ws 3D AI agent.",
+ "keywords": ["3d", "avatar", "agent", "three.ws", "embed"],
+ "version": "1.0.0",
+ "textdomain": "three-ws-agent",
+ "attributes": {
+ "src": { "type": "string", "default": "" },
+ "agentId": { "type": "string", "default": "" },
+ "chainId": { "type": "string", "default": "" },
+ "modelUrl": { "type": "string", "default": "" },
+ "background": { "type": "string", "default": "transparent" },
+ "framing": { "type": "string", "default": "full" },
+ "poster": { "type": "string", "default": "" },
+ "width": { "type": "string", "default": "100%" },
+ "height": { "type": "string", "default": "480px" }
+ },
+ "supports": {
+ "html": false,
+ "align": ["wide", "full"]
+ },
+ "editorScript": "file:./index.js",
+ "style": "file:./style.css"
+}
diff --git a/integrations/wordpress/three-ws-agent/blocks/agent-3d/index.asset.php b/integrations/wordpress/three-ws-agent/blocks/agent-3d/index.asset.php
new file mode 100755
index 000000000..db387fc0a
--- /dev/null
+++ b/integrations/wordpress/three-ws-agent/blocks/agent-3d/index.asset.php
@@ -0,0 +1,21 @@
+<?php
+/**
+ * Hand-written in place of a @wordpress/scripts build: this plugin ships no
+ * bundler, so index.js is plain ES5-safe JS using the wp.* globals below
+ * directly. WordPress reads this file's "dependencies" to enqueue them
+ * before index.js, the same contract wp-scripts' build output uses.
+ *
+ * @package ThreeWsAgent
+ */
+
+return array(
+ 'dependencies' => array(
+ 'wp-blocks',
+ 'wp-element',
+ 'wp-block-editor',
+ 'wp-components',
+ 'wp-server-side-render',
+ 'wp-i18n',
+ ),
+ 'version' => THREE_WS_AGENT3D_VERSION,
+);
diff --git a/integrations/wordpress/three-ws-agent/blocks/agent-3d/index.js b/integrations/wordpress/three-ws-agent/blocks/agent-3d/index.js
new file mode 100755
index 000000000..83c36ce04
--- /dev/null
+++ b/integrations/wordpress/three-ws-agent/blocks/agent-3d/index.js
@@ -0,0 +1,124 @@
+/**
+ * Editor script for the three-ws/agent-3d block. Plain ES5-safe JS against
+ * the wp.* globals (no bundler) so the plugin ships zero build step.
+ *
+ * The editor preview renders through ServerSideRender, which calls the exact
+ * same PHP render callback the front end uses, so what the editor shows is
+ * what visitors get.
+ */
+( function ( blocks, element, blockEditor, components, serverSideRender, i18n ) {
+ var el = element.createElement;
+ var __ = i18n.__;
+ var InspectorControls = blockEditor.InspectorControls;
+ var PanelBody = components.PanelBody;
+ var TextControl = components.TextControl;
+ var SelectControl = components.SelectControl;
+ var ServerSideRender = serverSideRender;
+
+ blocks.registerBlockType( 'three-ws/agent-3d', {
+ edit: function ( props ) {
+ var attributes = props.attributes;
+ var setAttributes = props.setAttributes;
+
+ function set( key ) {
+ return function ( value ) {
+ var next = {};
+ next[ key ] = value;
+ setAttributes( next );
+ };
+ }
+
+ return el(
+ element.Fragment,
+ {},
+ el(
+ InspectorControls,
+ {},
+ el(
+ PanelBody,
+ { title: __( 'Agent source', 'three-ws-agent' ), initialOpen: true },
+ el( TextControl, {
+ label: __( 'On-chain URI (src)', 'three-ws-agent' ),
+ help: __( 'e.g. agent://base/42. Takes priority over agent ID and model URL.', 'three-ws-agent' ),
+ value: attributes.src,
+ onChange: set( 'src' ),
+ } ),
+ el( TextControl, {
+ label: __( 'Agent ID', 'three-ws-agent' ),
+ help: __( 'Backend account ID or CAIP-10 agent ID. Used when no on-chain URI is set.', 'three-ws-agent' ),
+ value: attributes.agentId,
+ onChange: set( 'agentId' ),
+ } ),
+ el( TextControl, {
+ label: __( 'Chain ID', 'three-ws-agent' ),
+ help: __( 'Paired with a numeric Agent ID, e.g. 8453 for Base.', 'three-ws-agent' ),
+ value: attributes.chainId,
+ onChange: set( 'chainId' ),
+ } ),
+ el( TextControl, {
+ label: __( 'Model URL', 'three-ws-agent' ),
+ help: __( 'Bare GLB URL for an ad-hoc agent, used when no on-chain URI or agent ID is set.', 'three-ws-agent' ),
+ value: attributes.modelUrl,
+ onChange: set( 'modelUrl' ),
+ } )
+ ),
+ el(
+ PanelBody,
+ { title: __( 'Appearance', 'three-ws-agent' ), initialOpen: false },
+ el( SelectControl, {
+ label: __( 'Background', 'three-ws-agent' ),
+ value: attributes.background,
+ options: [
+ { label: __( 'Transparent', 'three-ws-agent' ), value: 'transparent' },
+ { label: __( 'Dark', 'three-ws-agent' ), value: 'dark' },
+ { label: __( 'Light', 'three-ws-agent' ), value: 'light' },
+ ],
+ onChange: set( 'background' ),
+ } ),
+ el( SelectControl, {
+ label: __( 'Framing', 'three-ws-agent' ),
+ value: attributes.framing,
+ options: [
+ { label: __( 'Full', 'three-ws-agent' ), value: 'full' },
+ { label: __( 'Portrait', 'three-ws-agent' ), value: 'portrait' },
+ ],
+ onChange: set( 'framing' ),
+ } ),
+ el( TextControl, {
+ label: __( 'Poster image URL', 'three-ws-agent' ),
+ value: attributes.poster,
+ onChange: set( 'poster' ),
+ } ),
+ el( TextControl, {
+ label: __( 'Width', 'three-ws-agent' ),
+ value: attributes.width,
+ onChange: set( 'width' ),
+ } ),
+ el( TextControl, {
+ label: __( 'Height', 'three-ws-agent' ),
+ value: attributes.height,
+ onChange: set( 'height' ),
+ } )
+ )
+ ),
+ el( 'div', { className: 'three-ws-agent-block-preview' },
+ el( ServerSideRender, {
+ block: 'three-ws/agent-3d',
+ attributes: attributes,
+ } )
+ )
+ );
+ },
+ save: function () {
+ // Server-rendered: PHP (three_ws_agent_block_render) owns the markup.
+ return null;
+ },
+ } );
+} )(
+ window.wp.blocks,
+ window.wp.element,
+ window.wp.blockEditor,
+ window.wp.components,
+ window.wp.serverSideRender,
+ window.wp.i18n
+);
diff --git a/integrations/wordpress/three-ws-agent/blocks/agent-3d/style.css b/integrations/wordpress/three-ws-agent/blocks/agent-3d/style.css
new file mode 100755
index 000000000..8659f2800
--- /dev/null
+++ b/integrations/wordpress/three-ws-agent/blocks/agent-3d/style.css
@@ -0,0 +1,10 @@
+.three-ws-agent-block-preview {
+ min-height: 120px;
+}
+
+.three-ws-agent-placeholder {
+ padding: 1em;
+ border: 1px dashed #ccc;
+ color: #555;
+ text-align: center;
+}
diff --git a/integrations/wordpress/three-ws-agent/includes/block.php b/integrations/wordpress/three-ws-agent/includes/block.php
new file mode 100755
index 000000000..abb3fd6fa
--- /dev/null
+++ b/integrations/wordpress/three-ws-agent/includes/block.php
@@ -0,0 +1,44 @@
+<?php
+/**
+ * Registers the three-ws/agent-3d block and its server-side render.
+ *
+ * @package ThreeWsAgent
+ */
+
+if (!defined('ABSPATH')) {
+ exit;
+}
+
+/**
+ * Renders the block on the front end from its saved attributes.
+ *
+ * @param array $attributes Block attributes (see blocks/agent-3d/block.json).
+ * @return string
+ */
+function three_ws_agent_block_render($attributes) {
+ return three_ws_agent_render(
+ array(
+ 'src' => $attributes['src'] ?? '',
+ 'agent_id' => $attributes['agentId'] ?? '',
+ 'chain_id' => $attributes['chainId'] ?? '',
+ 'model' => $attributes['modelUrl'] ?? '',
+ 'background' => $attributes['background'] ?? 'transparent',
+ 'framing' => $attributes['framing'] ?? 'full',
+ 'poster' => $attributes['poster'] ?? '',
+ 'width' => $attributes['width'] ?? '100%',
+ 'height' => $attributes['height'] ?? '480px',
+ )
+ );
+}
+
+/**
+ * Registers the block type from blocks/agent-3d/block.json and its editor
+ * script, and enqueues the editor-only stylesheet.
+ */
+function three_ws_agent_register_block() {
+ register_block_type(
+ THREE_WS_AGENT_PLUGIN_DIR . 'blocks/agent-3d',
+ array('render_callback' => 'three_ws_agent_block_render')
+ );
+}
+add_action('init', 'three_ws_agent_register_block');
diff --git a/integrations/wordpress/three-ws-agent/includes/pinned-release.php b/integrations/wordpress/three-ws-agent/includes/pinned-release.php
new file mode 100755
index 000000000..5171b4928
--- /dev/null
+++ b/integrations/wordpress/three-ws-agent/includes/pinned-release.php
@@ -0,0 +1,16 @@
+<?php
+/**
+ * Generated by scripts/build-site-builder-embeds.mjs from data/agent-3d-releases.json. Do not edit by hand: run `npm run build:site-builder-embeds`.
+ *
+ * @package ThreeWsAgent
+ */
+
+if (!defined('ABSPATH')) {
+ exit;
+}
+
+define('THREE_WS_AGENT3D_VERSION', '1.5.2');
+define('THREE_WS_AGENT3D_JS_URL', 'https://three.ws/agent-3d/1.5.2/agent-3d.js');
+define('THREE_WS_AGENT3D_JS_INTEGRITY', 'sha384-KdAiFRsdcCbQMu4O5rkoL8hOEYLkmrdpf9ELd7jro+9NTNipWis3oqqFLll7v20Q');
+define('THREE_WS_AGENT3D_UMD_URL', 'https://three.ws/agent-3d/1.5.2/agent-3d.umd.cjs');
+define('THREE_WS_AGENT3D_UMD_INTEGRITY', 'sha384-z74vjNbQ8KKXBZHL6JFhl4h45B+InYbzbV8ArjZSgzR+ATWOEthqu0S/eadTA0XC');
diff --git a/integrations/wordpress/three-ws-agent/includes/render.php b/integrations/wordpress/three-ws-agent/includes/render.php
new file mode 100755
index 000000000..b1828bd27
--- /dev/null
+++ b/integrations/wordpress/three-ws-agent/includes/render.php
@@ -0,0 +1,135 @@
+<?php
+/**
+ * Shared render path for the block and the [three_ws_agent] shortcode: both
+ * build the same attribute set and hand it to three_ws_agent_render().
+ *
+ * @package ThreeWsAgent
+ */
+
+if (!defined('ABSPATH')) {
+ exit;
+}
+
+const THREE_WS_AGENT_SCRIPT_HANDLE = 'three-ws-agent-3d';
+
+/**
+ * Registers the pinned <agent-3d> loader script once per request. Safe to
+ * call from both the block render callback and the shortcode handler.
+ */
+function three_ws_agent_register_script() {
+ if (wp_script_is(THREE_WS_AGENT_SCRIPT_HANDLE, 'registered')) {
+ return;
+ }
+
+ wp_register_script(
+ THREE_WS_AGENT_SCRIPT_HANDLE,
+ THREE_WS_AGENT3D_JS_URL,
+ array(),
+ THREE_WS_AGENT3D_VERSION,
+ array('strategy' => 'defer')
+ );
+ wp_script_add_data(THREE_WS_AGENT_SCRIPT_HANDLE, 'type', 'module');
+ wp_script_add_data(THREE_WS_AGENT_SCRIPT_HANDLE, 'integrity', THREE_WS_AGENT3D_JS_INTEGRITY);
+ wp_script_add_data(THREE_WS_AGENT_SCRIPT_HANDLE, 'crossorigin', 'anonymous');
+}
+
+/**
+ * Rewrites the registered loader's <script> tag to carry type="module",
+ * integrity and crossorigin, which wp_enqueue_script's own API does not
+ * expose for ESM loads. Added once, from three_ws_agent_render().
+ *
+ * @param string $tag The <script> tag WordPress built for $handle.
+ * @param string $handle The script handle being printed.
+ * @param string $src The script's resolved src attribute.
+ * @return string
+ */
+function three_ws_agent_filter_script_tag($tag, $handle, $src) {
+ if (THREE_WS_AGENT_SCRIPT_HANDLE !== $handle) {
+ return $tag;
+ }
+
+ $integrity = esc_attr(wp_scripts()->get_data(THREE_WS_AGENT_SCRIPT_HANDLE, 'integrity'));
+ $crossorigin = esc_attr(wp_scripts()->get_data(THREE_WS_AGENT_SCRIPT_HANDLE, 'crossorigin'));
+
+ // $src was already registered and enqueued with wp_register_script() /
+ // wp_enqueue_script() above; this filter only rewrites that one script's
+ // own output tag to add type="module", integrity and crossorigin, which
+ // core's enqueue API has no argument for.
+ $markup = '<script type="module" src="' . esc_url($src) . '" integrity="' . $integrity . '" crossorigin="' . $crossorigin . '"></script>' . "\n"; // phpcs:ignore WordPress.WP.EnqueuedResources.NonEnqueuedScript
+
+ return $markup;
+}
+add_filter('script_loader_tag', 'three_ws_agent_filter_script_tag', 10, 3);
+
+/**
+ * Renders a <agent-3d> element from a normalized attribute set. Exactly one
+ * of $atts['src'], $atts['agent_id'] or $atts['model'] should be set; if more
+ * than one is, the element's own priority order (src > agent-id > manifest >
+ * body) decides which wins, same as every other <agent-3d> embed.
+ *
+ * @param array $atts {
+ * @type string $src On-chain agent:// URI.
+ * @type string $agent_id Backend account id or CAIP-10 agent id.
+ * @type string $chain_id Chain id, paired with a numeric agent_id.
+ * @type string $model Bare GLB URL for an ad-hoc agent.
+ * @type string $background transparent|dark|light.
+ * @type string $framing full|portrait.
+ * @type string $poster Poster image URL shown while the model loads.
+ * @type string $width CSS width, e.g. "100%" or "480px".
+ * @type string $height CSS height, e.g. "520px".
+ * }
+ * @return string
+ */
+function three_ws_agent_render($atts) {
+ three_ws_agent_register_script();
+ wp_enqueue_script(THREE_WS_AGENT_SCRIPT_HANDLE);
+
+ $src = isset($atts['src']) ? trim((string) $atts['src']) : '';
+ $agent_id = isset($atts['agent_id']) ? trim((string) $atts['agent_id']) : '';
+ $chain_id = isset($atts['chain_id']) ? trim((string) $atts['chain_id']) : '';
+ $model = isset($atts['model']) ? trim((string) $atts['model']) : '';
+ $background = isset($atts['background']) ? trim((string) $atts['background']) : 'transparent';
+ $framing = isset($atts['framing']) ? trim((string) $atts['framing']) : 'full';
+ $poster = isset($atts['poster']) ? trim((string) $atts['poster']) : '';
+ $width = isset($atts['width']) ? trim((string) $atts['width']) : '100%';
+ $height = isset($atts['height']) ? trim((string) $atts['height']) : '480px';
+
+ if ('' === $src && '' === $agent_id && '' === $model) {
+ return sprintf(
+ '<p class="three-ws-agent-placeholder">%s</p>',
+ esc_html__('three.ws Agent: set an agent ID, on-chain URI or model URL to render an avatar here.', 'three-ws-agent')
+ );
+ }
+
+ if (!in_array($background, array('transparent', 'dark', 'light'), true)) {
+ $background = 'transparent';
+ }
+ if (!in_array($framing, array('full', 'portrait'), true)) {
+ $framing = 'full';
+ }
+
+ $attrs = array();
+ if ('' !== $src) {
+ $attrs[] = sprintf('src="%s"', esc_attr($src));
+ } elseif ('' !== $agent_id) {
+ $attrs[] = sprintf('agent-id="%s"', esc_attr($agent_id));
+ if ('' !== $chain_id) {
+ $attrs[] = sprintf('chain-id="%s"', esc_attr($chain_id));
+ }
+ } elseif ('' !== $model) {
+ $attrs[] = sprintf('body="%s"', esc_url($model));
+ }
+
+ $attrs[] = sprintf('background="%s"', esc_attr($background));
+ $attrs[] = sprintf('framing="%s"', esc_attr($framing));
+ if ('' !== $poster) {
+ $attrs[] = sprintf('poster="%s"', esc_url($poster));
+ }
+
+ return sprintf(
+ '<agent-3d %1$s style="display:block;width:%2$s;height:%3$s"></agent-3d>',
+ implode(' ', $attrs),
+ esc_attr($width),
+ esc_attr($height)
+ );
+}
diff --git a/integrations/wordpress/three-ws-agent/includes/shortcode.php b/integrations/wordpress/three-ws-agent/includes/shortcode.php
new file mode 100755
index 000000000..673e52f42
--- /dev/null
+++ b/integrations/wordpress/three-ws-agent/includes/shortcode.php
@@ -0,0 +1,39 @@
+<?php
+/**
+ * [three_ws_agent] shortcode: the same embed for the classic editor, widgets,
+ * and any theme template that cannot use the block.
+ *
+ * @package ThreeWsAgent
+ */
+
+if (!defined('ABSPATH')) {
+ exit;
+}
+
+/**
+ * [three_ws_agent src="agent://base/42" background="dark" framing="portrait"]
+ * [three_ws_agent model="https://three.ws/avatars/default.glb" height="600px"]
+ *
+ * @param array $atts Shortcode attributes; see three_ws_agent_render() for the keys.
+ * @return string
+ */
+function three_ws_agent_shortcode($atts) {
+ $atts = shortcode_atts(
+ array(
+ 'src' => '',
+ 'agent_id' => '',
+ 'chain_id' => '',
+ 'model' => '',
+ 'background' => 'transparent',
+ 'framing' => 'full',
+ 'poster' => '',
+ 'width' => '100%',
+ 'height' => '480px',
+ ),
+ $atts,
+ 'three_ws_agent'
+ );
+
+ return three_ws_agent_render($atts);
+}
+add_shortcode('three_ws_agent', 'three_ws_agent_shortcode');
diff --git a/integrations/wordpress/three-ws-agent/readme.txt b/integrations/wordpress/three-ws-agent/readme.txt
new file mode 100755
index 000000000..41f30c078
--- /dev/null
+++ b/integrations/wordpress/three-ws-agent/readme.txt
@@ -0,0 +1,65 @@
+=== three.ws Agent ===
+Contributors: threews
+Tags: 3d, avatar, ai agent, embed, block
+Requires at least: 6.4
+Tested up to: 7.1
+Requires PHP: 7.4
+Stable tag: 1.0.0
+License: GPLv2 or later
+License URI: https://www.gnu.org/licenses/gpl-2.0.html
+
+Embed a live, animated three.ws 3D AI agent anywhere in the block editor. No build step, no API key, SRI-pinned to an immutable release.
+
+== Description ==
+
+three.ws builds `<agent-3d>`, a custom HTML element that renders a rigged, animated 3D AI agent in one script tag: a Three.js viewer, voice I/O, an LLM brain, persistent memory and an extensible skill system, all opt-in. This plugin adds a block (and a shortcode for the classic editor) that drops the element into any post, page, or template with no code.
+
+Set one of:
+
+* **On-chain URI** (`src`), e.g. `agent://base/42`
+* **Agent ID** (`agentId`, optionally with a `chainId`), a three.ws backend account or a CAIP-10 on-chain ID
+* **Model URL** (`modelUrl`), a bare GLB for an ad-hoc agent with no backing account
+
+...then pick a background (transparent, dark, light) and framing (full or portrait).
+
+The loader script is fetched from three.ws's immutable CDN (`https://three.ws/agent-3d/<version>/agent-3d.js`) with a `integrity` hash pinned to the exact release this plugin ships against, so a CDN or MITM swap is refused by the browser rather than silently served. No three.ws account, API key, or outbound request beyond that script and the agent's own GLB/manifest is required to render a public agent.
+
+Full attribute reference: https://three.ws/docs/web-component
+
+= Shortcode =
+
+For the classic editor, widgets, or any template that cannot use the block:
+
+`[three_ws_agent src="agent://base/42" background="dark" framing="portrait"]`
+
+`[three_ws_agent model="https://three.ws/avatars/default.glb" height="600px"]`
+
+== Installation ==
+
+1. Upload the plugin to the `/wp-content/plugins/` directory, or install it through the WordPress plugin directory.
+2. Activate the plugin through the 'Plugins' screen in WordPress.
+3. Add the "three.ws Agent" block from the block inserter (category: Embeds), or use the `[three_ws_agent]` shortcode.
+
+== Frequently Asked Questions ==
+
+= Do I need a three.ws account? =
+
+No. A bare model URL or a public agent ID renders with no account, no API key, and no backend calls beyond the agent's own manifest and GLB.
+
+= Does this load any tracking script? =
+
+No. The only script this plugin enqueues is the `<agent-3d>` loader from three.ws's CDN, pinned by SRI hash to one exact release.
+
+= Can I use this outside the block editor? =
+
+Yes, the `[three_ws_agent]` shortcode renders the identical output and works in the classic editor, widgets, and theme templates via `do_shortcode()`.
+
+== Changelog ==
+
+= 1.0.0 =
+* Initial release: block, shortcode, SRI-pinned to agent-3d 1.5.2.
+
+== Upgrade Notice ==
+
+= 1.0.0 =
+Initial release.
diff --git a/integrations/wordpress/three-ws-agent/three-ws-agent.php b/integrations/wordpress/three-ws-agent/three-ws-agent.php
new file mode 100755
index 000000000..ffd5f7c76
--- /dev/null
+++ b/integrations/wordpress/three-ws-agent/three-ws-agent.php
@@ -0,0 +1,29 @@
+<?php
+/**
+ * Plugin Name: three.ws Agent
+ * Plugin URI: https://three.ws/embed
+ * Description: Embed a live, animated three.ws 3D AI agent anywhere in the block editor, SRI-pinned to an immutable release. No build step, no API key.
+ * Version: 1.0.0
+ * Requires at least: 6.4
+ * Requires PHP: 7.4
+ * Author: three.ws
+ * Author URI: https://three.ws
+ * License: GPL-2.0-or-later
+ * License URI: https://www.gnu.org/licenses/gpl-2.0.html
+ * Text Domain: three-ws-agent
+ *
+ * @package ThreeWsAgent
+ */
+
+if (!defined('ABSPATH')) {
+ exit;
+}
+
+define('THREE_WS_AGENT_PLUGIN_FILE', __FILE__);
+define('THREE_WS_AGENT_PLUGIN_DIR', plugin_dir_path(__FILE__));
+define('THREE_WS_AGENT_PLUGIN_URL', plugin_dir_url(__FILE__));
+
+require_once THREE_WS_AGENT_PLUGIN_DIR . 'includes/pinned-release.php';
+require_once THREE_WS_AGENT_PLUGIN_DIR . 'includes/render.php';
+require_once THREE_WS_AGENT_PLUGIN_DIR . 'includes/block.php';
+require_once THREE_WS_AGENT_PLUGIN_DIR . 'includes/shortcode.php';
diff --git a/package.json b/package.json
index 45fc8d376..b07fea819 100644
--- a/package.json
+++ b/package.json
@@ -259,7 +259,7 @@
"audit:route-shadowing": "node scripts/audit-route-shadowing.mjs",
"audit:handlers": "node scripts/audit-empty-handlers.mjs",
"audit:x402-catalog": "node scripts/audit-x402-catalog.mjs",
- "gate": "npm run check:conflicts && npm run check:claude && npm run check:cli-scripts && npm run check:vendored && npm run check:model-viewer && npm run check:gcloudignore && npm run check:fetch-timeouts && npm run check:tdz-bootstrap && npm run check:event && npm run check:cron-syntax && npm run check:home-matrix && npm run check:studio-openapi && npm run test:gate && npm run test:gate-3d && npm run audit:mcp && npm run audit:mcp-golden && npm run audit:mcp-safety && npm run audit:mcp-catalog && npm run check:mcp-counts && npm run test:mcp-surface && npm run check:mcp-catalog && npm run audit:mcp-listing && npm run audit:mcp-surfaces && npm run check:pay-skills && npm run audit:routes && npm run audit:handlers && npm run audit:pages && npm run audit:links && npm run check:awesome && npm run check:prompt-library && npm run audit:docs && npm run check:docs-freshness && npm run audit:upstreams && npm run check:tutorials && npm run audit:hidden-guard && npm run audit:inline-handlers && npm run audit:x402-catalog && npm run audit:tokens && npm run audit:states && npm run audit:motion-tokens && npm run audit:guards && npm run audit:tour-atlas && npm run check:ios-icons && npm run check:macos-icon && npm run check:apple-widget && npm run check:ios-app && npm run check:windows-widget && npm run check:announce && npm run i18n:home && npm run check:skills-seed && npm run check:openai-skills && npm run check:skills-pack && npm run check:skill-repos && npm run check:well-known-skills && npm run check:postman-collection && npm run check:openai-fields && npm run audit:motion && npm run audit:tour-global && npm run check:doc-media && npm run check:images && npm run audit:route-shadowing",
+ "gate": "npm run check:conflicts && npm run check:claude && npm run check:cli-scripts && npm run check:vendored && npm run check:model-viewer && npm run check:gcloudignore && npm run check:fetch-timeouts && npm run check:tdz-bootstrap && npm run check:event && npm run check:cron-syntax && npm run check:home-matrix && npm run check:studio-openapi && npm run test:gate && npm run test:gate-3d && npm run audit:mcp && npm run audit:mcp-golden && npm run audit:mcp-safety && npm run audit:mcp-catalog && npm run check:mcp-counts && npm run test:mcp-surface && npm run check:mcp-catalog && npm run audit:mcp-listing && npm run audit:mcp-surfaces && npm run check:pay-skills && npm run audit:routes && npm run audit:handlers && npm run audit:pages && npm run audit:links && npm run check:awesome && npm run check:prompt-library && npm run audit:docs && npm run check:docs-freshness && npm run audit:upstreams && npm run check:tutorials && npm run audit:hidden-guard && npm run audit:inline-handlers && npm run audit:x402-catalog && npm run audit:tokens && npm run audit:states && npm run audit:motion-tokens && npm run audit:guards && npm run audit:tour-atlas && npm run check:ios-icons && npm run check:macos-icon && npm run check:apple-widget && npm run check:ios-app && npm run check:windows-widget && npm run check:announce && npm run i18n:home && npm run check:skills-seed && npm run check:openai-skills && npm run check:skills-pack && npm run check:skill-repos && npm run check:well-known-skills && npm run check:postman-collection && npm run check:openai-fields && npm run audit:motion && npm run audit:tour-global && npm run check:doc-media && npm run check:images && npm run audit:route-shadowing && npm run check:site-builder-embeds",
"test:stake-program": "node scripts/test-event-markets-stake.mjs",
"test:gate-3d": "vitest run tests/glb-canonicalize.test.js tests/animation-retarget.test.js tests/animation-retarget-rest-pollution.test.js tests/viewer-framing.test.js",
"audit:mcp-golden": "node scripts/audit-mcp-golden.mjs",
@@ -366,6 +366,8 @@
"build:artifact": "vite build --config vite.config.artifact.js",
"publish:lib": "node scripts/publish-lib.mjs",
"check:sri-pins": "node scripts/check-sri-pins.mjs",
+ "build:site-builder-embeds": "node scripts/build-site-builder-embeds.mjs",
+ "check:site-builder-embeds": "node scripts/check-site-builder-embeds.mjs",
"publish:packages": "node scripts/publish-packages.mjs",
"publish:packages:dry": "node scripts/publish-packages.mjs --dry-run",
"publish:queue:dry": "node scripts/publish-npm-queue.mjs",
diff --git a/scripts/build-site-builder-embeds.mjs b/scripts/build-site-builder-embeds.mjs
new file mode 100644
index 000000000..8a663e380
--- /dev/null
+++ b/scripts/build-site-builder-embeds.mjs
@@ -0,0 +1,25 @@
+#!/usr/bin/env node
+// Writes the pinned-release constant file for each site-builder embed
+// (WordPress, Framer, Webflow) from data/agent-3d-releases.json.
+//
+// npm run build:site-builder-embeds
+//
+// Run this after `npm run release:lib` cuts a new <agent-3d> version so every
+// embed picks up the new version and hash in one pass. check:site-builder-embeds
+// fails the build if a committed file drifts from what this would generate.
+
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { readLedger } from './lib/agent-3d-releases.mjs';
+import { GENERATED_FILES, latestPin } from './lib/site-builder-pin.mjs';
+
+const root = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+const pin = latestPin(readLedger(root));
+
+for (const { path, render } of GENERATED_FILES) {
+ const abs = resolve(root, path);
+ mkdirSync(dirname(abs), { recursive: true });
+ writeFileSync(abs, render(pin));
+ console.log(`[site-builder-embeds] wrote ${path} (agent-3d ${pin.version})`);
+}
diff --git a/scripts/check-site-builder-embeds.mjs b/scripts/check-site-builder-embeds.mjs
new file mode 100644
index 000000000..d9686f190
--- /dev/null
+++ b/scripts/check-site-builder-embeds.mjs
@@ -0,0 +1,33 @@
+#!/usr/bin/env node
+// Holds the committed WordPress/Framer/Webflow pinned-release files to the
+// <agent-3d> release ledger. Fails if a file is missing or stale; `--fix`
+// regenerates them (same thing npm run build:site-builder-embeds does).
+
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { readLedger } from './lib/agent-3d-releases.mjs';
+import { GENERATED_FILES, latestPin } from './lib/site-builder-pin.mjs';
+
+const root = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+const fix = process.argv.includes('--fix');
+const pin = latestPin(readLedger(root));
+
+let problems = 0;
+for (const { path, render } of GENERATED_FILES) {
+ const abs = resolve(root, path);
+ const expected = render(pin);
+ const actual = existsSync(abs) ? readFileSync(abs, 'utf8') : null;
+ if (actual === expected) continue;
+ problems++;
+ if (fix) {
+ mkdirSync(dirname(abs), { recursive: true });
+ writeFileSync(abs, expected);
+ console.log(`[site-builder-embeds] rewrote ${path} (agent-3d ${pin.version})`);
+ } else {
+ console.error(`[site-builder-embeds] ${path} does not match the ledger (agent-3d ${pin.version}); run: npm run build:site-builder-embeds`);
+ }
+}
+
+if (problems && !fix) process.exit(1);
+if (!problems) console.log(`[site-builder-embeds] ${GENERATED_FILES.length} pinned-release file(s) match agent-3d ${pin.version}`);
diff --git a/scripts/lib/agent-3d-releases.mjs b/scripts/lib/agent-3d-releases.mjs
index 9003c93db..00ce8a6c8 100644
--- a/scripts/lib/agent-3d-releases.mjs
+++ b/scripts/lib/agent-3d-releases.mjs
@@ -99,7 +99,7 @@ export async function fetchReleaseFile(ledger, version, file, { cacheDir = null
// Where documentation lives. Tests are deliberately absent: their fixtures pin
// wrong hashes on purpose to exercise stale-pin detection.
-export const PIN_ROOTS = ['docs', 'specs', 'blog', 'examples', '.agents/skills', 'public/skills', 'README.md', 'packages'];
+export const PIN_ROOTS = ['docs', 'specs', 'blog', 'examples', '.agents/skills', 'public/skills', 'README.md', 'packages', 'integrations'];
const PIN_EXT = /\.(md|mdx|html?|txt)$/i;
const SKIP_DIRS = new Set(['node_modules', 'dist', 'test', 'tests', '.git']);
diff --git a/scripts/lib/site-builder-pin.mjs b/scripts/lib/site-builder-pin.mjs
new file mode 100644
index 000000000..6cf21e909
--- /dev/null
+++ b/scripts/lib/site-builder-pin.mjs
@@ -0,0 +1,62 @@
+// Generates the one pinned <agent-3d> release constant each site-builder embed
+// (WordPress, Framer, Webflow) loads from, so `npm run build:site-builder-embeds`
+// after a new `npm run release:lib` updates every embed in one pass. The ledger
+// (data/agent-3d-releases.json) stays the single source of truth; nothing here
+// hardcodes a version or a hash.
+
+import { releasedVersions } from './agent-3d-releases.mjs';
+
+const WARN = 'Generated by scripts/build-site-builder-embeds.mjs from data/agent-3d-releases.json. Do not edit by hand: run `npm run build:site-builder-embeds`.';
+
+/** The newest released version plus its file hashes and CDN URLs. */
+export function latestPin(ledger) {
+ const versions = releasedVersions(ledger);
+ const version = versions[versions.length - 1];
+ if (!version) throw new Error('data/agent-3d-releases.json has no releases');
+ const integrity = ledger.releases[version].integrity;
+ const base = `https://three.ws/agent-3d/${version}`;
+ return {
+ version,
+ jsUrl: `${base}/agent-3d.js`,
+ jsIntegrity: integrity['agent-3d.js'],
+ umdUrl: `${base}/agent-3d.umd.cjs`,
+ umdIntegrity: integrity['agent-3d.umd.cjs'],
+ };
+}
+
+export function renderPhp(pin) {
+ return `<?php
+/**
+ * ${WARN}
+ *
+ * @package ThreeWsAgent
+ */
+
+if (!defined('ABSPATH')) {
+ exit;
+}
+
+define('THREE_WS_AGENT3D_VERSION', '${pin.version}');
+define('THREE_WS_AGENT3D_JS_URL', '${pin.jsUrl}');
+define('THREE_WS_AGENT3D_JS_INTEGRITY', '${pin.jsIntegrity}');
+define('THREE_WS_AGENT3D_UMD_URL', '${pin.umdUrl}');
+define('THREE_WS_AGENT3D_UMD_INTEGRITY', '${pin.umdIntegrity}');
+`;
+}
+
+export function renderTs(pin) {
+ return `// ${WARN}
+
+export const AGENT3D_VERSION = '${pin.version}';
+export const AGENT3D_JS_URL = '${pin.jsUrl}';
+export const AGENT3D_JS_INTEGRITY = '${pin.jsIntegrity}';
+export const AGENT3D_UMD_URL = '${pin.umdUrl}';
+export const AGENT3D_UMD_INTEGRITY = '${pin.umdIntegrity}';
+`;
+}
+
+export const GENERATED_FILES = [
+ { path: 'integrations/wordpress/three-ws-agent/includes/pinned-release.php', render: renderPhp },
+ { path: 'integrations/framer/src/pinned-release.ts', render: renderTs },
+ { path: 'integrations/webflow/src/pinned-release.ts', render: renderTs },
+];
diff --git a/scripts/wordpress-plugin-check.sh b/scripts/wordpress-plugin-check.sh
new file mode 100755
index 000000000..b9159a219
--- /dev/null
+++ b/scripts/wordpress-plugin-check.sh
@@ -0,0 +1,85 @@
+#!/usr/bin/env bash
+# Runs the official WordPress Plugin Check plugin against
+# integrations/wordpress/three-ws-agent/ in a disposable local WordPress,
+# entirely in Docker. No account, no network access from WordPress itself
+# beyond installing Plugin Check from wordpress.org.
+#
+# scripts/wordpress-plugin-check.sh
+#
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+PLUGIN_DIR="$ROOT/integrations/wordpress/three-ws-agent"
+NET="three-ws-plugin-check"
+DB="three-ws-plugin-check-db"
+WP="three-ws-plugin-check-wp"
+
+cleanup() {
+ docker rm -f "$WP" "$DB" >/dev/null 2>&1 || true
+ docker network rm "$NET" >/dev/null 2>&1 || true
+}
+trap cleanup EXIT
+
+cleanup
+docker network create "$NET" >/dev/null
+
+docker run -d --name "$DB" --network "$NET" \
+ -e MYSQL_ROOT_PASSWORD=root \
+ -e MYSQL_DATABASE=wordpress \
+ -e MYSQL_USER=wordpress \
+ -e MYSQL_PASSWORD=wordpress \
+ mysql:8 >/dev/null
+
+docker run -d --name "$WP" --network "$NET" \
+ -e WORDPRESS_DB_HOST="$DB" \
+ -e WORDPRESS_DB_USER=wordpress \
+ -e WORDPRESS_DB_PASSWORD=wordpress \
+ -e WORDPRESS_DB_NAME=wordpress \
+ -v "$PLUGIN_DIR:/var/www/html/wp-content/plugins/three-ws-agent" \
+ wordpress:php8.2-apache >/dev/null
+
+echo "[plugin-check] waiting for MySQL..."
+for _ in $(seq 1 30); do
+ if docker exec "$DB" mysqladmin ping -h 127.0.0.1 -uroot -proot --silent >/dev/null 2>&1; then break; fi
+ sleep 2
+done
+
+echo "[plugin-check] waiting for WordPress..."
+for _ in $(seq 1 30); do
+ if docker exec "$WP" curl -sf -o /dev/null http://localhost/wp-admin/install.php; then break; fi
+ sleep 2
+done
+
+wpcli() {
+ docker run --rm --network "$NET" \
+ --volumes-from "$WP" \
+ -e WORDPRESS_DB_HOST="$DB" \
+ -e WORDPRESS_DB_USER=wordpress \
+ -e WORDPRESS_DB_PASSWORD=wordpress \
+ -e WORDPRESS_DB_NAME=wordpress \
+ --workdir /var/www/html \
+ wordpress:cli-php8.2 wp --allow-root "$@"
+}
+
+echo "[plugin-check] fixing wp-content permissions (the apache and cli images run as different uids)..."
+docker exec "$WP" chmod -R 0777 /var/www/html/wp-content
+
+echo "[plugin-check] installing WordPress core..."
+wpcli core install \
+ --url="http://localhost" \
+ --title="three.ws Plugin Check" \
+ --admin_user=admin \
+ --admin_password=admin \
+ --skip-email
+
+echo "[plugin-check] WordPress version: $(wpcli core version)"
+
+echo "[plugin-check] activating three-ws-agent..."
+wpcli plugin activate three-ws-agent
+
+echo "[plugin-check] installing the official Plugin Check plugin from wordpress.org..."
+wpcli plugin install plugin-check --activate
+
+echo "[plugin-check] running wp plugin check three-ws-agent..."
+wpcli plugin check three-ws-agent --format=table