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.

docs(vendoring): exempt the third_party/ reference trees from the house guards

nirholascb1ec268074f
diff --git a/.gitignore b/.gitignore
index 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.json
index 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.md
index 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.md
new file mode 100644
index 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 lives
diff --git a/eslint.config.js b/eslint.config.js
index 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 config
diff --git a/scripts/audit-docs.mjs b/scripts/audit-docs.mjs
index 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.mjs
index 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,