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.
JavaScript 3d-generationai-agentsanimationavatardigital-humangenerative-aiglbgltfimage-to-3dllmmcpmcp-servermodel-context-protocolsolanatext-to-3dthreejsweb-componentswebglwebxrx402
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.mdnew file mode 100755index 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.jsonnew file mode 100755index 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.phpnew file mode 100755index 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.jsnew file mode 100755index 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.cssnew file mode 100755index 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.phpnew file mode 100755index 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.phpnew file mode 100755index 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.phpnew file mode 100755index 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.phpnew file mode 100755index 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.txtnew file mode 100755index 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.phpnew file mode 100755index 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.jsonindex 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.mjsnew file mode 100644index 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.mjsnew file mode 100644index 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.mjsindex 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.mjsnew file mode 100644index 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.shnew file mode 100755index 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