Support document-selected avatar appearances alongside the humanoid rig

[edib]

Description

Add document-selected character appearances without changing Posecode's skeleton topology. rig remains humanoid; an optional avatar avatar1|avatar2|avatar3 directive selects a character through the renderer's characterUrls map. Documents without avatar continue to use the humanoid default.

Character load failures and unmapped selectors always restore the procedural mannequin, so an unavailable asset cannot leave the scene blank.

What changed

• posecode-parser / language v0.4: adds the optional avatar directive and IR field while keeping rig humanoid as the only rig topology.
• posecode-render: adds document-driven characterUrls selection while preserving fixed characterUrl precedence. Character swaps use latest-request-wins semantics, dispose stale async loads, allow retry after failure, reset clip state safely, and restore the procedural fallback.
• posecode-embed: absent character uses document-driven selection; an explicit GLB URL still pins one character and character="off" still disables skinned characters.
• playground assets: avatar1 intentionally reuses the existing XBot instead of committing a duplicate. avatar2.glb and avatar3.glb are included; avatar3 was reduced from about 35 MB to 7.4 MB.
• Editor/tooling parity: completion, hover vocabulary, LSP conversion, CodeMirror highlighting, and VS Code syntax support the new directive.
• Release safety: adds a changeset and extends the renderer's parser peer range so this remains an additive minor release instead of cascading to 1.0.0.
• Tests/docs: adds parser/tooling tests, async lifecycle race tests, specification updates, generated reference pages, and embed/renderer documentation.

Validation

Validated again against the current main merge result:

• npm test — 47 test files, 463 tests passed
• npm run typecheck
• npm run build
• npm run build:packages
• npm run check:packages
• npm run changeset -- status — minor release, no accidental major bump
• npm run eval — 1620/1620 checks across 77 movements
• Both new GLBs contain a skin and every required Mixamo bone

Required before merge

• Confirm the source and redistribution/license terms for avatar2.glb and avatar3.glb, then add the appropriate entry to docs/legal/THIRD_PARTY_NOTICES.md. The GLB metadata alone is not sufficient to establish provenance.

[vercel]

@edib is attempting to deploy a commit to the johndoe's projects Team on Vercel.

A member of the Team first needs to authorize it.

[a-baran-orhan]

@edib I prepared and validated the follow-up fixes here: edicate#1

Because #124 has maintainer edits disabled, please merge that draft PR into edicate/posecode:main; #124 will update automatically and remain authored by you.

The follow-up separates avatar appearance from rig humanoid, hardens async character swapping/fallbacks, removes the duplicate avatar1 asset, reduces avatar3 from ~35 MB to 7.4 MB, adds race/parser/tooling tests and a changeset, fixes the release peer range, and removes unrelated diff noise.

Validation passed: 463 tests, typecheck, production/package builds, package checks, and 1620/1620 movement eval checks.

One blocker still needs your input before merge: please confirm the source/license provenance for avatar2 and avatar3 so the correct third-party notice can be added.

[a-baran-orhan]

@edib Thanks for merging the hardening follow-up. To clear the remaining asset-license blocker, could you please reply with the following for both avatar2.glb and avatar3.glb?

1. Original download/source page URL
2. Creator and source platform
3. Exact license or terms URL that permits redistribution in this repository
4. Any modifications or conversion steps applied before committing the GLB

The files' embedded metadata identifies Blender/glTF tooling but does not identify the creator or redistribution terms. Once these details are available, we can add an accurate THIRD_PARTY_NOTICES.md entry instead of guessing.

[a-baran-orhan]

I prepared a follow-up that keeps the avatar-selection feature while removing the two bundled GLBs whose redistribution provenance has not been established:

edicate#2

The follow-up:

• removes avatar2.glb and avatar3.glb plus their built-in URLs;
• keeps avatar avatar1|avatar2|avatar3, renderer hot-swapping, and host-provided characterUrls intact;
• makes unmapped avatar2 / avatar3 selections use the existing procedural fallback;
• documents that future bundled assets need verified redistribution rights.

Verification is green: 463 tests, package builds, full typecheck, playground production build, package validation, and git diff --check.

@edib, please merge the follow-up into your main branch so this PR updates automatically. Licensed avatar2/avatar3 assets can be added later once their source and redistribution terms are documented.

[a-baran-orhan]

Status from a maintainer sweep of the open PRs:

• CI is green. Build & Test passes on this branch.
• The red Vercel check is not a code failure. It is the fork-authorization prompt for preview deployments, not a build error, so it should not be read as a defect in this PR.
• The one real blocker is the unchecked item in this PR's own description: the source and redistribution terms for playground/public/models/avatar2.glb and avatar3.glb still need to be established, with a matching entry in docs/legal/THIRD_PARTY_NOTICES.md. GLB metadata alone is not sufficient provenance, and this repo already tracks Mixamo-derived assets separately from its Apache-2.0/AGPL-3.0 code (see docs/legal/LEGAL_REVIEW.md). That is a licensing decision, not something CI can settle, so the PR stays open until it is resolved.

Note that main has moved since this branch was pushed: dependency updates landed in #128 and #129, CI now runs on Node 24, the release workflow moved to changesets/action@v2, and the published packages are now at 0.4.3. A rebase will be needed, and maintainerCanModify is off on this branch so it has to be done from the fork side.

[a-baran-orhan]

Landed on main via #130.

This PR could not be merged directly: its required Vercel status check stays red because fork preview deployments are unauthorized, branch protection uses a strict up-to-date policy, and maintainerCanModify is off on this branch, so it could not be updated to current main from the maintainer side either. #130 merges the commits from this branch into current main with their authorship intact — bec1c7e, 34cbfce and 5aea4e3 are on main credited to @edib.

Two things were resolved on the way in:

• Rebased onto current main (0.4.3, Node 24 CI, changesets/action@v2), with package-lock.json resynced to the 0.4.3 workspace versions.
• The unchecked "Required before merge" item is settled. The characters' provenance is established from the glTF contents: both carry the mixamorig: skeleton, a mixamo.com animation track, and Mixamo mesh and texture names (Beta_Joints/Beta_Surface and Remy_Body_*). They are Adobe Mixamo's Beta and Remy characters, the same category as the already-committed xbot.glb, and they are now listed in docs/legal/THIRD_PARTY_NOTICES.md and docs/legal/LEGAL_REVIEW.md.

Thanks for the contribution.