feat(viewer): plugin loop clips listed, run in the baked viewer and targeted in the walkthrough (AK-09 2/2)

[Aymericr]

AK-09 first slice, part 2 of 2. Stacked on #954; it targets main, so until #954 merges its diff includes #954's commits. This PR's own commits: compare.

What and why

A plugin kind's baked loop clip was never listed (glb-export.ts listed extras.clips only for item and procedural-item), so the baked viewer could not play it. The editor walkthrough and the baked viewer only knew item, procedural-item and openables.

• GLB export: every node that baked clips lists them in extras.clips. openable is still set only for an : open clip. In-tree, cabinets, doors and windows bake : open (already listed), and items and procedural items bake loops (already listed). The only newly listed clip is Articraft's <id>: loop, the only other exportAnimation among the hosted plugins.
• Baked viewer (data only, no plugin code): bakedLoopMechanisms finds nodes whose : loop clips no other controller owns, meaning no procedural playback, no scene-graph interactive item and not openable. Those loops start stopped. A click in the zone view and E or a click in the walkthrough toggle them through useInteractive.mechanisms, and the prompt reads "turn on/off". proceduralMotion extras and the door, window, item and procedural paths are unchanged.
• Editor walkthrough: any mounted node whose kind declares capabilities.mechanism is an E/click target (type: 'mechanism'), and the prompt verb comes from the capability's verb. Procedural per-part targeting and catalog item toggles run first, as before. They record the nodes they tested (covered), and the generic pass skips those, so no node is targeted twice and item/procedural targeting is unchanged.

Visible only once a plugin adopts it. The owner preview ships with the Articraft adoption (AK-ART).

Failing case first

aad1baa2e (tests only) on #954's code:

• glb-export.test.ts "lists any kind's registry loop clip": extras.clips is undefined. 0 pass, 1 fail.
• glb-mechanisms.test.ts and mechanism-targets.test.ts fail: neither module exists.

Proof

• bun run --cwd packages/viewer test: 392 pass, 0 fail.
• bun run --cwd packages/editor test: 1120 pass, 0 fail, including all 47 existing export tests (door, window, cabinet, item and procedural clips unchanged) plus the new one.
• bun run check: no errors. bun run check-types: every package passes. apps/editor fails on the missing local @webxr/plugin, as on main.
• private-editor bun typecheck against rebuilt core, viewer and nodes dists: 12/12.

Rule	Check
R1	API v1 unchanged. Export output is byte-identical for existing kinds; only nodes with loop-only registry clips gain extras.clips.
R6	Clips are still baked from the rest pose by each kind's exportAnimation; the extras contract (clips, openable, proceduralMotion) is unchanged and only extended to more kinds. Transient playback in the viewer.
R8	No agent surface in this slice. MCP creation of plugin kinds is still parked with A-07 flag-on.

R2–R5, R7 and R9 are unaffected.

House effect: no change. /next has no plugin mechanisms, and its bake lists the same clips.

For Wassim (procedural items, #930)

• first-person-controls.tsx: the procedural and item loops are untouched apart from covered.add(rawId). The new generic loop runs after them and skips covered ids.
• glb-scene.tsx: procedural playback owns its nodes (proceduralPlayback.entries), so its clips are excluded from the generic loops.

🤖 Generated with Claude Code

---

Note

Medium Risk
Extends GLB extras and viewer interaction paths and centralizes walkthrough/E behavior; changes are transient and scoped, but affect export output for new loop-only plugin clips and shared first-person targeting.

Overview
Introduces capabilities.mechanism so any node kind (including plugins) can expose moving parts through one transient switch in useInteractive.mechanisms, with nodeMechanism / toggleNodeMechanism helpers and no scene or undo writes.

Editor: a generic Play/Stop action appears for a single selected node with a mechanism; E runs runNodeInteraction (kind keyboardActions.e first, then mechanism). First-person walkthrough adds mechanism targets after procedural and catalog-item passes, with HUD verbs from the capability’s verb. Item and procedural-item wire itemMechanism / proceduralMechanism; per-kind Play/Stop is removed from item action contributions (lights only there).

Export & baked viewer: glb-export lists extras.clips for every node that baked animation, still setting openable only when a clip ends with : open. bakedLoopMechanisms drives unowned : loop clips in glb-scene from useInteractive.mechanisms on click and E, without changing procedural, interactive-item, or openable paths.

^{Reviewed by Cursor Bugbot for commit 07f5761. Bugbot is set up for automated code reviews on this repo. Configure here.}

[pascal]

I hit an error while handling your request (Model unavailable on AI Gateway free tier: Free tier users do not have access to this model. Upgrade to paid credits at https://vercel.com/d?to=%2F%5Bteam%5D%2F%7E%2Fai%3Fmodal%3Dtop-up for unrestricted…).

Please try again, rephrase, or reach out if it keeps failing.

Error id: c54a4136-348e-425c-95ef-04b9260b89f2