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
docs(vendoring): exempt the third_party/ reference trees from the house guards
nirholascb1ec268074f
diff --git a/.gitignore b/.gitignoreindex fbc1e54f6..30246c991 100644--- a/.gitignore+++ b/.gitignore@@ -601,8 +601,8 @@ marketing/product-demo/.smoke/# The unanchored `demo/` rule above (NVIDIA TRELLIS local outputs) matches at any# depth, so it also swallowed 578 files of runnable demos inside the vendored MIT-# trees under vendor/. Those demos are the substance of the Design+Code agent-# skills (each SKILL.md points at its demo/ as the worked example), so re-include-# the vendored copies explicitly. Scoped to vendor/ so the TRELLIS rule keeps-# working everywhere else.-!vendor/**/demo/+# trees under third_party/. Those demos are the substance of the Design+Code+# agent skills (each SKILL.md points at its demo/ as the worked example), so+# re-include the vendored copies explicitly. Scoped to third_party/ so the+# TRELLIS rule keeps working everywhere else.+!third_party/**/demo/diff --git a/.i18nrc.json b/.i18nrc.jsonindex 2d2812ed8..7c41eccaa 100644--- a/.i18nrc.json+++ b/.i18nrc.json@@ -198,7 +198,8 @@"exclude": ["**/node_modules/**","public/chat/**",- "src/scene-studio/vendor/**"+ "src/scene-studio/vendor/**",+ "third_party/**"]},"doNotTranslate": [diff --git a/STRUCTURE.md b/STRUCTURE.mdindex a53065b62..641fab65f 100644--- a/STRUCTURE.md+++ b/STRUCTURE.md@@ -468,6 +468,7 @@ array. Runbook: [docs/contributing.md](docs/contributing.md#publishing-packages-- **Cross-chain SDKs** — [sdk/](sdk), [solana-agent-sdk/](solana-agent-sdk), [agent-payments-sdk/](agent-payments-sdk), [agent-protocol-sdk/](agent-protocol-sdk)- **MCP integration** — [mcp-server/](mcp-server), [mcp-bridge/](mcp-bridge)- **Specs & protocol docs** — [specs/](specs)+- **Vendored third-party reference trees**: [third_party/](third_party/README.md) (complete upstream MIT source kept to read, not to build: the Design+Code agent-skill corpus and the ThreeUI Community component library). Read-only, excluded from ESLint, i18n extraction, and the Cloud Build upload. Distinct from the `vendor/` directories inside a surface ([src/scene-studio/vendor/](src/scene-studio/vendor), `public/vendor/`, `pages/ibm/vendor/`), which are third-party code we actually ship.- **Frontend pages** — [src/](src), [pages/](pages), [public/](public)- **Tests** — [tests/](tests)diff --git a/docs/vendored-design-libraries.md b/docs/vendored-design-libraries.mdnew file mode 100644index 000000000..1737046b8--- /dev/null+++ b/docs/vendored-design-libraries.md@@ -0,0 +1,158 @@+# Vendored design libraries++Two complete MIT source trees from [Meng To](https://github.com/MengTo) live in+[third_party/](../third_party): the **ThreeUI Community** component catalog and the+**Design+Code agent skills** collection. This page is the three.ws-side guide to+them: what is in each, what it is good for here, and how to actually run one.++The vendoring contract itself (why they are byte-identical, which guards skip+them, how to re-sync) is [third_party/README.md](../third_party/README.md). Read that+before you change anything under `third_party/`. The short version: never edit a file+in place, and never import from `third_party/` at runtime.++## Why these two are in the repo++three.ws is a Three.js platform whose product surfaces are galleries of+interactive 3D things, and whose agents are driven by portable `SKILL.md`+folders. These are the two best-maintained open-source collections of exactly+those two artifacts, both MIT, both by the same author.++- **ThreeUI** answers "what should a live component catalog feel like, and what+ do 103 finished WebGL components look like when someone else already built+ them."+- **The skills collection** answers "what does a mature public agent-skill+ library look like," and gives 132 ready workflows for design, web, and game+ work that our own agents can load today.++## third_party/threeui++`@designcodeio/threeui` 1.2.0. The login-free Community edition of+[threeui.com](https://threeui.com): 50 parent components across 111 routes, 141+free variant records, plus the catalog application that renders them.++```+third_party/threeui/+ src/package-components/ 103 published components, one .ts per component+ src/shaders/ 48 shader and scene studies (the raw HTML sources)+ src/components/ the catalog shell: browse grid, controls, source tabs+ packages/ the publishable @designcodeio/threeui package + CLI+ public/ built demo pages and the catalog's source-code index+```++### Run it++The tree carries its own dependency set and is not an npm workspace of this+repo, so install inside it:++```bash+cd third_party/threeui+npm install+npm run dev+```++`npm run build:site` runs the upstream typecheck, public-boundary audit, Vite+build and build audit together, which is the check to run if you ever sync the+tree and want to know the copy is intact.++### Use a component++The library is published, so a three.ws surface that wants one takes the npm+dependency rather than reaching into `third_party/`:++```bash+npm install @designcodeio/threeui+```++```tsx+import { AtTheHorizon } from "@designcodeio/threeui";+import "@designcodeio/threeui/style.css";++export function Hero() {+ return <AtTheHorizon />;+}+```++Our own frontend is vanilla JS modules rather than React, so the more common+path here is the second one: open the matching study under+`third_party/threeui/src/shaders/<name>/` (each is a self-contained HTML document+with its own shaders and scene setup), read how the effect is built, and+implement it in the three.ws surface that needs it. Keep the MIT attribution+with anything you carry across.++### What is worth studying first++- `src/components/` is a working answer to the gallery problem our+ [/gallery](https://three.ws/gallery), [/examples](https://three.ws/examples)+ and [/marketplace](https://three.ws/marketplace) pages all solve separately:+ one shell that gives every catalog entry a live renderer, a controls panel, a+ variant picker and a copyable source tab.+- `src/shaders/bookshelf/`, `src/shaders/japanese-tower/` and+ `src/shaders/landscape/` are complete Three.js scenes in single documents,+ which is the same shape as our embeddable avatar demos.+- `packages/` shows a component library published from inside a catalog repo:+ relevant every time we graduate a surface out of this monorepo (see+ [package-extraction.md](./package-extraction.md)).++## third_party/designcode-agent-skills++132 `SKILL.md` folders in the same Agent Skills format as+[.agents/skills/](../.agents/skills), each with its references, scripts, and a+runnable `demo/`.++| Group | Skills | What it covers |+|---|---:|---|+| `web-design` | 88 | scroll storytelling, GSAP ScrollTrigger, marquees, orbit controls, particle fields, layout systems, animation debugging |+| `game-development` | 20 | playable Three.js systems, gameplay QA, game architecture |+| `codex` | 19 | the capture-to-prompt workflows: video to super prompt, HTML to interaction prompts, stitched full-page capture, daily UI inspiration |+| `ui` | 3 | design-first UI prompting |+| `media` | 2 | image sourcing for a build |++### Load one into a session++A skill folder is portable by design, so pointing an agent at the path is+enough:++```bash+cat third_party/designcode-agent-skills/agent-skills/codex/video-to-superprompt/SKILL.md+```++To make one available to Claude Code as a first-class skill on this machine,+copy the folder (not a symlink, so the skill and its references travel together)+into your skills directory:++```bash+cp -r third_party/designcode-agent-skills/agent-skills/codex/video-to-superprompt \+ ~/.claude/skills/video-to-superprompt+```++They are deliberately NOT copied into `.agents/skills/`. That directory is the+three.ws skill pack we publish: `scripts/build-skills-pack.mjs` generates+`skills-pack.json` and `SKILLS.md` from it, the `three-ws-core` plugin ships it,+and `workers/okx-chat-bot` copies it into its image. Mixing a third party's 132+skills into our published pack would misattribute them and add 90 MB to that+worker's build context. Read [docs/agent-skills.md](./agent-skills.md) for how+our own pack is authored.++### What is worth studying first++- `agent-skills/codex/video-to-superprompt/` is the flagship: it turns a screen+ recording of an interface into a prompt detailed enough to one-shot the HTML.+ Directly useful for building three.ws pages from a reference.+- `agent-skills/game-development/` maps closely onto the `/play` world and the+ multiplayer surfaces, both of which are Three.js gameplay systems.+- Every skill's `demo/` is the worked example. That is why the repo's+ unanchored `demo/` ignore rule had to be negated for `third_party/`: a skill+ without its demo is a description instead of a proof.++## Licence++Both trees are MIT, copyright 2026 Meng To. The licence text ships with each+tree and must stay with it, and with anything derived from it.++## See also++- [third_party/README.md](../third_party/README.md): the vendoring contract, guard+ exemptions, and the re-sync procedure+- [docs/agent-skills.md](./agent-skills.md): how the three.ws skill pack itself+ is authored and published+- [STRUCTURE.md](../STRUCTURE.md): where every three.ws surface livesdiff --git a/eslint.config.js b/eslint.config.jsindex b94489e98..debb10ee4 100644--- a/eslint.config.js+++ b/eslint.config.js@@ -31,6 +31,9 @@ export default [// Any directory named `vendor` holds third-party code we don't own// and must not lint (e.g. extensions/*/vendor/readability.js).'**/vendor/**',+ // Complete vendored upstream trees kept as reference material and+ // never built or shipped. See third_party/README.md.+ 'third_party/**','**/*.bundle.js','public/dashboard/avaturn-sdk.js',// Self-contained sub-projects with their own ESLint flat configdiff --git a/scripts/audit-docs.mjs b/scripts/audit-docs.mjsindex bf73183c8..9217debf7 100644--- a/scripts/audit-docs.mjs+++ b/scripts/audit-docs.mjs@@ -63,6 +63,16 @@ const SKIP_DIRS = new Set([// links are lifted verbatim from files that live elsewhere, so auditing it// reports thousands of "missing" targets that exist at their real paths.'exports',+ // Vendored third-party source trees (vendor/). Their Markdown is upstream's,+ // its relative links resolve against the upstream repo layout, and we never+ // edit it, so auditing it reports the vendor's own docs as our drift. The+ // three.ws docs that point INTO vendor/ are still audited from this side.+ 'vendor',+ // Complete upstream trees kept as reference material (third_party/). Same+ // reasoning as `vendor` above: the Markdown is upstream's, its relative+ // links resolve against the upstream repo layout, and we never edit it.+ // See third_party/README.md.+ 'third_party',]);// Generated aggregates: their links are produced by a generator, not authored.const SKIP_FILES = new Set(['docs/ALL.md', 'docs/EVERYTHING.md', 'EVERYTHING.md', 'CHANGELOG.md']);@@ -285,6 +295,8 @@ const UNPUBLISHED_DOCS = new Map([['bnb-vault', 'owner-gated: names a crypto project other than $THREE'],['bnb-world', 'owner-gated: names a crypto project other than $THREE'],['btn-pill-migration', 'internal: one-time component migration map'],+ ['product-demo', 'internal: the runbook for recording the marketing demo film, not a reader-facing product doc'],+ ['vendored-design-libraries', 'internal: orientation for the third_party/ reference trees, which ship to no reader-facing surface'],['build', 'internal: build and deploy integrity runbook'],['clip-director', 'internal: content strategy'],['coin-launches', 'owner-gated: names a crypto project other than $THREE'],diff --git a/scripts/check-rules.mjs b/scripts/check-rules.mjsindex 380834fb6..a10c70338 100644--- a/scripts/check-rules.mjs+++ b/scripts/check-rules.mjs@@ -81,6 +81,15 @@ const SKIP = [// holding them to house prose rules reports the vendor's copyright line as// commented-out code. Our own code that loads them is still scanned./^public\/vendor\//,+ // Whole third-party source trees under third_party/ (MIT drops kept+ // byte-identical to upstream so a re-sync stays a diff instead of a merge).+ // The prose there is the upstream author's, and rewriting its typography to+ // satisfy a house rule would make every future sync conflict on punctuation+ // (the current drop carries 1625 em-dashes that are upstream's to fix). Our+ // own code and docs that USE them are still scanned, and so is this tree by+ // scripts/check-secrets.mjs: a third party's leaked key is still a leaked key+ // in our history. Provenance and licences: third_party/README.md.+ /^third_party\//,/\.min\.(js|css)$/,/package-lock\.json$/,/\.(png|jpg|jpeg|gif|webp|glb|gltf|bin|woff2?|ttf|mp4|wasm|ico|svg)$/i,