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 Framer code component for <agent-3d>, pinned to the release ledger

nirholas9c36dd51fb4f
diff --git a/integrations/framer/README.md b/integrations/framer/README.md
new file mode 100644
index 000000000..8579d6706
--- /dev/null
+++ b/integrations/framer/README.md
@@ -0,0 +1,60 @@
+# three.ws Agent (Framer code component)
+
+A Framer code component that embeds [`<agent-3d>`](../../docs/web-component.md): a live, animated
+3D AI agent in one script tag. No build step beyond Framer's own canvas bundler.
+
+## Layout
+
+| File | Role |
+|---|---|
+| [`src/pinned-release.ts`](src/pinned-release.ts) | **Generated.** The `<agent-3d>` version, CDN URL and SRI hash this component 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. |
+| [`src/Agent3DView.tsx`](src/Agent3DView.tsx) | The actual rendering logic: loads the pinned CDN script once per page, mounts `<agent-3d>`, and drives its attributes from props. Deliberately has no `"framer"` import, so it can be rendered and tested with plain React outside Framer's canvas. |
+| [`src/Agent3D.tsx`](src/Agent3D.tsx) | The Framer-specific wrapper: `addPropertyControls()` over `Agent3DView`, exposing On-chain URI, Agent ID, Chain ID, Model URL, Background, Framing, Poster and Autoplay in the Properties panel. |
+
+## Why split the component in two
+
+The `framer` npm package (the one that exports `addPropertyControls`/`ControlType`) ships types
+only; its import only resolves inside Framer's own canvas bundler, never in Node, Vite, or
+Playwright. Splitting the real rendering logic into `Agent3DView.tsx` (no `"framer"` import) means
+that logic can be typechecked and rendered in a real browser outside Framer, while `Agent3D.tsx`
+stays a thin wrapper that only Framer ever has to resolve.
+
+## SRI pin
+
+`src/pinned-release.ts` 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 WordPress plugin's `pinned-release.php` and the Webflow component's `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
+
+```bash
+# from the repo root
+npm install --prefix integrations/framer # once, or after a dependency change
+npm run typecheck --prefix integrations/framer # tsc --noEmit against the real "framer" types
+npx playwright test tests/e2e/agent-3d-framer-component.spec.js
+```
+
+The Playwright spec starts this package's own `vite.config.mjs` (a standalone dev server; the
+repo root's `vite.config.js` sets its own static-site JSX factory, which would break real React
+JSX) and mounts the real `Agent3DView` with plain `ReactDOM` at
+[`harness/index.html`](harness/index.html). It loads the real pinned CDN script from
+`https://three.ws/<version>/agent-3d.js` and a real production avatar GLB (no mocks), and asserts
+a WebGL canvas actually renders inside `<agent-3d>`'s shadow DOM.
+
+## Using it in Framer
+
+1. Open a Framer project, open the code file panel (or a Code Component file), and paste in
+ `src/pinned-release.ts`, `src/Agent3DView.tsx`, and `src/Agent3D.tsx` (in that order, as three
+ files of those names).
+2. Drag the "three.ws Agent" component onto the canvas. Set an On-chain URI (`agent://base/42`),
+ an Agent ID, or a Model URL in the Properties panel.
+3. Pick a Background and Framing, and optionally a Poster image and Autoplay.
+
+No three.ws account or API key is required to render a public agent or a bare model URL.
+
+## Framer Marketplace submission
+
+Submission (publishing under an owner-controlled Framer account) is an owner action: see
+[`marketing/growth/submissions/site-builders.md`](../../marketing/growth/submissions/site-builders.md).
diff --git a/integrations/framer/harness/index.html b/integrations/framer/harness/index.html
new file mode 100644
index 000000000..f2873739f
--- /dev/null
+++ b/integrations/framer/harness/index.html
@@ -0,0 +1,20 @@
+<!doctype html>
+<html>
+<head>
+<meta charset="utf-8">
+<title>agent-3d Framer component harness</title>
+<!--
+ Playwright-only fixture for tests/e2e/agent-3d-framer-component.spec.js.
+ Mounts the real Agent3DView (the framer-free component Agent3D.tsx wraps)
+ with plain ReactDOM, served by this package's own vite.config.mjs so the
+ repo root's vhtml JSX transform never touches it. Loads the real pinned
+ agent-3d CDN release (integrations/framer/src/pinned-release.ts) and a
+ real production avatar GLB, no mocks.
+-->
+<style>html,body{margin:0}</style>
+</head>
+<body>
+<div id="root"></div>
+<script type="module" src="./main.tsx"></script>
+</body>
+</html>
diff --git a/integrations/framer/harness/main.tsx b/integrations/framer/harness/main.tsx
new file mode 100644
index 000000000..ea544e841
--- /dev/null
+++ b/integrations/framer/harness/main.tsx
@@ -0,0 +1,16 @@
+import { createRoot } from 'react-dom/client';
+import { Agent3DView } from '../src/Agent3DView';
+
+const params = new URLSearchParams(window.location.search);
+const root = createRoot(document.getElementById('root') as HTMLElement);
+
+root.render(
+ <Agent3DView
+ model={params.get('model') || 'https://three.ws/avatars/default.glb'}
+ background={(params.get('background') as 'transparent' | 'dark' | 'light') || 'dark'}
+ framing={(params.get('framing') as 'full' | 'portrait') || 'full'}
+ autoplay
+ width="480px"
+ height="480px"
+ />,
+);
diff --git a/integrations/framer/package-lock.json b/integrations/framer/package-lock.json
new file mode 100644
index 000000000..9169b691d
--- /dev/null
+++ b/integrations/framer/package-lock.json
@@ -0,0 +1,185 @@
+{
+ "name": "@three-ws/framer-agent-3d",
+ "version": "1.0.0",
+ "lockfileVersion": 3,
+ "requires": true,
+ "packages": {
+ "": {
+ "name": "@three-ws/framer-agent-3d",
+ "version": "1.0.0",
+ "license": "MIT",
+ "devDependencies": {
+ "@types/react": "^18.2.0",
+ "framer": "3.0.4",
+ "react": "^18.2.0",
+ "react-dom": "^18.2.0",
+ "typescript": "^5.4.0"
+ },
+ "peerDependencies": {
+ "react": "^18.2.0",
+ "react-dom": "^18.2.0"
+ }
+ },
+ "node_modules/@types/prop-types": {
+ "version": "15.7.15",
+ "resolved": "https://registry.npmjs.org/@types/prop-types/-/prop-types-15.7.15.tgz",
+ "integrity": "sha512-F6bEyamV9jKGAFBEmlQnesRPGOQqS2+Uwi0Em15xenOxHaf2hv6L8YCVn3rPdPJOiJfPiCnLIRyvwVaqMY3MIw==",
+ "dev": true,
+ "license": "MIT"
+ },
+ "node_modules/@types/react": {
+ "version": "18.3.31",
+ "resolved": "https://registry.npmjs.org/@types/react/-/react-18.3.31.tgz",
+ "integrity": "sha512-vfEqpXTvwT91yhmwdfouStN2hSKwTvyRs8qpLfADyrq/kxDw0hZM7Wk9Ug1FELj8hIby+S/+kQCSRFF32nv2Qw==",
+ "dev": true,
+ "license": "MIT",
+ "dependencies": {
+ "@types/prop-types": "*",
+ "csstype": "^3.2.2"
+ }
+ },
+ "node_modules/csstype": {
+ "version": "3.2.3",
+ "resolved": "https://registry.npmjs.org/csstype/-/csstype-3.2.3.tgz",
+ "integrity": "sha512-z1HGKcYy2xA8AGQfwrn0PAy+PB7X/GSj3UVJW9qKyn43xWa+gl5nXmU4qqLMRzWVLFC8KusUX8T/0kCiOYpAIQ==",
+ "dev": true,
+ "license": "MIT"
+ },
+ "node_modules/framer": {
+ "version": "3.0.4",
+ "resolved": "https://registry.npmjs.org/framer/-/framer-3.0.4.tgz",
+ "integrity": "sha512-O6RyM77iGBg3p2NuUbSHvPnuS5TZ1zJHzSC2GO4RelICT5sgUfXWfDWqpvULTETTCCxbg7vv8EuZp9bHRkr96w==",
+ "dev": true,
+ "license": "MIT",
+ "dependencies": {
+ "framer-motion": "12.34.3"
+ },
+ "peerDependencies": {
+ "react": "^18.2.0"
+ }
+ },
+ "node_modules/framer-motion": {
+ "version": "12.34.3",
+ "resolved": "https://registry.npmjs.org/framer-motion/-/framer-motion-12.34.3.tgz",
+ "integrity": "sha512-v81ecyZKYO/DfpTwHivqkxSUBzvceOpoI+wLfgCgoUIKxlFKEXdg0oR9imxwXumT4SFy8vRk9xzJ5l3/Du/55Q==",
+ "dev": true,
+ "license": "MIT",
+ "dependencies": {
+ "motion-dom": "^12.34.3",
+ "motion-utils": "^12.29.2",
+ "tslib": "^2.4.0"
+ },
+ "peerDependencies": {
+ "@emotion/is-prop-valid": "*",
+ "react": "^18.0.0 || ^19.0.0",
+ "react-dom": "^18.0.0 || ^19.0.0"
+ },
+ "peerDependenciesMeta": {
+ "@emotion/is-prop-valid": {
+ "optional": true
+ },
+ "react": {
+ "optional": true
+ },
+ "react-dom": {
+ "optional": true
+ }
+ }
+ },
+ "node_modules/js-tokens": {
+ "version": "4.0.0",
+ "resolved": "https://registry.npmjs.org/js-tokens/-/js-tokens-4.0.0.tgz",
+ "integrity": "sha512-RdJUflcE3cUzKiMqQgsCu06FPu9UdIJO0beYbPhHN4k6apgJtifcoCtT9bcxOpYBtpD2kCM6Sbzg4CausW/PKQ==",
+ "dev": true,
+ "license": "MIT"
+ },
+ "node_modules/loose-envify": {
+ "version": "1.4.0",
+ "resolved": "https://registry.npmjs.org/loose-envify/-/loose-envify-1.4.0.tgz",
+ "integrity": "sha512-lyuxPGr/Wfhrlem2CL/UcnUc1zcqKAImBDzukY7Y5F/yQiNdko6+fRLevlw1HgMySw7f611UIY408EtxRSoK3Q==",
+ "dev": true,
+ "license": "MIT",
+ "dependencies": {
+ "js-tokens": "^3.0.0 || ^4.0.0"
+ },
+ "bin": {
+ "loose-envify": "cli.js"
+ }
+ },
+ "node_modules/motion-dom": {
+ "version": "12.43.0",
+ "resolved": "https://registry.npmjs.org/motion-dom/-/motion-dom-12.43.0.tgz",
+ "integrity": "sha512-azKON4d9S65PEoFUiQTMTgPheEmzf2QngdRc50AKfJp9Q9mmcBVw22c8eMq9k8kxOFHdL7+WZY7N/5F/lwiDag==",
+ "dev": true,
+ "license": "MIT",
+ "dependencies": {
+ "motion-utils": "^12.39.0"
+ }
+ },
+ "node_modules/motion-utils": {
+ "version": "12.39.0",
+ "resolved": "https://registry.npmjs.org/motion-utils/-/motion-utils-12.39.0.tgz",
+ "integrity": "sha512-8nadJAJjTtqRkmRF36FoJTrywK9nnFmnPwnSMyxaOCU7GDjN9RTMJIxx9De8ErM+vpPhMccr/6fo5WciyQLnMQ==",
+ "dev": true,
+ "license": "MIT"
+ },
+ "node_modules/react": {
+ "version": "18.3.1",
+ "resolved": "https://registry.npmjs.org/react/-/react-18.3.1.tgz",
+ "integrity": "sha512-wS+hAgJShR0KhEvPJArfuPVN1+Hz1t0Y6n5jLrGQbkb4urgPE/0Rve+1kMB1v/oWgHgm4WIcV+i7F2pTVj+2iQ==",
+ "dev": true,
+ "license": "MIT",
+ "dependencies": {
+ "loose-envify": "^1.1.0"
+ },
+ "engines": {
+ "node": ">=0.10.0"
+ }
+ },
+ "node_modules/react-dom": {
+ "version": "18.3.1",
+ "resolved": "https://registry.npmjs.org/react-dom/-/react-dom-18.3.1.tgz",
+ "integrity": "sha512-5m4nQKp+rZRb09LNH59GM4BxTh9251/ylbKIbpe7TpGxfJ+9kv6BLkLBXIjjspbgbnIBNqlI23tRnTWT0snUIw==",
+ "dev": true,
+ "license": "MIT",
+ "dependencies": {
+ "loose-envify": "^1.1.0",
+ "scheduler": "^0.23.2"
+ },
+ "peerDependencies": {
+ "react": "^18.3.1"
+ }
+ },
+ "node_modules/scheduler": {
+ "version": "0.23.2",
+ "resolved": "https://registry.npmjs.org/scheduler/-/scheduler-0.23.2.tgz",
+ "integrity": "sha512-UOShsPwz7NrMUqhR6t0hWjFduvOzbtv7toDH1/hIrfRNIDBnnBWd0CwJTGvTpngVlmwGCdP9/Zl/tVrDqcuYzQ==",
+ "dev": true,
+ "license": "MIT",
+ "dependencies": {
+ "loose-envify": "^1.1.0"
+ }
+ },
+ "node_modules/tslib": {
+ "version": "2.8.1",
+ "resolved": "https://registry.npmjs.org/tslib/-/tslib-2.8.1.tgz",
+ "integrity": "sha512-oJFu94HQb+KVduSUQL7wnpmqnfmLsOA/nAh6b6EH0wCEoK0/mPeXU6c3wKDV83MkOuHPRHtSXKKU99IBazS/2w==",
+ "dev": true,
+ "license": "0BSD"
+ },
+ "node_modules/typescript": {
+ "version": "5.9.3",
+ "resolved": "https://registry.npmjs.org/typescript/-/typescript-5.9.3.tgz",
+ "integrity": "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw==",
+ "dev": true,
+ "license": "Apache-2.0",
+ "bin": {
+ "tsc": "bin/tsc",
+ "tsserver": "bin/tsserver"
+ },
+ "engines": {
+ "node": ">=14.17"
+ }
+ }
+ }
+}
diff --git a/integrations/framer/package.json b/integrations/framer/package.json
new file mode 100644
index 000000000..470a5a932
--- /dev/null
+++ b/integrations/framer/package.json
@@ -0,0 +1,22 @@
+{
+ "name": "@three-ws/framer-agent-3d",
+ "version": "1.0.0",
+ "private": true,
+ "description": "Framer code component embedding <agent-3d>, three.ws's live animated 3D AI agent.",
+ "license": "MIT",
+ "files": ["src/Agent3D.tsx", "src/Agent3DView.tsx", "src/pinned-release.ts"],
+ "scripts": {
+ "typecheck": "tsc --noEmit -p tsconfig.json"
+ },
+ "devDependencies": {
+ "@types/react": "^18.2.0",
+ "framer": "3.0.4",
+ "react": "^18.2.0",
+ "react-dom": "^18.2.0",
+ "typescript": "^5.4.0"
+ },
+ "peerDependencies": {
+ "react": "^18.2.0",
+ "react-dom": "^18.2.0"
+ }
+}
diff --git a/integrations/framer/src/Agent3D.tsx b/integrations/framer/src/Agent3D.tsx
new file mode 100644
index 000000000..99d8d25cd
--- /dev/null
+++ b/integrations/framer/src/Agent3D.tsx
@@ -0,0 +1,82 @@
+// Framer code component: paste this file (and Agent3DView.tsx and
+// pinned-release.ts alongside it) into a Framer project's code file panel, or
+// publish it as a Framer package. Only runs inside Framer's canvas/published
+// site, where the "framer" module resolves; the real rendering logic lives in
+// Agent3DView.tsx so it can be tested outside Framer. See README.md.
+import { addPropertyControls, ControlType } from 'framer';
+import { Agent3DView } from './Agent3DView';
+
+/**
+ * @framerSupportedLayoutWidth any
+ * @framerSupportedLayoutHeight any
+ */
+export default function Agent3D(props: {
+ agent: string;
+ agentId: string;
+ chainId: string;
+ model: string;
+ background: 'transparent' | 'dark' | 'light';
+ framing: 'full' | 'portrait';
+ // Framer's Image control resolves to an asset object ({ src, alt, ... }),
+ // not a bare URL.
+ poster?: { src: string };
+ autoplay: boolean;
+ width?: number;
+ height?: number;
+}) {
+ return <Agent3DView {...props} poster={props.poster?.src} width="100%" height="100%" />;
+}
+
+addPropertyControls(Agent3D, {
+ agent: {
+ type: ControlType.String,
+ title: 'On-chain URI',
+ placeholder: 'agent://base/42',
+ description: 'Takes priority over Agent ID and Model URL.',
+ },
+ agentId: {
+ type: ControlType.String,
+ title: 'Agent ID',
+ placeholder: 'a_abc123',
+ description: 'Backend account ID or CAIP-10 ID. Used when On-chain URI is empty.',
+ },
+ chainId: {
+ type: ControlType.String,
+ title: 'Chain ID',
+ placeholder: '8453',
+ description: 'Paired with a numeric Agent ID.',
+ hidden: (props) => !props.agentId,
+ },
+ model: {
+ type: ControlType.String,
+ title: 'Model URL',
+ placeholder: 'https://three.ws/avatars/default.glb',
+ description: 'Bare GLB for an ad-hoc agent. Used when On-chain URI and Agent ID are both empty.',
+ hidden: (props) => Boolean(props.agent || props.agentId),
+ },
+ background: {
+ type: ControlType.Enum,
+ title: 'Background',
+ options: ['transparent', 'dark', 'light'],
+ optionTitles: ['Transparent', 'Dark', 'Light'],
+ defaultValue: 'transparent',
+ },
+ framing: {
+ type: ControlType.Enum,
+ title: 'Framing',
+ options: ['full', 'portrait'],
+ optionTitles: ['Full', 'Portrait'],
+ defaultValue: 'full',
+ },
+ poster: {
+ type: ControlType.Image,
+ title: 'Poster',
+ description: 'Shown while the model loads.',
+ },
+ autoplay: {
+ type: ControlType.Boolean,
+ title: 'Autoplay',
+ description: 'Boot immediately instead of waiting for the component to scroll into view.',
+ defaultValue: false,
+ },
+});
diff --git a/integrations/framer/src/Agent3DView.tsx b/integrations/framer/src/Agent3DView.tsx
new file mode 100644
index 000000000..75ab451d4
--- /dev/null
+++ b/integrations/framer/src/Agent3DView.tsx
@@ -0,0 +1,130 @@
+// The actual rendering logic behind the Framer code component. Deliberately
+// framer-free (no "framer" import) so it can be unit/E2E tested with plain
+// React outside Framer's canvas, which is the only place the "framer" module
+// resolves. Agent3D.tsx is the thin Framer-specific wrapper around this.
+import { useEffect, useRef } from 'react';
+import { AGENT3D_JS_INTEGRITY, AGENT3D_JS_URL } from './pinned-release';
+
+declare global {
+ // eslint-disable-next-line @typescript-eslint/no-namespace
+ namespace JSX {
+ interface IntrinsicElements {
+ 'agent-3d': React.DetailedHTMLProps<React.HTMLAttributes<HTMLElement>, HTMLElement>;
+ }
+ }
+}
+
+export type Agent3DViewProps = {
+ /** On-chain URI, e.g. "agent://base/42". Takes priority over agentId and model. */
+ agent?: string;
+ /** Backend account id or CAIP-10 agent id. Used when agent is empty. */
+ agentId?: string;
+ /** Chain id, paired with a numeric agentId. */
+ chainId?: string;
+ /** Bare GLB URL for an ad-hoc agent, used when agent and agentId are both empty. */
+ model?: string;
+ background?: 'transparent' | 'dark' | 'light';
+ framing?: 'full' | 'portrait';
+ poster?: string;
+ /** Skip the IntersectionObserver wait and boot on connect (the "eager" attribute). */
+ autoplay?: boolean;
+ width?: string | number;
+ height?: string | number;
+};
+
+let loaderPromise: Promise<void> | null = null;
+
+/**
+ * Injects the pinned <agent-3d> loader script once per page, SRI-verified
+ * against the exact release this component ships against. Safe to call from
+ * multiple mounted instances; the browser refuses the script outright if its
+ * bytes ever stop matching AGENT3D_JS_INTEGRITY.
+ */
+function ensureLoader(): Promise<void> {
+ if (loaderPromise) return loaderPromise;
+ if (customElements.get('agent-3d')) {
+ loaderPromise = Promise.resolve();
+ return loaderPromise;
+ }
+ loaderPromise = new Promise((resolve, reject) => {
+ const script = document.createElement('script');
+ script.type = 'module';
+ script.src = AGENT3D_JS_URL;
+ script.integrity = AGENT3D_JS_INTEGRITY;
+ script.crossOrigin = 'anonymous';
+ script.onload = () => resolve();
+ script.onerror = () => reject(new Error(`three.ws: failed to load the pinned agent-3d loader from ${AGENT3D_JS_URL}`));
+ document.head.appendChild(script);
+ });
+ return loaderPromise;
+}
+
+export function Agent3DView(props: Agent3DViewProps) {
+ const {
+ agent = '',
+ agentId = '',
+ chainId = '',
+ model = '',
+ background = 'transparent',
+ framing = 'full',
+ poster = '',
+ autoplay = false,
+ width = '100%',
+ height = '100%',
+ } = props;
+
+ const ref = useRef<HTMLElement>(null);
+
+ useEffect(() => {
+ ensureLoader().catch((err) => console.error(err));
+ }, []);
+
+ useEffect(() => {
+ const el = ref.current;
+ if (!el) return;
+
+ el.removeAttribute('src');
+ el.removeAttribute('agent-id');
+ el.removeAttribute('chain-id');
+ el.removeAttribute('body');
+
+ if (agent) {
+ el.setAttribute('src', agent);
+ } else if (agentId) {
+ el.setAttribute('agent-id', agentId);
+ if (chainId) el.setAttribute('chain-id', chainId);
+ } else if (model) {
+ el.setAttribute('body', model);
+ }
+
+ el.setAttribute('background', background);
+ el.setAttribute('framing', framing);
+ if (poster) el.setAttribute('poster', poster);
+ else el.removeAttribute('poster');
+ if (autoplay) el.setAttribute('eager', '');
+ else el.removeAttribute('eager');
+ }, [agent, agentId, chainId, model, background, framing, poster, autoplay]);
+
+ if (!agent && !agentId && !model) {
+ return (
+ <div
+ style={{
+ width,
+ height,
+ display: 'flex',
+ alignItems: 'center',
+ justifyContent: 'center',
+ border: '1px dashed #999',
+ color: '#777',
+ fontSize: 13,
+ textAlign: 'center',
+ padding: 8,
+ }}
+ >
+ Set an agent, agent ID, or model URL
+ </div>
+ );
+ }
+
+ return <agent-3d ref={ref as React.RefObject<HTMLElement>} style={{ display: 'block', width, height }} />;
+}
diff --git a/integrations/framer/src/pinned-release.ts b/integrations/framer/src/pinned-release.ts
new file mode 100644
index 000000000..cf8c19046
--- /dev/null
+++ b/integrations/framer/src/pinned-release.ts
@@ -0,0 +1,7 @@
+// 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`.
+
+export const AGENT3D_VERSION = '1.5.2';
+export const AGENT3D_JS_URL = 'https://three.ws/agent-3d/1.5.2/agent-3d.js';
+export const AGENT3D_JS_INTEGRITY = 'sha384-KdAiFRsdcCbQMu4O5rkoL8hOEYLkmrdpf9ELd7jro+9NTNipWis3oqqFLll7v20Q';
+export const AGENT3D_UMD_URL = 'https://three.ws/agent-3d/1.5.2/agent-3d.umd.cjs';
+export const AGENT3D_UMD_INTEGRITY = 'sha384-z74vjNbQ8KKXBZHL6JFhl4h45B+InYbzbV8ArjZSgzR+ATWOEthqu0S/eadTA0XC';
diff --git a/integrations/framer/tsconfig.json b/integrations/framer/tsconfig.json
new file mode 100644
index 000000000..3913263d9
--- /dev/null
+++ b/integrations/framer/tsconfig.json
@@ -0,0 +1,15 @@
+{
+ "compilerOptions": {
+ "target": "ES2020",
+ "lib": ["ES2020", "DOM"],
+ "module": "ESNext",
+ "moduleResolution": "Bundler",
+ "jsx": "react-jsx",
+ "strict": true,
+ "skipLibCheck": true,
+ "esModuleInterop": true,
+ "forceConsistentCasingInFileNames": true,
+ "noEmit": true
+ },
+ "include": ["src/**/*.ts", "src/**/*.tsx"]
+}
diff --git a/integrations/framer/vite.config.mjs b/integrations/framer/vite.config.mjs
new file mode 100644
index 000000000..9bf14702c
--- /dev/null
+++ b/integrations/framer/vite.config.mjs
@@ -0,0 +1,13 @@
+import { defineConfig } from 'vite';
+
+// Standalone dev server for harness/index.html (tests/e2e/agent-3d-framer-component.spec.js).
+// The repo root's vite.config.js sets esbuild.jsxFactory to its own static-site
+// "vhtml" helper, which would silently break real React JSX. This package
+// renders inside Framer's own canvas bundler in production, so its local
+// harness needs its own config with the real React automatic runtime instead.
+export default defineConfig({
+ esbuild: {
+ jsx: 'automatic',
+ jsxImportSource: 'react',
+ },
+});
diff --git a/tests/e2e/agent-3d-framer-component.spec.js b/tests/e2e/agent-3d-framer-component.spec.js
new file mode 100644
index 000000000..258f8737d
--- /dev/null
+++ b/tests/e2e/agent-3d-framer-component.spec.js
@@ -0,0 +1,77 @@
+import { test, expect } from '@playwright/test';
+import { spawn } from 'node:child_process';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+// Work order 094: proves integrations/framer/src/Agent3DView.tsx (the
+// framer-free component that Agent3D.tsx wraps with addPropertyControls)
+// actually renders a live <agent-3d> in a real browser. The "framer" npm
+// package is types-only and only resolves inside Framer's own canvas, so
+// this can't go through Framer directly; Agent3DView.tsx has no "framer"
+// import, so it mounts here with plain ReactDOM instead.
+//
+// This package's own vite.config.mjs (not the repo root's, which sets a
+// static-site "vhtml" JSX factory) runs a standalone dev server for
+// integrations/framer/harness/index.html. The harness loads the real pinned
+// agent-3d CDN release from data/agent-3d-releases.json and a real
+// production avatar GLB: no mocks, no interception.
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+const FRAMER_DIR = path.join(HERE, '..', '..', 'integrations', 'framer');
+const PORT = 3171;
+const ORIGIN = `http://localhost:${PORT}`;
+
+function spawnHarnessServer() {
+ const child = spawn('npx', ['vite', '--port', String(PORT), '--strictPort'], {
+ cwd: FRAMER_DIR,
+ stdio: ['ignore', 'pipe', 'pipe'],
+ });
+ let log = '';
+ child.stdout.on('data', (d) => (log += d.toString()));
+ child.stderr.on('data', (d) => (log += d.toString()));
+ return { child, getLog: () => log };
+}
+
+async function waitForServer(url, timeoutMs) {
+ const deadline = Date.now() + timeoutMs;
+ while (Date.now() < deadline) {
+ try {
+ const res = await fetch(url);
+ if (res.ok) return;
+ } catch {
+ // not up yet
+ }
+ await new Promise((resolve) => setTimeout(resolve, 250));
+ }
+ throw new Error(`harness dev server never came up at ${url}`);
+}
+
+test.describe('agent-3d Framer code component (real pinned CDN release)', () => {
+ test.setTimeout(60_000);
+
+ test('Agent3DView mounts a live, rendering <agent-3d> with the pinned release', async ({ page }) => {
+ const server = spawnHarnessServer();
+ try {
+ await waitForServer(`${ORIGIN}/harness/index.html`, 30_000);
+
+ const errors = [];
+ page.on('pageerror', (err) => errors.push(String(err?.message || err)));
+
+ await page.goto(`${ORIGIN}/harness/index.html`, { waitUntil: 'domcontentloaded' });
+
+ await expect(page.locator('agent-3d')).toBeAttached();
+ await expect(page.locator('agent-3d')).toHaveAttribute('body', 'https://three.ws/avatars/default.glb');
+ await expect(page.locator('agent-3d')).toHaveAttribute('background', 'dark');
+
+ // It really boots against the pinned CDN script: a WebGL canvas
+ // renders inside the element's shadow DOM.
+ await expect
+ .poll(() => page.evaluate(() => document.querySelector('agent-3d')?.shadowRoot?.querySelector('canvas')))
+ .toBeTruthy();
+
+ expect(errors, `page errors: ${errors.join(' | ')}\nvite log:\n${server.getLog()}`).toEqual([]);
+ } finally {
+ server.child.kill('SIGTERM');
+ }
+ });
+});