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(aws): finish three Builder Center articles and write an X thread for each
nirholas47281b37da9a
diff --git a/docs/aws-builder-center-universal-retargeting.md b/docs/aws-builder-center-universal-retargeting.mdindex d266a9de0..91c568901 100644--- a/docs/aws-builder-center-universal-retargeting.md+++ b/docs/aws-builder-center-universal-retargeting.md@@ -10,13 +10,13 @@ index: docs/aws-builder-center.md# Any skeleton, one clip library: how we animate every humanoid avatar in the browser without a rig allowlist-There are 113 animation clips on three.ws: idles, walks, waves, dances, emotes. We baked each of them once, at build time, onto one reference skeleton. They then play, in the browser, on avatars that other tools exported years apart under other naming schemes: a Mixamo character, a VRoid model, an Unreal mannequin, a Daz figure, a Blender export, a hobby rig whose bones are called `shoulderL` and `kneeL`. Nobody re-authors a clip for any of them, and there is no list of approved rigs anywhere in the code.+There are 113 animation clips on three.ws: idles, walks, waves, dances, emotes. We baked each of them once, at build time, onto one reference skeleton. They play, in the browser, on avatars other tools exported under other naming schemes: Mixamo, VRoid, an Unreal mannequin, Daz, Blender, a hobby rig whose bones are called `shoulderL` and `kneeL`. Nobody re-authors a clip per avatar, and the animation stack keeps no list of approved rigs.-This article explains how that works, and where it stops. Mapping bone names is the part everybody expects, and it is the smaller half. The larger half is that two skeletons with identical names can rest in different poses and measure rotations in different frames, and a clip copied across verbatim will tip one avatar onto its back and drive another one's arms through its own chest. We shipped both of those bugs. The fixes, and the tests that keep them fixed, are the substance here.+This is how that works, and where it stops. Mapping bone names is the part everybody expects, and the smaller half. The larger half: two skeletons with identical names can rest in different poses and measure rotations in different frames, and a clip copied verbatim tips one avatar onto its back and drives another's arms through its chest. We shipped both of those bugs. The fixes, and the tests that keep them fixed, are the substance here.Everything runs client-side in [three.js](https://threejs.org), and every code sample is an excerpt from [the repository](https://github.com/nirholas/three.ws) (Apache-2.0) with its file path, so you can check each claim in the same sitting.-**Status, plainly, because AWS builders check.** three.ws is a verified AWS Partner. Nothing in this article runs on an AWS service: retargeting happens in the viewer's browser tab, and the platform's own runtime is on Google Cloud Run. We would rather say that than let a partner article imply a hosting story that is not ours. One more date matters: the A-pose limb re-aim described in section 7 merged on 3 October 2026. At the time of writing, production still runs the commit before it (`curl -s https://three.ws/api/version` shows which commit is live), and the published npm package `@three-ws/retarget` 0.1.2 predates it too. Everything else here is live.+**Status, plainly, because AWS builders check.** three.ws is a verified AWS Partner. Nothing in this article runs on an AWS service: retargeting happens in the viewer's browser tab, and the platform's own runtime is on Google Cloud Run. We would rather say that than let a partner article imply a hosting story that is not ours. One more date matters: the A-pose limb re-aim described in section 7 merged on 3 October 2026. At the time of writing, production still runs an earlier commit (`curl -s https://three.ws/api/version` shows which commit is live), and the published npm package `@three-ws/retarget` 0.1.2 predates it too. Everything else described as shipped is live.**Contents**@@ -157,7 +157,7 @@ After resolution, a canonical name is assigned at most once. When two joints sti## 5. Why a name map is not enough-Suppose every name maps. Copy the clip's rotations across and two things can still go badly wrong, because a rotation track stores **absolute local rotations** measured against one skeleton's rest pose and one skeleton's axes.+Suppose every name maps. Two things can still go badly wrong, because a rotation track stores **absolute local rotations** measured against one skeleton's rest pose and axes.**Axis conventions.** Mixamo exports bake a +90 degree rotation about X into the armature node and a -90 degree rotation into the hips. The two cancel, so the avatar stands upright at rest. But the clip was authored on a rig whose hips rest at identity, so the first keyframe of the hip track overwrites the -90 and leaves the armature's +90 uncancelled. The avatar plays its idle lying on its back. Our upright-invariant test suite records how bad this was on a real Mixamo export (`public/avatars/michelle.glb`) before the fix: the hips sat 92 degrees off vertical during `idle`, 94 during `celebrate`, and 115 during `dance`.@@ -236,11 +236,11 @@ The spine, neck, head and clavicles are deliberately absent, because their rest- **Inheritance.** A bone without its own entry (a hand, a finger) inherits its parent's turn, so the hand stays rigid with the forearm and the fingers with the hand.- **Feet keep their world rest.** The foot is in `WORLD_REST_BONES` and turns by nothing, so a sole that is flat on the floor at rest stays flat whatever angle the shin was re-aimed by. Toes inherit from the foot.-The threshold `ALIGN_DOT = 1 - 1e-6` corresponds to about 0.08 degrees, so two exports of the same skeleton that differ by measurement noise are treated as aligned, a T-pose rig turns by a few degrees at most, and the reference rig turns by nothing and still round-trips unchanged. The turn of the bone and of its parent (`C` and `Cp`) then slot into the correction from section 6, which is exactly the original formula when every turn is identity.+The threshold `ALIGN_DOT = 1 - 1e-6` is about 0.08 degrees, so export noise counts as aligned, a T-pose rig turns by a few degrees at most, and the reference rig turns by nothing and still round-trips unchanged. The bone's turn and its parent's (`C` and `Cp`) then slot into the section 6 correction.## 8. Hips, legs, and root motion-Legs need nothing special in the naming layer; they are ordinary entries, and the dignity sweep in section 10 checks that they actually swing. They need care in two other places.+Legs are ordinary entries in the naming layer (section 10's sweep checks they actually swing). They need care in two other places.**Only motion crosses over.** About a third of the clips (41 of 113) ship a position and a scale track for every bone, because that is how the build bakes them. A bone's local position is its offset from its parent, which is to say the reference rig's bone lengths. Copy those onto an avatar with different proportions and every bone "matches" while the skeleton folds into a heap. So the retargeter takes only what is genuinely motion:@@ -262,7 +262,7 @@ Joint rotations, plus the root translation. Every rig keeps its own bone lengths}```-(`src/animation-manager.js`.) The upper clamp is 200 rather than something modest because a Mixamo armature exported at `scale 0.01` puts its hips near 100 in local units; matching world heights instead would collapse the hip track to about a centimetre of motion and sink the avatar a metre into the floor. Height is measured from the model's bounding-box bottom rather than world zero, because viewers recenter models and many exports put their floor below the origin. The hip translation is also rotated into the target's hips-parent frame, so root motion travels the same world direction on a Mixamo armature as on the reference rig, and a floor offset lands the clip's ground on the rig's ground.+(`src/animation-manager.js`.) The clamp reaches 200 because a Mixamo armature exported at `scale 0.01` puts its hips near 100 in local units; matching world heights instead would leave about a centimetre of hip motion and sink the avatar into the floor. Height is measured from the model's bounding-box bottom, not world zero, because many exports put their floor below the origin. The track is also rotated into the target's hips-parent frame, so root motion travels the same world direction on any armature.One more consequence: when a gesture plays over a walk as an additive overlay, every hip, leg and foot track is stripped from the overlay, so a wave never fights the walk cycle's root sway.@@ -287,7 +287,7 @@ function _modelSupportsCanonicalClips(model) {}```-`supportsCanonicalClips()` returns that answer, and callers decide what a "no" means for them. A shared scene that needs a performer substitutes a known-good one: the theater stage tries the agent's own avatar, then an assigned fallback avatar, then the plain mannequin, and only an avatar that passes this gate (plus a proportion check that rejects anything far wider than it is tall) gets to perform. A personal view, like an agent's own screen, shows the model as authored. Non-humanoid skeletons (quadrupeds, prop rigs) fail this rung on purpose, because there is no safe automatic mapping for them.+`supportsCanonicalClips()` returns that answer, and callers decide what "no" means. A shared scene substitutes a known-good performer: the theater stage tries the agent's own avatar, then an assigned fallback avatar, then the plain mannequin, and only one that passes this gate gets to perform. A personal view, like an agent's own screen, shows the model as authored. Non-humanoid skeletons fail this rung on purpose: there is no safe automatic mapping for them.**Rung 2: does this clip find enough of a home?** Coverage below `MIN_COVERAGE` returns `clip: null` with an honest breakdown of matched, total and dropped bones. No half-puppet plays.@@ -317,7 +317,7 @@ Three layers of tests keep this honest, and each catches a failure the others ca['hand_r', 'RightHand'],```-Around those tables sit the tests that encode decisions rather than spellings: the Unreal spine stays unaliased, `J_Bip_` names survive the `j_` prefix strip, side derivation never crosses sides, control-rig bones stay unmapped, metacarpals with no canonical home stay unmapped, a full Unreal mannequin hand maps all 15 joints per side, the Rigify and SMPL collisions split correctly whichever order the joints are listed in, and no canonical name is ever assigned twice. Real fixtures cover both ends: `cz.glb` is a no-op returned by reference, and `michelle.glb` is renamed, axis-folded, and asserted to keep every joint's world matrix, so the rewrite cannot change how the mesh looks. The file ran 477 tests green when we wrote this.+Around them sit tests that encode decisions rather than spellings: the Unreal spine stays unaliased, side derivation never crosses sides, control-rig bones stay unmapped, a full Unreal mannequin hand maps all 15 joints per side, the Rigify and SMPL collisions split correctly in either joint order, and no canonical name is assigned twice. Real fixtures cover both ends: `cz.glb` is a no-op, and `michelle.glb` is renamed, axis-folded, and asserted to keep every joint's world matrix, so the mesh cannot change. The file ran 477 tests green when we wrote this.A new convention is always the same four parts: an alias entry, a table of its real spellings, a "never crosses sides" test, and a Rig Doctor fingerprint. That is what "no allowlist" means in practice: teach the canonicalizer once, and every surface that animates avatars learns it at the same moment.@@ -332,19 +332,19 @@ A new convention is always the same four parts: an alias entry, a table of its r});```-A regression test that passes with or without the fix tests nothing. Writing the "without" case first is the cheapest way we know to prove a test can fail.+A regression test that passes with or without the fix tests nothing.**A motion sweep, because names passing is not limbs moving.** A rig can map its hips and animate as a torso with four frozen sticks attached, and every name test stays green. `scripts/animation-dignity-sweep.mjs` drives the real idle and walk clips onto ten differently named rigs, down both production paths (canonicalize at ingest, then retarget; and retarget straight onto raw names at runtime), and measures per-limb rotation swing plus hand and foot travel through space in hip-heights, by composing world matrices. We ran it for this article: 10 of 10 conventions animate both arms and both legs on both paths, with coverage from 94 percent (the `shoulderL` hobby rig, 49 bones mapped) to 100 percent. On that hobby rig, the walk swings the legs by 50.7 and 54.4 degrees.-One honest caveat about that sweep: its ten rigs are one synthetic T-pose skeleton renamed ten ways. That is deliberate, so a difference in results is a difference in naming and never in proportions, but it also means the sweep says nothing about rest poses. Rest poses are covered by the upright suite, the byte-for-byte reference-rig test, and the real Mixamo fixture. The section 7 re-aim has no dedicated test yet; see the next section.+One caveat: the ten rigs are one synthetic T-pose skeleton renamed ten ways, deliberately, so differences are about naming, never proportions. The sweep therefore says nothing about rest poses; the upright suite, the reference-rig test and the real Mixamo fixture cover those. The section 7 re-aim has no dedicated test yet.## 11. What we would build differently**Derive descriptive claims from data.** Writing this article, we found our own comments disagreeing: one says the reference rig rests in an A-pose, the comment added by the October fix says T-pose, and the generated rest data settles it (T-pose). A comment cannot fail a test. Where a stance or a number can be computed from reference data, compute it or assert it.-**Write the test in the same commit as the geometric fix.** The A-pose re-aim shipped with no unit test of its own. It deserves the same treatment as the upright suite: a synthetic A-pose rig, an assertion that the idle's hands end outside the torso's bounds, and the "without the fix" case that proves the assertion can fail.+**Write the test in the same commit as the geometric fix.** The A-pose re-aim shipped with no unit test of its own, and the gap it left is exactly the kind a test would have caught on day one (see the next point). The test that finally came is a parity test, `tests/animation-retarget-rig-parity.test.js`: it loads the A-posed parametric base, retargets the idle and the walk through both entry points, and requires every limb track to agree. Run without the fix, it fails with the right upper arm about 50 degrees off.-**One retarget entry point, not three.** The runtime manager, `retargetClipToObject` and `retargetClipToRig` each assemble their own inputs. The re-aim reached the first two. `retargetClipToRig`, used by the Animation Studio's preset gallery and its animated-GLB export, does not pass rest directions yet, although the helper it needs (`canonicalRestDirectionMapFromRig`) already exists. Entry points that assemble their own inputs drift.+**One retarget entry point, not three.** The runtime manager, `retargetClipToObject` and `retargetClipToRig` each assemble their own inputs. The re-aim reached the first two and missed the third: `retargetClipToRig`, used by the Animation Studio's preset gallery and its animated-GLB export, did not pass rest directions for five days, although the helper it needed (`canonicalRestDirectionMapFromRig`) shipped in the same commit. An A-posed body animated correctly on its own page and put its arms through its torso in the studio. The fix was four lines; the lesson is that entry points which assemble their own inputs drift, and a parity test is the cheapest guard against it.**Make the gates agree.** The bone-count gate and the coverage gate answer different questions, which is how the Biped case slips between them. Gate on what the library will actually do (would any clip clear coverage?), not on a proxy. Likewise Rig Doctor uses the same canonicalizer but not the clavicle/upper-arm resolver, so on a Rigify rig it reports a collision the runtime resolves. A diagnostic that disagrees with the runtime teaches the wrong thing.@@ -362,7 +362,7 @@ All Apache-2.0, none of it tied to our hosting:Everything below is public and keyless.-- **Rig Doctor**, with a Mixamo rig preloaded: [three.ws/rig-doctor?sample=/avatars/michelle.glb](https://three.ws/rig-doctor?sample=/avatars/michelle.glb). It names the convention, scores torso, arms, hands and legs, lists every bone rewrite, and plays idle, walk, wave and dance on the rig through the same manager the platform uses. Drop your own `.glb` on [three.ws/rig-doctor](https://three.ws/rig-doctor): the file is read in your browser and never uploaded. The [Rig Doctor reference](https://three.ws/docs/rig-doctor) explains each verdict.+- **Rig Doctor**, with a Mixamo rig preloaded: [three.ws/rig-doctor?sample=/avatars/michelle.glb](https://three.ws/rig-doctor?sample=/avatars/michelle.glb). It names the convention, scores each limb group, lists the bone rewrites, and plays idle, walk, wave and dance on the rig through the platform's own animation manager. Drop your own `.glb` on [three.ws/rig-doctor](https://three.ws/rig-doctor): the file is read in your browser and never uploaded. The [Rig Doctor reference](https://three.ws/docs/rig-doctor) explains each verdict.- **The Animation Studio** at [three.ws/pose](https://three.ws/pose) plays the rest of the library on a loaded avatar and exports an animated GLB.- **The clip library itself:**diff --git a/docs/aws-builder-center.md b/docs/aws-builder-center.mdindex 3bf8b69c7..c970dc4b7 100644--- a/docs/aws-builder-center.md+++ b/docs/aws-builder-center.md@@ -59,6 +59,9 @@ Written and reviewed in this repo, not yet submitted:| [aws-builder-center-mcp-agents.md](./aws-builder-center-mcp-agents.md) | An MCP server whose paid tools settle per call in USDC over HTTP 402 || [mobile-launch/aws-builder-center-article.md](./mobile-launch/aws-builder-center-article.md) | One web product, three native apps, zero forks: the Seeker, Android, and iPhone shells, with the AWS SDK v3 storage client and the Marketplace front door || [aws-builder-center-agent-commerce-spine.md](./aws-builder-center-agent-commerce-spine.md) | The authorization spine behind autonomous commerce: Marketplace entitlements under Concurrent Agreements, spend policy instead of a credential, x402 preflight, agent vitals, and the physical fulfillment lane at the end of the chain |+| [aws-builder-center-universal-retargeting.md](./aws-builder-center-universal-retargeting.md) | Any skeleton, one clip library: how 113 pre-baked clips play on humanoid avatars from many exporters in the browser with no rig allowlist. Bone-name canonicalization, the bind correction, the A-pose re-aim, the fallen-pose guard, and the conventions that still fail. Companion thread: [universal-retargeting-thread.md](./x-posts/universal-retargeting-thread.md) |+| [aws-builder-center-immutable-embed-releases.md](./aws-builder-center-immutable-embed-releases.md) | A URL is a promise: moving channels beside write-once versioned URLs for the `<agent-3d>` web component, the release ledger, Subresource Integrity pins, the 2026-10-01 incident that broke every pin, and how the pattern maps to S3 Object Lock and CloudFront. Companion thread: [immutable-embed-releases-thread.md](./x-posts/immutable-embed-releases-thread.md) |+| [aws-builder-center-claims-ledger.md](./aws-builder-center-claims-ledger.md) | An AI-assisted publishing pipeline that refuses to post what it cannot prove: the claims ledger, probes, proof reels filmed against production, content-hash-bound reviews, the idempotent publish ledger, and the model failover chain. Companion thread: [claims-ledger-thread.md](./x-posts/claims-ledger-thread.md) |## Publishing checklistdiff --git a/docs/x-posts/README.md b/docs/x-posts/README.mdindex 6e0606d81..3e20ea8d4 100644--- a/docs/x-posts/README.md+++ b/docs/x-posts/README.md@@ -41,6 +41,18 @@ explicit approval). Each file states what it's for and what has already been ver| [`proof-of-life-x-post.md`](proof-of-life-x-post.md) | A shipping-evidence post for the platform account: what landed this week, with public verification links. Names nothing about the personal account || [`pumpfun-article-x-post.md`](pumpfun-article-x-post.md) | The pump.fun article |+## Companion threads for the AWS Builder Center articles++Long-form threads that stand on their own and pair with a draft in+[`aws-builder-center.md`](../aws-builder-center.md). Each ends with a labeled reply to add once its+article is live on the Builder Center, and each lists the preconditions that must hold before it posts.++| File | What it covers |+| --- | --- |+| [`universal-retargeting-thread.md`](universal-retargeting-thread.md) | One clip library on any humanoid skeleton: name canonicalization, rest poses, the A-pose re-aim. Hold until the re-aim is deployed (the file has the check) |+| [`immutable-embed-releases-thread.md`](immutable-embed-releases-thread.md) | Write-once versioned URLs and SRI pins for the `<agent-3d>` script, and the incident that taught us why |+| [`claims-ledger-thread.md`](claims-ledger-thread.md) | The publishing pipeline that refuses a claim it cannot prove: evidence, probes, proof reels, content-hash reviews |+## Video and narration scripts| File | What it covers |diff --git a/docs/x-posts/claims-ledger-thread.md b/docs/x-posts/claims-ledger-thread.mdnew file mode 100644index 000000000..ba6b2123b--- /dev/null+++ b/docs/x-posts/claims-ledger-thread.md@@ -0,0 +1,209 @@+# X thread: claims-ledger++A thread for **@trythreews** on how the account itself is run: an AI-assisted pipeline that drafts+and reviews posts with a model, while deterministic code decides what is true, what is approved,+and whether a post already went out. It is the short companion to the AWS Builder Center article+[aws-builder-center-claims-ledger.md](../aws-builder-center-claims-ledger.md), and it stands on+its own for a reader who never opens that article.++**Thesis of this thread:** a model may draft and edit; it does not get to decide what is true.+Nothing else. No token talk, no roadmap, no claims about reach.++Posting is owner-gated per [`CLAUDE.md`](../../CLAUDE.md). This file is copy waiting for a human+to send.++**Every claim below was verified on 2026-10-08**, against the code in this repository or the live+site:++| Claim in the thread | Where it was verified |+|---|---|+| Every number, ordinal and absolute word must sit inside a declared claim with evidence; an uncovered number is blocking | [`api/_lib/x-content/editorial.js`](../../api/_lib/x-content/editorial.js) (`ABSOLUTES`, `claimProblems`), [`docs/x-content-pipeline.md`](../x-content-pipeline.md) |+| The checker runs both ways (a claim not in the copy also fails) | `claimProblems` in [`editorial.js`](../../api/_lib/x-content/editorial.js) |+| Machine Atlas run read 9 cylinders before the drag and 5 after | [`data/x-content/proofs/machine-atlas.json`](../../data/x-content/proofs/machine-atlas.json) (`facts.cylinders`, `facts.cylindersAfter`) |+| Page evidence is matched in a real browser after the text stops growing; no fuzzy match, no model | `createPageReader` and the `page` case in [`api/_lib/x-content/verify.js`](../../api/_lib/x-content/verify.js) |+| Every post the owner took down had passed the fact check | [`docs/x-content-pipeline.md`](../x-content-pipeline.md) ("Proof reels"), and the header of [`api/_lib/x-content/reel.js`](../../api/_lib/x-content/reel.js) |+| A post with no probe fails review; probe kinds; a command probe must exit 0; API probes run again before sending | `verifyItem`, `probeChecks`, `commandProbe` in [`verify.js`](../../api/_lib/x-content/verify.js); `preflight` in [`api/_lib/x-content/runner.js`](../../api/_lib/x-content/runner.js) |+| One to three frames a second in software; clock stepped 1/30 s; no reel when a step fails | header, `Take.frame` and `proveItem` in [`reel.js`](../../api/_lib/x-content/reel.js) (`DEFAULT_FPS = 30`) |+| A wait of 2 s or more is cut and labelled; the stamp names commit and day | `CUT_BADGE_AFTER_SEC = 2` and the stamp in `proveItem`, [`reel.js`](../../api/_lib/x-content/reel.js) |+| The Drive reply took about 6 seconds, and the reel shows it | [`data/x-content/proofs/drive-copilot.json`](../../data/x-content/proofs/drive-copilot.json) (`cuts`: 3.9 s and 6.3 s; `/api/chat` answered 200 in 6.8 s); the frame itself reads "cut 6 s" |+| Proof stores SHA-256 of scenario and video; expires after 14 days; exact facts must match, floors must hold | `scenarioHash`, `proofProblems`, `PROOF_MAX_AGE_DAYS = 14`, `factRules` in [`reel.js`](../../api/_lib/x-content/reel.js); `factDrift` in [`verify.js`](../../api/_lib/x-content/verify.js) |+| Drafter cites only harvested evidence, copied unchanged; failures fed back, up to 3 attempts; a failing draft is not written to the queue | `draftFindings`, `draftPost` (`attempts = 3`) in [`api/_lib/announce/draft.js`](../../api/_lib/announce/draft.js) |+| Editor scores six dimensions 1 to 5, returns JSON; a blocking issue or a score under 4 turns publish into revise | `SCORE_KEYS`, `SYSTEM`, `parseReview` in [`api/_lib/x-content/editor.js`](../../api/_lib/x-content/editor.js) |+| The editor can add a blocker, not remove one | `reviewItem` in [`api/_lib/x-content/review.js`](../../api/_lib/x-content/review.js): lint and verification blockers are collected independently of the editor |+| Five rungs, in that order; Groq is text-only; no-credential rungs skipped; errors and unparseable replies fall through | `modelRungs`, `viaChatCompletions`, `callModelChain` in [`api/_lib/x-content/llm.js`](../../api/_lib/x-content/llm.js) |+| All 52 review records name the last rung; the records span three weeks | counted over [`data/x-content/reviews/`](../../data/x-content/reviews/): 52 tracked files, every `editor.model` is `nvidia:moonshotai/kimi-k3`, `reviewedAt` runs from 2026-09-18 to 2026-10-08; every record's `editor.fallbacks` lists OpenRouter 402 and OpenAI 429 `billing_not_active`, plus Vertex 403 (32) or no Google Cloud credentials (20) |+| Review bound to a SHA-256 of copy, media bytes, alt text, claims, mentions and probes; 14-day expiry | `contentHash`, `approvalProblems`, `REVIEW_MAX_AGE_DAYS = 14` in [`review.js`](../../api/_lib/x-content/review.js) |+| On 8 October the validator refused two approved posts, at 17 and 19 days | output of `npm run x:content:check` run on 2026-10-08 (items `galaxy` and `ai-3d-skills`) |+| Ledger writes every media id and post id as X returns it; a crashed thread resumes at the next reply | `uploadOnce`, `publishPosts`, `publishItem` in [`api/_lib/x-content/publisher.js`](../../api/_lib/x-content/publisher.js) |+| Policy release conditions; veto window; ops alert | `policyBlockers`, `vetoUntil` in [`api/_lib/x-content/approval.js`](../../api/_lib/x-content/approval.js); `advance` in [`scripts/x-content.mjs`](../../scripts/x-content.mjs) |+| Outcomes read at most every 6 hours over 90 days; used for ranking only | `OUTCOMES_REFRESH_HOURS = 6`, `OUTCOMES_WINDOW_DAYS = 90` in [`api/_lib/x-content/outcomes.js`](../../api/_lib/x-content/outcomes.js); read by [`priority.js`](../../api/_lib/x-content/priority.js) and as editor calibration, by no deterministic check |+| An engagement-ask phrase in the lint blocks the example post in our own docs | `PUSHY_CTAS` (`/\bdrop a\b/i`) in [`editorial.js`](../../api/_lib/x-content/editorial.js) against the "Queue item format" example in [`docs/x-content-pipeline.md`](../x-content-pipeline.md); reproduced with `lintItem` on 2026-10-08 |+| The docs page is live | [three.ws/docs/x-content-pipeline](https://three.ws/docs/x-content-pipeline) answered 200 and rendered "The editorial bar" on 2026-10-08 |++The thread also passes the pipeline's own offline gate: every post was run through+`languageProblems` and `copyProblems` (no findings, maximum 1000), and the ten posts with 22+declared claims were run through `claimProblems` (no findings), with every `file` evidence string+confirmed present.++**Re-run before posting.** Three numbers are true of a day, not of the code: the 52 review records,+the "two, at 17 and 19 days" refusal, and "three weeks". Before sending, re-count with:++```bash+npm run x:content:check+node -e 'const fs=require("fs");const d="data/x-content/reviews/";const m={};for(const f of fs.readdirSync(d)){const r=JSON.parse(fs.readFileSync(d+f));m[r.editor?.model]=(m[r.editor?.model]||0)+1}console.log(m)'+```++If either has moved, change the copy to today's numbers or cut the sentence.++**Things to NOT claim:**++1. **Do not say the pipeline runs on AWS or uses Amazon Bedrock.** It runs on Google Cloud Run, and+ the model chain is the five providers in `llm.js`.+2. **Do not call the account autonomous or unattended.** Tier 1 posts, any post that tags an+ account, and any editor override wait for a person; policy releases sit in a veto window.+3. **Do not say a reel proves the feature works in general.** It proves the steps passed once, on+ the commit and day in its stamp.+4. **Do not tie the learning loop or any model to $THREE, price, or volume.** Say it learns from+ the account's own measured posts. Nothing about pool volume belongs in this thread.+5. **Do not say the lint has no false positives, or that the lint is AI.** It is regular+ expressions, and post 10 says so.+6. **Do not say "verified AWS Partner" here.** The live [three.ws/aws](https://three.ws/aws) page+ says "AWS Partner", and nothing in this thread needs the credential.+7. **Do not give slot times or say when the account posts.** The minutes are an HMAC under a+ production-only seed on purpose.+8. **Do not say Claude reviewed these posts.** Every committed review record was written by Kimi+ K3 on NVIDIA NIM; Claude is the top rung, not the rung that answered.++---++## The thread++**Post 1 (head)** (470 weighted characters, image: `reel-stamp.png`)++> This feed is written with AI help, and no post goes out on a model's word.+>+> Every number, ordinal and absolute word in a post has to sit inside a declared claim, and every claim carries evidence a program re-checks at review: a quote from the live page, a line in our source, or a fact read off the screen while a run of the feature was filmed. A number with no claim behind it is a blocking error, so it does not ship.+>+> Here is how that works, and where it falls short.++**Post 2** (556 weighted characters)++> A claim quotes our own copy and names its evidence. "Nine cylinders to five" in the Machine Atlas post cites two facts the filmed run read off the page: 9 cylinders before a slider drag, 5 after.+>+> The checker runs both ways. A number the copy states that no claim covers fails review, and so does a claim whose words are no longer in the copy, so a verified claim cannot stay behind while the sentence changes.+>+> Page evidence is matched against the page rendered in a real browser, after its text stops growing. No fuzzy matching and no model in that loop.++**Post 3** (474 weighted characters)++> A quote proves a page says something. It does not prove the feature does it, and every post we have taken down had passed that check.+>+> So a post also needs a probe, or its review fails: an API call with an expected status or JSON value, a scripted browser session, a repo test that has to exit 0, or the post's own filmed scenario. API probes run a second time seconds before the post is sent, so a page that broke after review holds the post instead of publishing it wrong.++**Post 4** (538 weighted characters, image: `reel-cut.png`)++> The video on a feature post is a filmed test run against production, not a screen recording.+>+> With no GPU, a headless browser renders WebGL at one to three frames a second, so the camera takes over the page clock and steps it 1/30 s at a time, one screenshot per step. If any step fails, no reel is made.+>+> A wait on the network of 2 seconds or more is cut and labelled in the bar under the page, and a stamp names the production commit and the day it was filmed. In this frame the agent's reply took about 6 seconds, and the reel says so.++**Post 5** (437 weighted characters)++> The proof record stores a SHA-256 of the scenario and of the video file. Edit a step or swap the clip and the post stops validating, and a proof expires after 14 days.+>+> At review the scenario runs again without the camera. A number the post states exactly has to read the same as in the reel. A number stated as a floor ("more than 500") only has to stay at or above it, so a count that grows does not send a true post back to be filmed.++**Post 6** (557 weighted characters)++> Two jobs use a model: drafting from an evidence brief, and the editorial review.+>+> The drafter may only cite evidence that was harvested from the live page or a repo file before it wrote a word, copied unchanged. Its failures are fed back verbatim for up to 3 attempts, and a draft that still fails is never written into the queue.+>+> The editor scores six dimensions from 1 to 5 and returns JSON. Code enforces the verdict, not the model: a blocking issue or any score under 4 turns "publish" into "revise". The editor can add a blocker. It cannot remove one.++**Post 7** (651 weighted characters)++> The model chain has five rungs: Claude on Vertex AI, gpt-oss-120b on Groq (text only, so a review that must see images skips it), Claude through OpenRouter, OpenAI, and Kimi K3 on NVIDIA NIM. A rung with no credentials is skipped, and one that errors or returns something unparseable falls through.+>+> Each review record names the model that wrote it. All 52 records in the repo today name the last rung, because each rung above it was either skipped or failing on billing or credentials. The review bar kept running through three weeks of that, which is the problem: the chain needs an alert when the rung that answered is not the one that should have.++**Post 8** (488 weighted characters, image: `editorial-bar.png`)++> A passing review is bound to a SHA-256 of the copy, every media file's bytes, the alt text, the claims, the mentions and the probes. Change one word and the approval is void. Reviews expire after 14 days, and the validator refuses an approved post whose review is stale: on 8 October it refused two, at 17 and 19 days.+>+> The publish ledger writes each media id and post id the moment X returns it, so a thread cut off by a crash resumes at the next unposted reply instead of posting twice.++**Post 9** (495 weighted characters)++> A post is released without a person only if its tier allows it, it was filmed and the proof covers it, it tags no one, and the editor passed it on its own verdict rather than on an override. Even then it waits out a veto window, and the release goes to our ops alerts.+>+> The queue also reads its own posts back through the X API, at most every 6 hours, and learns what media, length and threads were worth over 90 days. That changes which ready post fills a slot. No deterministic check reads it.++**Post 10** (454 weighted characters)++> What this does not prove: a reel shows the steps passed once, on the commit and the day in its stamp. Not on your phone, not under load, not next month, which is why the stamp is there and the record expires.+>+> The voice lint is regular expressions, and it has false positives: one of its engagement-ask phrases also blocks the example post in our own docs.+>+> The whole pipeline, every rule above, and its tests are documented here: three.ws/docs/x-content-pipeline+---++## Reply to append once the AWS article is live++Post this as a reply to post 10 only after the AWS Builder Center article is published. Whoever+publishes it pastes the article's canonical Builder Center URL after the colon at the end of the+line. With the URL counted as 23, it is 160 weighted characters.++> The full write-up of this thread is now on the AWS Builder Center, with the code behind each check and the limits we have not fixed yet:++---++## Media plan++Three real images, all in [`public/x-media/claims-ledger-thread/`](../../public/x-media/claims-ledger-thread/).+Each one was looked at before it was chosen. Two are single frames cut from proof reels already in+the repository; one is a screenshot of a live three.ws page.++| Post | File | What it shows | Size |+|---|---|---|---|+| 1 (head) | `reel-stamp.png` | Frame at 11 s of the Docs World reel (`public/x-media/docs-world/reel.mp4`), with the caption and the production stamp in the bar | 1280 x 720 |+| 4 | `reel-cut.png` | Frame at 9 s of the Drive reel (`public/x-media/drive-copilot/reel.mp4`), while the `cut 6 s` badge is showing | 1280 x 720 |+| 8 | `editorial-bar.png` | Playwright screenshot of [three.ws/docs/x-content-pipeline](https://three.ws/docs/x-content-pipeline) scrolled to "The editorial bar", taken 2026-10-08 at 1280 x 720 and device scale 1.5, cropped to remove a half-cut table row | 1920 x 990 |++Alt text, ready to paste (X sends it as media metadata):++**reel-stamp.png**++> A frame from the filmed Docs World run on three.ws: glowing pavilions on a dark ring, a trail of arrows leading to the Creation studios pavilion, and a card offering the Forge page. The bar under the page reads "Shift+Enter lays a trail to the pavilion that holds the page" and is stamped "live on three.ws @ f2081d946, 2026-09-29".++**reel-cut.png**++> A frame from the filmed Drive run: a 3D avatar in red headphones and round sunglasses has answered the question "What should I listen to on a long drive?" with "For a long drive, something with a steady...". The bar under the page shows the caption, a yellow "cut 6 s" badge, and the stamp "live on three.ws @ f2081d946, 2026-09-29".++**editorial-bar.png**++> The three.ws docs page for the X content pipeline, open at "The editorial bar": a paragraph saying nothing can be approved until a review passes and that the record is bound to a hash of the copy, media bytes, alt text, claims and mentions, above a table of review layers (voice lint, editorial lint, media quality, live verification), each linked to its source file.++How the frames were cut, so they can be re-cut if a reel is re-filmed:++```bash+node_modules/ffmpeg-static/ffmpeg -ss 11 -i public/x-media/docs-world/reel.mp4 -frames:v 1 public/x-media/claims-ledger-thread/reel-stamp.png+node_modules/ffmpeg-static/ffmpeg -ss 9 -i public/x-media/drive-copilot/reel.mp4 -frames:v 1 public/x-media/claims-ledger-thread/reel-cut.png+```++Both reels were filmed on 2026-09-29. The queue's media rule treats a captured frame older than 21+days as stale, so if this thread goes out after 2026-10-20, re-film the reels (`npm run x:content+-- prove docs-world` and `prove drive-copilot`) and cut new frames, and update the commit and date+in the alt text to match the new stamp.++## Notes on framing++- **Lead with the rule, not the tooling.** "No post goes out on a model's word" is the claim a+ reader can hold us to. The reels, hashes and ledgers are how we keep it.+- **Post 7 is the limit, and it should stay in.** A thread about refusing unverifiable claims that+ hides its own failover outage would be the exact failure it describes.+- **One link, at the end.** Every other post carries mechanism instead of a link, which matches the+ one-link rule the pipeline enforces on its own posts.+- **The AWS article goes deeper** on the code and on what we would build differently. Link it only+ in the appended reply, never in the head.diff --git a/docs/x-posts/immutable-embed-releases-thread.md b/docs/x-posts/immutable-embed-releases-thread.mdnew file mode 100644index 000000000..9ae3b366e--- /dev/null+++ b/docs/x-posts/immutable-embed-releases-thread.md@@ -0,0 +1,245 @@+# X thread: immutable embed releases++Companion thread for @trythreews to the AWS Builder Center draft+[`aws-builder-center-immutable-embed-releases.md`](../aws-builder-center-immutable-embed-releases.md):+how three.ws releases the `<agent-3d>` web component so a pinned embed never breaks, the+2026-10-01 incident where rebuilding version 1.5.2 on every deploy broke the integrity pins we had+published, and the second lesson about code that runs on someone else's origin.++The thread stands on its own; it does not depend on the article being live. Posting is manual and+owner-gated per [`CLAUDE.md`](../../CLAUDE.md) (posting to external channels needs explicit+approval). Do not post post 9 before checking the deploy note in the "do not claim" list below.++**Thesis:** a versioned URL is a promise to people you will never talk to, so a release has to be a+record that deploys read from, never something a deploy produces. Nothing else. No coin, no+payments, no roadmap.++## Verified claims++Checked on 2026-10-08. Every hash was computed with `curl | openssl dgst -sha384 -binary | openssl base64 -A`.++| Claim | Where it was verified |+| --- | --- |+| `/agent-3d/1.5.2/agent-3d.js` is 3,308,933 bytes and hashes to `sha384-KdAiFRsdcCbQMu4O5rkoL8hOEYLkmrdpf9ELd7jro+9NTNipWis3oqqFLll7v20Q` on three.ws, in the archive, and in the ledger | https://three.ws/agent-3d/1.5.2/agent-3d.js, https://storage.googleapis.com/three-ws-lib-releases/agent-3d/1.5.2/agent-3d.js, [`data/agent-3d-releases.json`](../../data/agent-3d-releases.json) |+| The versioned path is served `public, max-age=31536000, immutable`; `latest`, `1` and `1.5` are served `public, max-age=3600, s-maxage=300, stale-while-revalidate=86400` | `curl -sI` against the live URLs; route rules in [`vercel.json`](../../vercel.json) |+| 1.5.2 was cut on 2026-06-17 and `package.json` stayed at 1.5.2 until the fix | commit `57c315696`; `git log -S'"version": "1.5.2"' -- package.json` |+| The old publish step wrote the exact version and all moving channels from the current build | `git show bde1f4975^:scripts/publish-lib.mjs` (`const channels = [version, ...]`) |+| Before the fix, our docs carried two different hashes for 1.5.2 (`qCG5gH4...` in the Character Library tutorial and the combined docs page, `xkFDjVP8...` in the agent skill files) while production served `KdAiFR...` | `git grep` at `bde1f4975^`; diff of commit `bde1f4975` |+| A stale pin is refused by the browser with "Failed to find a valid digest in the 'integrity' attribute ... The resource has been blocked." | Headless Chromium (Playwright) loading the live URL with the old `qCG5gH4...` hash from a non-three.ws origin, 2026-10-08 |+| `/agent-3d/1.5.1/agent-3d.js` answers 404 | `curl` on 2026-10-08; the 1.5.2 release commit `57c315696` said "1.5.1 stays immutable" |+| The archive is `gs://three-ws-lib-releases`, uploads use `--if-generation-match=0`, and the bucket has a retention policy of 315,295,200 seconds (just under ten years) that is not locked | [`scripts/release-lib.mjs`](../../scripts/release-lib.mjs); `gcloud storage buckets describe gs://three-ws-lib-releases` |+| Every deploy lays out each released version from the archive and refuses bytes that do not match the ledger; moving channels follow the current build; publishing refuses a version that was never released | [`scripts/publish-lib.mjs`](../../scripts/publish-lib.mjs), `fetchReleaseFile` in [`scripts/lib/agent-3d-releases.mjs`](../../scripts/lib/agent-3d-releases.mjs) |+| `check:dist` re-hashes released files and checks `versions.json` and documented pins; `npm run check:sri-pins -- --fix` rewrites stale doc pins; the same check runs under `npm test` | [`scripts/check-dist.mjs`](../../scripts/check-dist.mjs), [`scripts/check-sri-pins.mjs`](../../scripts/check-sri-pins.mjs), [`tests/agent-3d-releases.test.js`](../../tests/agent-3d-releases.test.js) |+| A released version is never re-cut with different bytes; `--from https://three.ws` froze 1.5.2 at the bytes production served | [`scripts/release-lib.mjs`](../../scripts/release-lib.mjs); ledger `source` field is `https://three.ws/agent-3d/1.5.2/` |+| The embed now resolves its API origin from its own script URL, sends cookies only when the page is three.ws, and anonymous public reads answer any origin | commit `fb067d0f2`; [`src/shared/embed-api-origin.js`](../../src/shared/embed-api-origin.js); `embedReadCors` in [`api/_lib/http.js`](../../api/_lib/http.js) |+| Production on 2026-10-08 runs commit `76081013b`, built 2026-10-01 19:31 UTC, so `fb067d0f2` is not live yet | https://three.ws/api/version |+| `/agent-3d/1.5.2/integrity.json` and `/agent-3d/versions.json` serve the ledger hashes | https://three.ws/agent-3d/1.5.2/integrity.json, https://three.ws/agent-3d/versions.json |++## Do not claim++1. **Do not claim a number of embeds or pages.** We have no measured count of sites embedding the+ element. "Pages we do not own" is true; "thousands of pages" is not verified.+2. **Do not claim the origin fix is live** until `curl -s https://three.ws/api/version` reports a+ commit at or after `fb067d0f2`. If it has shipped by posting day, change the last sentence of+ post 9 to say it is live and the first clause of post 10 to "that fix reached latest, 1 and 1.5".+3. **Do not claim the UMD build works from a plain script tag.** On 2026-10-08,+ `/agent-3d/1.5.2/agent-3d.umd.cjs` is served as `application/node` with `nosniff`, and Chromium+ refuses to run it. The bytes hash correctly; the header is wrong. Fix the content type before+ anyone points readers at the UMD file.+4. **Do not claim older versions are still available.** Only 1.5.2 is in the ledger; 1.5.1 and+ earlier answer 404.+5. **Do not call the archive permanent or locked.** The retention policy is real and not locked.+6. **Do not say the moving channels cache for "5 minutes" without qualification.** The edge caches+ for 5 minutes; browsers may keep the file for an hour.+7. **Do not imply AWS hosting.** Runtime and archive are on Google Cloud. The AWS article maps the+ patterns to S3 and CloudFront; it does not describe something we run there.++---++## The thread++Eleven posts. Counts are X weighted characters with every URL, and every bare domain X would+auto-link (`three.ws`, `example.com`), counted as 23.++**1/** (509 characters) Attach `same-url-two-pins.png`.++```text+For three and a half months, the URL we told developers would never change, https://three.ws/agent-3d/1.5.2/agent-3d.js, was rewritten on every deploy.++Our own docs carried two different integrity hashes for that one file, and production served a third. Browsers refuse a script whose hash does not match, so a page that followed our tutorial to the letter got a blank space where the 3D avatar should be.++We fixed it on Oct 1. This is how the release pipeline for our embeddable web component works now, and what we got wrong.+```++**2/** (711 characters) Attach `docs-cdn-versioning.png`.++```text+The embed is two lines of HTML: a script tag that loads the <agent-3d> custom element, and the element pointed at a 3D body. That script then runs on pages we never see.++So the same file is served two ways:++Moving channels (latest, 1, 1.5) follow whatever is deployed. Edge cache 5 minutes, browser up to an hour. For prototypes.++Exact versions (1.5.2) are served "max-age=31536000, immutable". That header tells every browser and CDN the bytes will never change, so they never ask again. For production, pinned with a Subresource Integrity hash.++The second contract is a promise you cannot take back. If the bytes move, caches split visitors into two groups running different code under one version number.+```++**3/** (570 characters)++```text+Subresource Integrity is a hash in the script tag: integrity="sha384-...". The browser downloads the file, computes its SHA-384, and compares. On a mismatch it does not run the script, and the host page's console says:++"Failed to find a valid digest in the 'integrity' attribute ... The resource has been blocked."++For an embedder that is the right trade. If anything between them and us serves different bytes, mistaken or malicious, their page fails closed.++The price is on us: a pinned URL has to be byte-stable forever, and the browser enforces it with no appeal.+```++**4/** (673 characters)++```text+The bug was one line in our publish step:++const channels = [version, `${major}.${minor}`, major, 'latest'];++All four directories were written from the current build. That is fine on the day a version is cut. It breaks the day after, because nothing forces the version string to change when the code does.++Version 1.5.2 was cut on June 17. package.json stayed at 1.5.2 until October 1. Every deploy in between rewrote the "immutable" file.++Same root cause, quieter casualty: the old step only wrote the current version, so 1.5.1 vanished the day 1.5.2 shipped. It answers 404 today.++A release was a side effect of a deploy. It has to be a record that deploys read from.+```++**5/** (552 characters)++```text+Fix, part one: a write-once archive.++Releasing a version uploads its two files to a public Google Cloud Storage bucket with --if-generation-match=0, a precondition that fails if anything already exists at that path. Our own tools cannot overwrite a release.++The bucket also carries a retention policy of just under ten years, so an object cannot be deleted or replaced until it is that old. That covers a person with credentials and a bad afternoon.++Two layers on purpose: a precondition is opt-in per request, and a hand-typed upload can forget it.+```++**6/** (630 characters)++```text+Fix, part two: a ledger the build has to obey.++data/agent-3d-releases.json, in git, records the SHA-384 of every file of every release.++On every deploy, each released version is downloaded from the archive, hashed, and written out only if it matches the ledger. A mismatch stops the deploy instead of publishing altered bytes. Moving channels still follow the current build.++Two more guards: publishing refuses to run when package.json names a version that was never released, so bumping a number can no longer mint a release by accident. And check:dist re-hashes what actually landed in the build output before anything ships.+```++**7/** (738 characters)++```text+Fix, part three: documentation is a pin too.++The incident was found in our docs, so the build now treats them as release surface. A scanner finds every script tag that loads a versioned agent-3d file with an integrity attribute, across docs, specs, examples, the README, packages and the skill files we ship to AI coding agents, and fails the build if one disagrees with the ledger. check:sri-pins --fix rewrites a stale hash; a pin on a version that was never released stays an error until a person fixes it. The same check runs under npm test.++Then the hard call: which of the three hashes becomes permanent. We froze 1.5.2 at the bytes production was serving, so live embeds kept working. Anyone holding an older pin updates it once.+```++**8/** (310 characters)++```text+Check it yourself. These three should print the same hash:++curl -s https://three.ws/agent-3d/1.5.2/agent-3d.js | openssl dgst -sha384 -binary | openssl base64 -A++The same file from the archive:+https://storage.googleapis.com/three-ws-lib-releases/agent-3d/1.5.2/agent-3d.js++The recorded value:+https://three.ws/agent-3d/1.5.2/integrity.json++On Oct 8 all three were sha384-KdAiFRsdcCbQ..., 3,308,933 bytes.+```++**9/** (790 characters)++```text+The second lesson came two days later, and it is about where an embed's code thinks home is.++On our own site, fetch('/api/agents/' + id) calls us. Inside an embed on example.com, the same line asks example.com for an agent, gets a 404, and the avatar falls back to a default body.++The fix: an ES module knows its own URL through import.meta.url, so the element now derives the API origin from the script that loaded it, and threads that through the modules that call our API. Cookies are sent only when the page is three.ws itself. On the server, a read with no cookie and no auth header can only see public data, so it answers any origin; anything carrying identity keeps the strict allowlist.++That fix is committed and ships with our next deploy.+```++**10/** (567 characters)++```text+The limit, said plainly: when that fix deploys, it reaches latest, 1 and 1.5 immediately. It will never reach 1.5.2.++Those bytes are frozen. A page pinned to 1.5.2 keeps the old behavior until its owner moves to a newer release, which exists once we cut 1.5.3.++That is the design, not a flaw in it. A pinned embedder chose to receive no changes without consent, including good ones. What it asks of us is to cut releases often enough that "upgrade to get the fix" is a real option, and the last three and a half months show that is the habit we still have to build.+```++**11/** (366 characters)++```text+The pinning guide, the channel table and the current integrity hash for production embeds:+https://three.ws/docs/web-component#cdn-versioning++If your page pins 1.5.2 with a hash from before October 1, replace it once with the value in /agent-3d/1.5.2/integrity.json. It will not change again.++The release scripts are short, Apache-2.0, and written to be lifted whole:+https://github.com/nirholas/three.ws/blob/main/scripts/release-lib.mjs+```++---++## Reply to append once the AWS article is live++Post this as a reply under post 11 only after the AWS Builder Center article has been published.+Whoever publishes it pastes the article's canonical Builder Center URL directly after the colon,+separated by one space, before posting. Without the URL it measures 125 characters; with the space and the URL it is 149.++```text+The long version, with every script excerpted and a mapping onto S3 Object Lock and CloudFront, is on the AWS Builder Center:+```++---++## Media plan++Both images were captured on 2026-10-08 with Playwright (headless Chromium) against the live site+and checked by eye: no sign-in wall, no spinner, no error page, and the avatar is in its idle pose,+not a T-pose. They live in+[`public/x-media/immutable-embed-releases-thread/`](../../public/x-media/immutable-embed-releases-thread/).++**`same-url-two-pins.png`** (3200x1800), for post 1. A plain host page on a non-three.ws origin,+written for this capture, with two isolated frames. Both load `https://three.ws/agent-3d/1.5.2/agent-3d.js`;+only the `integrity` attribute differs. The status line under each frame is written by the script+tag's own `load` or `error` event, not typed in.++> Alt text: Two side-by-side frames on a page headed "Same URL, two integrity pins". Both load the+> same three.ws script URL for version 1.5.2. On the left, pinned to the hash in the release ledger,+> a 3D avatar of a woman in glasses and a purple and grey tracksuit stands in an idle pose, and the+> caption reads "script ran: integrity matched the served bytes". On the right, pinned to the hash+> our tutorial carried before October 1, the frame is empty and the caption reads "browser refused+> the script: integrity mismatch".++**`docs-cdn-versioning.png`** (2800x1800), for post 2. The CDN versioning section of+https://three.ws/docs/web-component in dark mode.++> Alt text: The three.ws documentation page for the agent-3d web component, open at the "CDN+> versioning" section. A table lists four script paths: the exact MAJOR.MINOR.PATCH version marked+> immutable and "Production. Pin exact bytes. Combine with SRI.", then the minor, major and latest+> channels for following newer code. Below it, a section titled "What immutable guarantees"+> explains that each version is cut once by npm run release:lib into a write-once archive and+> recorded in data/agent-3d-releases.json.++Note on the docs capture: the table on that page says "5 min" for the moving channels. That is the+edge cache (`s-maxage=300`); the response also allows browsers to keep the file for an hour+(`max-age=3600`). Post 2 states both, which is why its wording differs from the screenshot.diff --git a/docs/x-posts/universal-retargeting-thread.md b/docs/x-posts/universal-retargeting-thread.mdnew file mode 100644index 000000000..0b46fe528--- /dev/null+++ b/docs/x-posts/universal-retargeting-thread.md@@ -0,0 +1,209 @@+# X thread: one clip library, any humanoid skeleton++Thread copy for `@trythreews`, the companion to the AWS Builder Center draft+[`aws-builder-center-universal-retargeting.md`](../aws-builder-center-universal-retargeting.md).+It explains how three.ws plays one pre-baked animation library on humanoid avatars from many+different exporters, in the browser, with no list of approved rigs, and it leads with the newest fix+in that path: A-pose avatars no longer swing their arms through their own torso.++**Thesis:** a matching bone name is the smaller half of retargeting. The larger half is rest poses+and axis conventions, and the platform handles both without a rig allowlist. No token talk, no+payments, no roadmap.++**Posting precondition (hard).** The news hook in post 1 and the mechanism in post 7 describe commit+`8561d5c5d` (merged 3 October 2026). When this draft was written, production was serving commit+`76081013b`, which predates it. Do not post until this prints `deployed`:++```bash+git merge-base --is-ancestor 8561d5c5d \+ "$(curl -s https://three.ws/api/version | node -e 'let s="";process.stdin.on("data",d=>s+=d).on("end",()=>console.log(JSON.parse(s).commit))')" \+ && echo deployed+```++Posting is owner-gated like everything in this folder (see [README](./README.md)).++## Verified claims++Each claim the thread makes, and where it was checked on 2026-10-08.++| Claim | Verified at |+| --- | --- |+| 113 clips in the library | `public/animations/manifest.json` (113 entries) and the live `https://three.ws/animations/manifest.json` (113) |+| Clips are baked once onto one reference skeleton (`cz.glb`) | `scripts/build-animations.mjs` header; `src/animation-canonical-rest.js` is generated from `public/avatars/cz.glb` |+| 52 canonical joints | `CANONICAL_BONES` in `src/glb-canonicalize.js` (52 entries); live `/rig-doctor` shows "52 canonical joints scored" |+| 30 of a clip's 53 retargetable tracks are fingers | measured over `public/animations/clips/*.json`: 110 of 113 clips have 53 rotation-plus-hip tracks, 30 of them finger joints |+| A clip plays only if at least half its tracks map | `MIN_COVERAGE = 0.5` in `src/animation-retarget.js` |+| A rig needs a skinned mesh and 8 canonical bones | `_modelSupportsCanonicalClips` and `MIN_CANONICAL_BONES = 8` in `src/animation-manager.js` |+| The 12 elbow spellings in post 3 all resolve to `LeftForeArm` | each run through `canonicalizeBoneName` in `src/glb-canonicalize.js` |+| Rigify and SMPL clavicle/upper-arm clash, resolved by contention then hierarchy | `resolveArmShoulderCollisions` in `src/glb-canonicalize.js`; tests in `tests/glb-canonicalize.test.js` |+| Mixamo bakes +90 X on the armature and -90 X on the hips | comments and `canonicalizeArmatureOrientation` in `src/glb-canonicalize.js`; `src/animation-retarget.js` |+| A Mixamo avatar lay 92 degrees off vertical during idle before the bind correction, 7.3 after | empirical table in the header of `tests/animation-upright-invariant.test.js` |+| The correction is q' = L · q · R from each bone's local and world rest | `bindCorrections` in `src/animation-retarget.js` |+| The reference rig rests in a T-pose | computed from `CANONICAL_REST_POSITION` in `src/animation-canonical-rest.js`: upper arms and forearms within a fraction of a degree of horizontal |+| The idle swings the reference upper arm a little over 70 degrees down | forward kinematics on the reference skeleton with frame 0 of `public/animations/clips/idle.json` (71.6 and 76.5 degrees) |+| Upper arms, forearms, thighs and shins are re-aimed; feet keep their world rest; hands and fingers inherit | `LIMB_DIRECTION_CHILD`, `WORLD_REST_BONES` and `restAlignments` in `src/animation-retarget.js`, commit `8561d5c5d` |+| Only rotations and the hip translation cross over; hip motion is rescaled to the avatar's height | `retargetClip` in `src/animation-retarget.js`; `_retarget` in `src/animation-manager.js` |+| A clip that would tip the hips past 45 degrees is disabled | `CATASTROPHE_TILT_DEG = 45` and `_guardAgainstFallenPose` in `src/animation-manager.js` |+| Unmapped arms are found by direction and swung down | `src/animation-arm-relax.js` |+| 477 tests in the canonicalizer suite | `npx vitest run tests/glb-canonicalize.test.js` on 2026-10-08: 477 passed |+| A test runs without the fix and asserts the avatar falls | "the test has teeth" in `tests/animation-upright-invariant.test.js` |+| 10 of 10 naming conventions move both arms and both legs | `node scripts/animation-dignity-sweep.mjs` on 2026-10-08: "10/10 conventions animate both arms and both legs on both lanes" |+| Biped fingers, ValveBiped, and colon-stripped HumanIK names do not map | `canonicalizeBoneName('Bip01 L Finger0')`, `('ValveBiped.Bip01_Pelvis')`, `('Character1Hips')` all return `null`; listed as open in `docs/first-contribution.md` |+| A Biped rig with fingers gets no clip | scratch test against current code: idle maps 21 of 53 tracks (39.6 percent), `clip: null` |+| Rig Doctor reads the file in the browser and never uploads it | `src/rig-doctor-page.js` header (FileReader, blob URL); live page copy "Nothing is uploaded" |+| Rig Doctor recognises 15 conventions | `CONVENTION_COUNT` in `src/rig-report.js` (15); live `/rig-doctor` shows "15 rig conventions recognised" |++## Do not claim++1. **Do not post before the precondition passes.** The A-pose re-aim is merged, not deployed, as of this draft.+2. **Do not say "any rig" or "every avatar" without "humanoid".** Non-humanoid skeletons are refused on purpose, and three humanoid conventions (Biped fingers, ValveBiped, colon-stripped HumanIK) still fail. The thread says so in post 11; keep it.+3. **Do not quote a convention count other than 15 (Rig Doctor fingerprints) or 10 (the motion sweep).** The canonicalizer's header lists more spellings than that, but nobody has counted them into a defensible number.+4. **Do not say the re-aim is tested.** It shipped without a dedicated unit test. The upright suite and the sweep predate it.+5. **Do not say the npm package has the re-aim.** `@three-ws/retarget` 0.1.2 (published 2026-09-11) predates it. The Animation Studio gallery and GLB export (`retargetClipToRig`) got it in a follow-up commit, so the same deploy precondition applies to them.+6. **Do not call it AI or machine learning.** It is deterministic name tables and quaternion math.+7. **Do not imply AWS hosting.** The companion article is on the AWS Builder Center; the platform runs on Google Cloud Run and retargeting runs in the browser.+8. **Do not name other animation tools or engines as comparisons.** Exporter names appear only as the conventions we read.++---++## The thread++Counts are X weighted characters, with the one URL counted as 23. Every post is under the+1000-character Premium ceiling and over 280, per [the announcement voice](../announce-voice.md).++**1/** (466)++> Every animation on three.ws was baked once, onto one reference skeleton. All 113 clips then play, in the browser, on avatars it has never seen: Mixamo, VRoid, Unreal mannequins, Daz figures, Blender exports, hobby rigs with bones named shoulderL.+>+> Our latest fix closes the stance gap: avatars that rest in an A-pose no longer swing their arms through their own torso.+>+> How one clip library drives any humanoid skeleton, with no list of approved rigs:++**2/** (408)++> A clip does not store a body. It stores tracks, and each track names the joint it turns: Hips, LeftForeArm, RightUpLeg. 52 joint names in all.+>+> Load a rig whose elbow is called lowerarm_l and that track binds to nothing. No error. The model renders, the mixer runs, and the avatar stands frozen in its bind pose with its arms straight out.+>+> So step one is turning every exporter's spelling into one spelling.++**3/** (499)++> The canonicalizer strips vendor prefixes and namespaces, folds separators and case, then looks the rest up in alias tables, in a fixed priority order so an obscure convention can never shadow a common one.+>+> These all resolve to LeftForeArm:+>+> mixamorig:LeftForeArm+> lowerarm_l+> J_Bip_L_LowerArm+> leftLowerArm+> lForeArm+> forearm.L+> CC_Base_L_Forearm+> Bip01 L Forearm+> ElbowLeft+> mElbowLeft+> elbowL+> ulna.L+>+> Left spellings are written once; the right side is derived, and a test checks no name ever crosses sides.++**4/** (403)++> Fingers decide more than they look like they should. 30 of a clip's 53 tracks are finger joints, and a clip only plays when at least half its tracks find a home.+>+> So a rig whose body maps perfectly but whose hands don't scores about 43 percent and gets no animation at all. Not stiff fingers: nothing.+>+> That is why finger chains are mapped convention by convention, from index_01_l to leftIndexProximal.++**5/** (457)++> Some names can't be settled by spelling. Rigify calls the collarbone shoulder.L. SMPL calls the upper arm left_shoulder. A hobby rig calls its upper arm shoulderL and has no collarbone at all.+>+> Any name-only rule breaks one of the three. So the clash is resolved by contention: a joint is only reassigned when two joints fight over one name and the sibling slot is empty. If there is still a tie, the hierarchy decides, because the collarbone is the parent.++**6/** (526)++> Matching names is the smaller half.+>+> A clip stores absolute rotations measured against the reference rig's rest pose and axes. Mixamo exports bake +90 degrees into the armature and -90 into the hips. Copy the clip verbatim and the hips lose their -90: our Mixamo test avatar played its idle lying 92 degrees off vertical.+>+> The fix replays each bone's motion as the same change in world space from the target's own rest: q' = L · q · R, built from each bone's local and world rest rotation. Same avatar, same idle: 7.3 degrees.++**7/** (532)++> Then the A-pose problem. The reference rig rests in a T-pose, and the idle swings its upper arm a little over 70 degrees down from there. Apply that same swing to an arm that already hangs down in an A-pose, and the hand ends up inside the chest.+>+> Now, before the motion replays, each upper arm, forearm, thigh and shin is turned from its own rest direction onto the reference's. Hands and fingers inherit the turn, feet keep their own rest so soles stay flat, and the spine is left alone because its angles are anatomy, not stance.++**8/** (433)++> Only motion crosses over. Some clips carry a position and scale for every bone, and those encode the reference rig's bone lengths. Copy them onto an avatar with different proportions and its skeleton folds into a heap, even though every bone matched.+>+> So only joint rotations and the hip translation retarget, and the hip track is rescaled to the avatar's own hip height, measured from its own floor. Every rig keeps its proportions.++**9/** (513)++> It would rather leave an avatar alone than animate it badly:+>+> No skinned mesh, or fewer than 8 recognised joints: treated as a prop, shown as authored.+> Under half of a clip's tracks mapped: that clip does not play.+> A clip that would tip the hips past 45 degrees: disabled for that avatar, and reported.+> Body maps but arms don't: the stuck arms are found by direction, no name needed, and swung down to the sides.+>+> In shared scenes, a rig that fails is swapped for a known-good one instead of standing in a T-pose.++**10/** (413)++> The tests are written so they can fail. 477 name tests, one table of real export spellings per convention. An upright suite that also runs WITHOUT the correction and asserts the avatar falls over, so it would catch anyone removing it.+>+> And a motion sweep, because names passing is not limbs moving: idle and walk on 10 differently named rigs, measuring hand and foot travel. 10 of 10 move both arms and both legs.++**11/** (479)++> Where it still fails, plainly. A 3ds Max Biped rig maps its body but not its numbered fingers (Bip01 L Finger0), so it lands under the half-the-tracks line, gets no clip, and shows its bind pose. Source-engine ValveBiped rigs and HumanIK names with the colon stripped don't map either. All three are open contributor tasks.+>+> And no retargeter can fix skinning: a sleeve weighted to the wrong bone bends with that bone.+>+> The re-aim from post 7 also has no dedicated unit test yet.++**12/** (281)++> Try it on your own avatar. Drop a .glb on Rig Doctor and it names your skeleton's convention, scores torso, arms, hands and legs, lists the bone renames, and plays idle, walk, wave and dance on your rig. The file is read in your browser and never uploaded.+>+> three.ws/rig-doctor++---++## Reply to append once the AWS article is live++Post this as a reply to post 12 after the AWS Builder Center article is published. Whoever+publishes pastes the article's URL directly after the colon; with the URL counted as 23 the reply+measures 144 characters.++> The full write-up, with the code excerpts, the tests, and what we would build differently, is on the AWS Builder Center:++---++## Media plan++Three stills, captured on 2026-10-08 with Playwright (headless Chromium, SwiftShader WebGL) against+`https://three.ws/rig-doctor?sample=...`, which is reproducible from those URLs. They are in+[`public/x-media/universal-retargeting-thread/`](../../public/x-media/universal-retargeting-thread/).+Each was checked by eye: no sign-in wall, no spinner, no error, no T-posed avatar. For the two+report captures, the site's floating corner widgets (the walking companion and the help stack)+were hidden with CSS so they would not cover the panels; nothing inside the report was altered.++The captures were taken while production ran `76081013b`, before the A-pose fix. The avatar shown is+a Mixamo rig, which rests in a T-pose, so the fix does not change how it looks. If you film a reel+for post 1 instead (the voice guide's first rule, `npm run x:content -- prove <id>`), film it after the+precondition passes, on an A-pose avatar.++| File | Attach to | Alt text |+| --- | --- | --- |+| `rig-doctor-walk-preview.png` | Post 1 | A stylized 3D woman in a grey crop top, yellow trousers and red headphones walks toward the camera mid-stride, one foot ahead of the other, inside Rig Doctor's live preview panel on three.ws. The Walk button is selected beside Idle, Wave and Dance, with the caption "This is the same retargeting path the platform uses." |+| `rig-doctor-mixamo-report.png` | Post 3 | Rig Doctor's report for a Mixamo avatar named michelle.glb. A green Ready banner reads "Every limb group is drivable. This rig performs the full clip library." and "52 of 52 canonical joints mapped from a Mixamo rig." Coverage bars show torso 6 of 6, arms 8 of 8, hands 30 of 30 and legs 8 of 8. A bone rewrites panel maps mixamorig:Hips to Hips, mixamorig:LeftArm to LeftArm and so on, with the avatar standing at rest, arms at her sides, in the live preview. |+| `rig-doctor-partial-verdict.png` | Post 11 | Rig Doctor's amber Partial verdict for a half-body avatar: "This rig animates, but arms and legs will not move. 36 of 52 canonical joints mapped." It lists arms at 2 of 8 joints mapped and legs at 0 of 8, names the missing joints, and notes that without legs a walk cycle plays as a slide. |++The partial-verdict capture is cropped to the banner on purpose: on that sample the live preview+panel rendered empty in our headless run, so it is not shown.