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 Framer code component for <agent-3d>, pinned to the release ledger
nirholas9c36dd51fb4f
diff --git a/integrations/framer/README.md b/integrations/framer/README.mdnew file mode 100644index 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.htmlnew file mode 100644index 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.tsxnew file mode 100644index 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.jsonnew file mode 100644index 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.jsonnew file mode 100644index 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.tsxnew file mode 100644index 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.tsxnew file mode 100644index 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.tsnew file mode 100644index 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.jsonnew file mode 100644index 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.mjsnew file mode 100644index 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.jsnew file mode 100644index 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');+ }+ });+});