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.
Changelog & Versioning
This document covers how three.ws is versioned, what has changed across releases, and how to upgrade safely. It is aimed at developers pinning the SDK or CDN bundle.
Looking for what shipped this week? Day-to-day product updates are published continuously on the live changelog at three.ws/changelog (also available as JSON and RSS). The versioned entries below track the platform/SDK release history rather than every product change.
The two JSON feeds
/changelog.json is the complete history and is the documented public feed: every
entry since the site existed, newest first, and it keeps that contract. It also
grows forever, and on 2026-09-08 it was 3,552 entries and 870 KB over the wire.
/changelog-recent.json is the newest 150 of the same entries in the same
envelope, plus two fields that say so:
{
"generated_at": "2026-09-08T17:18:00.000Z",
"site": { "name": "three.ws", "url": "https://three.ws" },
"total": 3552,
"complete": false,
"full_feed": "/changelog.json",
"entries": [ { "date": "2026-09-08", "type": "update", "title": "…", "summary": "…", "link": "/…", "tags": ["improvement"] } ]
}
total is how many entries exist; complete says whether this file is all of
them. Read this one when you want what shipped lately (a "what's new" strip, a
notification, a single entry someone linked to) and fall back to
/changelog.json when complete is false and you need older history. Both are
generated by npm run build:pages from data/pages.json + data/changelog.json,
and both are served with cache-control: public, max-age=600.
three.ws/changelog itself paints from the small feed and fetches the full one
only when a reader filters or asks for older updates.
GitHub Releases
Once a month the changelog also goes out as a GitHub Release,
which reaches every watcher and stargazer of the repository through GitHub's own feed.
scripts/github-release.mjs builds the notes from data/changelog.json as it stood at the
commit production runs (read GET /api/version for it), keeps only entries that pass the X
lane's public filter (data/changelog-x-filter.json), and drops any entry naming a $TICKER
other than $THREE:
node scripts/github-release.mjs --from 2026-08-29 --to 2026-09-30 \
--tag v1.5.2 --target 774ca7287 --title "1.5.2, September 2026" # preview
# add --apply to publish; --exclude-terms <file> takes a JSON array of project
# names to leave out, kept outside the repo so no committed file names them
The first one, v1.5.2, covers 2026-08-29 to 2026-09-30. Start the next window the day after the previous one ended.
Versioning Policy
three.ws follows Semantic Versioning (MAJOR.MINOR.PATCH):
| Segment | When it increments | Example |
|---|---|---|
| Major | Breaking changes to the web component API, agent manifest schema, or SDK public exports | 2.0.0 |
| Minor | New backwards-compatible features | 1.6.0 |
| Patch | Bug fixes with no API changes | 1.5.1 |
Current platform version: 1.5.2
Current SDK version (@three-ws/sdk): 0.2.1
The SDK is versioned independently from the platform. A platform patch release does not necessarily bump the SDK version if no public API changed.
Breaking Changes Policy
Breaking changes are rare and follow a defined process:
- Deprecation notice — the feature or behavior is marked deprecated in the preceding minor version. A console warning is emitted at runtime where applicable.
- Migration guide — published before the breaking release so you can update before upgrading.
- Grace period — old behavior is supported for at least one full minor version after the deprecation notice.
What counts as a breaking change:
- Removing or renaming a web component attribute or property
- Changing the agent manifest schema in a non-backwards-compatible way (field removal or rename)
- Changing an API endpoint path, method, or response shape
- Removing a public export from
@three-ws/sdk
Adding new optional fields to manifests, new optional API response properties, or new SDK exports is not a breaking change.
Changelog
Entries are organized by release. Categories follow Keep a Changelog conventions.
[1.5.1] — 2026-04-27
Added
feat: star field canvas and perspective grid on landing page for visual depthfeat: features page with scroll-driven animations and responsive layoutfeat: parallax hero with additional depth layers and updated gallery layoutdocs: comprehensive documentation for Introduction, Quick Start, Architecture Overview, 3D Viewer, and Agent System Overviewdocs: widget types and configurations reference (widgets.md)docs: custom parallax layer guide
Fixed
fix: on-chain deploy now correctly persists agent URI and serves realagentURIfrom the ERC-8004 registryfix: service worker no longer intercepts all navigations and servesindex.htmlfor non-page requestsfix: routing paths invercel.jsoncorrected;home.htmlentry added toappConfigfix:/agent/:idroute now resolves to bundledagent-home.htmlinstead of broken public copyfix: double-mount of agent sidebar on app boot eliminatedfix: boot order restored for/app?agent=:iddeep linksfix: auto-play of first animation on model load removed (viewer now waits for user intent)
Changed
refactor: animation UUIDs updated and build scripts improvedrefactor:explorerenamed todiscoverthroughout codebase and commentsrefactor:postMessagecalls streamlined; iframe snippet formatting improvedrefactor: aria-labels updated for accessibility; unused stylesheet link removedrefactor: tip jar skill documentation and code cleaned up
[1.5.0] — 2026-04-20
Added
feat: share panel with SVG fallback for QR codesfeat: on-chain agent discovery page (/discover) with styles and full logicfeat: dashboard form additional fields and improved searchfeat: embed functionality with handshake verification and live preview
Fixed
fix: auth pending attribute correctly removed from<body>after user fetchfix: agent wallet address visibility for owners inGET /api/agentsresponsefix: agent routing paths updated to point to/publicdirectoryfix: unified username/email conflict error messages in registration flow
Changed
refactor: cheerio dependency removed; related server code cleaned uprefactor: My Agents page HTML, CSS, and JavaScript unified for consistency
[1.4.0] — 2026-04-18
Added
feat: manage permissions panel and ERC-7710 delegation toolkitfeat:PermissionsClient— grant, list, verify, and revoke scoped delegationsfeat: permissions management lazy loading and advanced permissions smoke testfeat: session management for login redirectionfeat: quota enforcement for avatar uploads and limit checks in agent creation flowfeat: on-chain deployment button and styling on agent profile pages
Fixed
fix: login and register redirection paths correctedfix: routing paths invercel.jsoncleaned up (removed unnecessary/publicprefix)
Changed
refactor: Privy integration removed; wallet connection logic simplified to injected provider
[1.3.0] — 2026-04-17
Added
feat: ERC-8004 on-chain agent discovery page (initial implementation)feat: embed host and action bridges; iframe embed pipelinefeat: LobeHub plugin — manifest, bridge, and dev harnessfeat: avatar idle animation loop — breathing, saccade, blink, and weight shiftfeat: agent home page with share panel and deploy chipfeat: first-time onboarding banner for new agentsfeat: inline name/description editing on agent profile with deploy-on-chain header buttonfeat: ERC-8004 chain dropdown on/agent/:iddeploy chip; Base Mainnet as defaultfeat: viewer camera polish on first load; spacebar, double-click, andFshortcuts; per-agent camera preferences stored locallyfeat: post-create redirect to editor; 3D body mounted on public agent profile
Fixed
fix: wallet auth foundation hardened for agent reliabilityfix: TradingView widgets switched to dark mode for midnight theme
Changed
chore: duplicate camera module (capture) retiredchore: create→deploy flow accessibility polishedfeat(tests): test suite for discover/my-agents rename and routing
SDK Changelog (@three-ws/sdk)
The SDK is published separately. Its changelog lives at sdk/CHANGELOG.md.
[0.1.0] — 2026-04-14
Initial public release.
Added:
AgentKit— one-call class to ship an ERC-8004 agent (panel + registration + manifests)AgentPanel— standalone floating chat UI with voice I/O; bring your ownonMessagehandler- ERC-8004 wallet + IPFS + on-chain registration flow via
registerAgent() .well-knownmanifest generators:agentRegistration(),agentCard(),aiPlugin()PermissionsClient— ERC-7710 delegation grant, verify, and revoke- Low-level exports:
IDENTITY_REGISTRY_ABI,REPUTATION_REGISTRY_ABI,VALIDATION_REGISTRY_ABI,REGISTRY_DEPLOYMENTS,agentRegistryId(),buildRegistrationJSON(),getIdentityRegistry(),connectWallet(),pinToIPFS() - TypeScript declarations (
index.d.ts) - Standalone
styles.cssunder the.ak-*namespace
CDN Versioning
The CDN bundle is served from three.ws (Google Cloud Run + CDN). The URL includes the version so you can pin to an exact release.
<!-- Pinned to 1.5.2 — safe for production; won't break when 2.0.0 releases -->
<script type="module" src="https://three.ws/agent-3d/1.5.2/agent-3d.js"></script>
<!-- Always latest stable — convenient for development, risky for production -->
<script type="module" src="https://three.ws/agent-3d/latest/agent-3d.js"></script>
The CDN also maintains rolling channel aliases:
Every channel is a directory holding the same file name, so only the path segment changes:
| URL | Tracks |
|---|---|
https://three.ws/agent-3d/1.5.2/agent-3d.js |
Exact version (immutable) |
https://three.ws/agent-3d/1.5/agent-3d.js |
Latest 1.5.x patch |
https://three.ws/agent-3d/1/agent-3d.js |
Latest 1.x minor |
https://three.ws/agent-3d/latest/agent-3d.js |
Latest stable (any version) |
Recommendation: Pin to a full MAJOR.MINOR.PATCH version in production. Upgrade intentionally after reviewing the migration notes for the target version.
The immutable exact-version directory ships an integrity.json sidecar for Subresource Integrity verification. The rolling channels deliberately have none, because their contents change:
https://three.ws/agent-3d/1.5.2/integrity.json
The same SHA-384 hashes are published for every version at once in the CDN version index, https://three.ws/agent-3d/versions.json.
Smart Contract Versioning
ERC-8004 contracts are immutable after deployment. This is a property of the blockchain, not a limitation of the platform.
What this means in practice:
- Contract code never changes after deployment. The address is permanent.
- New features that require contract changes are deployed as new contracts at new addresses.
- Old contract addresses continue to work indefinitely — existing agent registrations remain valid.
- The platform always uses the latest contract address for new registrations.
REGISTRY_DEPLOYMENTSin the SDK contains all historical deployment addresses; old addresses are never removed.
When a new contract is deployed:
- The new address is added to
REGISTRY_DEPLOYMENTSfor the relevant chain ID. - Agents registered on older contracts continue to resolve normally.
- A migration path is documented if agent owners want to re-register under the new contract (e.g., to gain access to new on-chain features).
// All deployed contract addresses, by chain ID
import { REGISTRY_DEPLOYMENTS } from '@three-ws/sdk';
// Base Mainnet
console.log(REGISTRY_DEPLOYMENTS[8453].identityRegistry);
// Base Sepolia (testnet)
console.log(REGISTRY_DEPLOYMENTS[84532].identityRegistry);
Manifest Format Versioning
Agent manifests carry a $schema field that identifies the format version:
{
"$schema": "https://three.ws/schemas/agent-manifest-v1.json",
"name": "My Agent",
"endpoint": "https://myapp.com"
}
Current schema: v1
| Rule | Detail |
|---|---|
| v1 manifests are always loadable | The manifest loader will support v1 indefinitely |
| Additive changes stay in v1 | New optional fields can be added without a version bump |
| Breaking changes require v2 | Field removals and renames will use a new schema URL |
| Simultaneous support | The manifest loader handles both v1 and v2 at the same time during transitions |
How to Upgrade
npm package
# Upgrade to latest
npm update @three-ws/sdk
# Pin to a specific version
npm install @three-ws/[email protected]
CDN embed
Change the version number in the src attribute of your script tag. Before upgrading across a major version boundary, read the migration notes in this changelog for every version between your current version and the target.
Checking your current version
// From the SDK
import { version } from '@three-ws/sdk';
console.log(version); // "0.2.1"
// From the CDN version index
const { latest } = await fetch('https://three.ws/agent-3d/versions.json').then(r => r.json());
console.log(latest); // "1.5.2"
Deprecated Features
No public-facing features are currently deprecated. The only @deprecated annotations in the codebase are inside vendored dependencies (Three.js internals) and have no effect on the public API.
When features are deprecated, they will be listed here with:
- The version that introduced the deprecation
- The target version for removal
- A migration path
Release Process
For contributors and maintainers. A release follows these steps:
- Changes are merged to the
mainbranch via pull request. package.jsonversion is bumped (andsdk/package.jsonif the SDK changed).- This
CHANGELOG.mdis updated with entries for the new version. - A git tag is created:
git tag v1.5.2 && git push threews v1.5.2 - A GitHub Release is created from the tag with the changelog entry as the body.
npm run build:allproduces the platform bundle and the CDN library build.npm run publish:libcopies the CDN bundle intodist/agent-3d/{version}/, generates anintegrity.jsonsidecar with SHA-384 hashes, updates the rolling channel aliases (1.5,1,latest), and writes aversions.jsonmanifest.- The image is deployed to Google Cloud Run with
npm run deploy:gcp:full, which serves the updateddist/directory (including the CDN library build) from thethree-ws-apiservice. That one command runs the fullbuild:gcpchain and thendeploy:gcp; a barenpm run buildis not enough on its own, because the deploy gate checksdist/for the UMD library thatbuild:lib:fullandpublish:libput there.
The SDK (@three-ws/sdk) is published to npm separately:
cd sdk && npm publish
Staying Up to Date
- GitHub Releases — Watch the repository and select "Releases only" to get an email for each new release.
- npm outdated — Add
npm outdated @three-ws/sdkto your CI pipeline to detect available upgrades automatically. versions.json— The CDN publishes a machine-readable index athttps://three.ws/agent-3d/versions.jsonlisting all available versions, channel aliases, and SRI hashes.
Related
- Introduction: what the platform is and how the layers fit together
- Quick Start: pin the CDN bundle or install the SDK
- SDK Reference: the npm packages this versioning policy covers
- Deployment: how a release actually ships to production