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
fix(satellites): run the GLB quality gate on Node 24 and fail export when the committed bundle drifts from source
nirholas4a5839fa4ea2
diff --git a/STRUCTURE.md b/STRUCTURE.mdindex dc327aba2..8fc615fdf 100644--- a/STRUCTURE.md+++ b/STRUCTURE.md@@ -143,7 +143,7 @@ bottom.| Premium vanity inventory (sell pre-ground addresses) | [public/vanity/premium/](public/vanity/premium/index.html) `→ /vanity/premium`, batch grinder [workers/vanity-grinder/](workers/vanity-grinder), store [api/_lib/vanity-inventory-store.js](api/_lib/vanity-inventory-store.js), sell [api/x402/vanity-premium.js](api/x402/vanity-premium.js), replenish [api/cron/vanity-inventory-replenish.js](api/cron/vanity-inventory-replenish.js) | In-repo · GCP spot CPU | Long (4–5+ char) brandable Solana addresses ground ahead of time on cheap spot CPU, sealed at rest (AES-256-GCM or GCP-KMS envelope, [api/_lib/vanity-vault.js](api/_lib/vanity-vault.js)), and sold from stock via x402 — priced by rarity ($1–$50) on `vanity-premium`, or by fixed 4–5 char tiers ($2.50/$10) directly through [`/api/x402/vanity`](docs/vanity.md#tier-1--live-grinder) (instant delivery, `source:"inventory"`) and the [pump-launch vanity upsell](docs/pump-launcher.md) — delivered exactly once, ciphertext destroyed on delivery. An hourly cron watches stock and fires a fresh grind batch (Cloud Run Job) when low. Free `vanity_premium` MCP browse tool. Runbook: [docs/ops/gcp-credits.md](docs/ops/gcp-credits.md) || Embed examples | [examples/](examples) | In-repo | `embed-test.html`, `web-component.html`, `two-agents.html`, `minimal.html`, [agent-native-3d/](examples/agent-native-3d) (below). Also: [skills/](examples/skills) (six installable skill bundles), [three-concierge/](examples/three-concierge) (Trinity, reference agent for manifest spec agent-manifest/0.2), [monicas-apartment/](examples/monicas-apartment) (walkable first-person Three.js scene demo, added 2026-07-17), [agenc-task-roundtrip/](examples/agenc-task-roundtrip) (end-to-end AgenC task flow on Solana devnet), [metamask-agent-wallet/](examples/metamask-agent-wallet) (single-page demo giving an agent a server-side MetaMask wallet), [pump-fun-agent/](examples/pump-fun-agent) (example manifest composing the four production pump.fun skills), [paid-mcp-server/](examples/paid-mcp-server) (an MCP server whose tools charge per call in USDC on Solana over x402: one free orientation tool, one paid glTF/GLB inspector, 15 tests, added 2026-07-30) || Examples satellite repo (public developer front door) | Exporter [scripts/export-satellites.mjs](scripts/export-satellites.mjs) (`npm run export:satellites`), runbook [docs/ops/examples-repo-export.md](docs/ops/examples-repo-export.md), curated source [examples/](examples) + the published `@three-ws/*` SDKs | Built and gated in-repo; publishing is owner-gated (the `three-ws` GitHub org does not exist yet) | Assembles the public `three-ws/examples` repo from this monorepo as a strictly ONE-WAY export: the monorepo is the only source of truth, the satellite history is disposable, and it is never pulled, fetched, or merged from (same rule as the retired 3D-Agent mirror). No CI is involved (GitHub Actions are unavailable here), so the export runs locally from the push routine. Every relative reference is resolved against its real location and routed by where it lands rather than regex-swept: to the shipped file, to another exported unit (so an agent manifest's skill `uri` still resolves), to the published package on jsDelivr, to the live docs page, or to a monorepo permalink. A four-stage smoke gate then aborts the export on any failure, because a broken public example is anti-marketing: structure (no reference escapes or dangles, no `file:` dep survives), registry (every pinned `@three-ws/*` version exists on npm), install (`npm install` plus each example's own check command), and links (every `https://three.ws` URL reachable). On success it stamps a single-parent git history into the staging tree and prints the org-creation and push commands; it never touches a remote. Examples referencing a crypto project other than $THREE are held out of the manifest under the CLAUDE.md commit gate (`pump-fun-agent`, `three-concierge`, `agenc-task-roundtrip`). |-| Product-led growth satellites | Canonical source [satellites/](satellites), exporter [scripts/export-growth-satellites.mjs](scripts/export-growth-satellites.mjs) (`npm run export:growth-satellites`), runbook [docs/ops/growth-satellite-export.md](docs/ops/growth-satellite-export.md) | Built and gated in-repo; destination repositories require the `nirholas` owner identity | Two focused acquisition surfaces whose first experience is deliberately smaller than this monorepo: [satellites/agent-starter/](satellites/agent-starter) is a responsive, Codespaces-ready live `<agent-3d>` page with real motion, speech, a keyless create command, a ten-minute learning path, and a structural check; [satellites/glb-quality-gate/](satellites/glb-quality-gate) is a Node 20 GitHub Action that discovers changed GLBs through the pull-request API, reads base/head bytes without a checkout, runs the published `@three-ws/glb-diff` engine, upserts a PR report, writes the workflow summary, and gates at a configurable severity. The exporter installs locked dependencies, runs real tests, builds the committed Action bundle, copies Apache legal files, and stamps one clean history per destination. The monorepo remains the only source of truth. |+| Product-led growth satellites | Canonical source [satellites/](satellites), exporter [scripts/export-growth-satellites.mjs](scripts/export-growth-satellites.mjs) (`npm run export:growth-satellites`), runbook [docs/ops/growth-satellite-export.md](docs/ops/growth-satellite-export.md) | Built and gated in-repo; destination repositories require the `nirholas` owner identity | Two focused acquisition surfaces whose first experience is deliberately smaller than this monorepo: [satellites/agent-starter/](satellites/agent-starter) is a responsive, Codespaces-ready live `<agent-3d>` page with real motion, speech, a keyless create command, a ten-minute learning path, and a structural check; [satellites/glb-quality-gate/](satellites/glb-quality-gate) is a Node 24 GitHub Action that discovers changed GLBs through the pull-request API, reads base/head bytes without a checkout, runs the published `@three-ws/glb-diff` engine, upserts a PR report, writes the workflow summary, and gates at a configurable severity. The exporter installs locked dependencies, runs real tests, builds the committed Action bundle, copies Apache legal files, and stamps one clean history per destination. The monorepo remains the only source of truth. || Agent-native 3D + embeddable distribution | MCP tool [api/_mcp/tools/agents.js](api/_mcp/tools/agents.js) (`attach_avatar_to_agent`); shared oEmbed provider [api/agent-oembed.js](api/agent-oembed.js) `→ /api/oembed` + builder [api/_lib/embed.js](api/_lib/embed.js) (`forgeEmbedTarget`, shared by `get_embed_code` in [api/_mcp/tools/embed.js](api/_mcp/tools/embed.js)); Forge share page oEmbed discovery [api/forge-share.js](api/forge-share.js) `→ /forge/share/:id`; distribution snippet builders [src/forge-embed-snippets.js](src/forge-embed-snippets.js) + panel [src/forge-embed-panel.js](src/forge-embed-panel.js); autonomous demo [examples/agent-native-3d/](examples/agent-native-3d) | In-repo | Closes the loop: create → own → discover/remix → **use everywhere**. `attach_avatar_to_agent` gives a registered agent identity a persistent body (chains into `register_agent` for on-chain identity + `anchor_provenance` for a signed authenticity credential). Any Forge creation now unfurls via real oEmbed (paste `/forge/share/:id` into Notion/Discord/Slack) with the same `type:rich` iframe payload `get_embed_code` returns via MCP. The Forge "Embed this model" panel hands out five real distribution flavours from one GLB — iframe, `<model-viewer>`, `<agent-3d>`, a `@three-ws/page-agent` talking guide, and a `@three-ws/walk` companion — all built from one shared, pure snippet module so every surface stays byte-identical. `examples/agent-native-3d/run.mjs` drives the full agent-native chain live against `/api/mcp-studio` (mesh_forge → rig_mesh → create_agent_persona → persona_say → get_agent_persona → every distribution snippet) with zero mocks and a documented, logged fallback if the shared free-tier generation lane is rate-limited at run time. Spec: [specs/EMBED_SPEC.md](specs/EMBED_SPEC.md#share-routes-on-chain-agents). Docs: [docs/mcp.md#attach_avatar_to_agent](docs/mcp.md#attach_avatar_to_agent). Roadmap prompt 10 (closes the roadmap campaign). || Animation pipeline | [public/animations/](public/animations) + [scripts/build-animations.mjs](scripts/build-animations.mjs) | In-repo | Mixamo source FBX + GLB retargeting pipeline · see [docs/3d-asset-pipeline.md](docs/3d-asset-pipeline.md) || Procedural animation (runtime IK layers) | [src/procedural/](src/procedural) — analytic two-bone IK [two-bone-ik.js](src/procedural/two-bone-ik.js), gaze [look-at.js](src/procedural/look-at.js), terrain foot planting [foot-plant.js](src/procedural/foot-plant.js), drift-free re-application [pose-baseline.js](src/procedural/pose-baseline.js) | Live | Post-mixer layers that do what no baked clip can: the chest/neck/head chain turns toward a world point, and each foot lands on its own patch of uneven ground. Rig-agnostic via `canonicalNodeMapFromObject`; an unsupported rig reports `enabled === false` and no-ops. Wired into the corner companion ([walk-sdk/src/companion.js](walk-sdk/src/companion.js) `_updateGaze`), the walkaround world ([src/walk.js](src/walk.js) `rebuildFootPlant`), and agent avatars ([src/agent-avatar.js](src/agent-avatar.js) `_applyLookTarget` — which is what finally makes `setLookTarget()` and the `LOOK_AT` action move the rig). Ambient idle motion (breathing/blink/saccade/weight-shift) stays in [src/idle-animation.js](src/idle-animation.js). Docs: [docs/procedural-animation.md](docs/procedural-animation.md). Tests: [tests/procedural-anim.test.js](tests/procedural-anim.test.js), [tests/agent-avatar-look-target.test.js](tests/agent-avatar-look-target.test.js) |diff --git a/satellites/glb-quality-gate/action.yml b/satellites/glb-quality-gate/action.ymlindex 93bddcbc6..e715b57ed 100644--- a/satellites/glb-quality-gate/action.yml+++ b/satellites/glb-quality-gate/action.yml@@ -23,5 +23,5 @@ outputs:files-checked:description: Number of changed GLB files included in the report.runs:- using: node20+ using: node24main: dist/index.jsdiff --git a/scripts/export-growth-satellites.mjs b/scripts/export-growth-satellites.mjsindex ac05fc1d7..38fcf2f79 100644--- a/scripts/export-growth-satellites.mjs+++ b/scripts/export-growth-satellites.mjs@@ -73,6 +73,35 @@ function copyProject(target) {return destination;}+function listFiles(root, path = root) {+ return readdirSync(path, { withFileTypes: true }).flatMap((entry) => {+ const child = join(path, entry.name);+ return entry.isDirectory() ? listFiles(root, child) : [relative(root, child)];+ });+}++// The Action runs the committed bundle, so the monorepo copy must be exactly what a clean build+// of the locked dependencies produces. A mismatch means the published runtime would differ from+// reviewed source: an unresolved optional import, a stale chunk, or a dependency the build found+// outside the satellite's own lockfile.+function assertBundleMatchesSource(target, destination) {+ const committed = join(REPO, target.source, 'dist');+ const built = join(destination, 'dist');+ const committedFiles = listFiles(committed).sort();+ const builtFiles = listFiles(built).sort();+ const drift = [...new Set([...committedFiles, ...builtFiles])].filter(+ (file) =>+ !committedFiles.includes(file) ||+ !builtFiles.includes(file) ||+ !readFileSync(join(committed, file)).equals(readFileSync(join(built, file))),+ );+ if (drift.length) {+ throw new Error(+ `${target.name} committed dist/ differs from a clean build (${drift.join(', ')}); run npm ci && npm run build in ${target.source} and commit dist/`,+ );+ }+}+function verifyProject(target, destination) {if (OFFLINE) return;run('npm', ['ci', '--ignore-scripts'], destination);@@ -82,6 +111,7 @@ function verifyProject(target, destination) {if (!existsSync(join(destination, 'dist', 'index.js'))) {throw new Error(`${target.name} build did not produce dist/index.js`);}+ assertBundleMatchesSource(target, destination);}}