feat: item-backed container menus (Phase 3)

[KP2048]

Phase 3 of the pre-release storage/GUI plan: item-backed container menus

Adds ComposeItemContainerMenu, an ItemStack-backed sibling of the existing BlockEntity-backed
menu (renamed ComposeContainerMenu → ComposeBlockContainerMenu to match) — e.g. for a
backpack/bag with its own GUI.

3a — base-class extraction

Extracted ComposeContainerMenuBase<SELF> from ComposeContainerMenu, holding the ~95% of slot
layout/registration/quickMoveStack machinery that's already fully holder-agnostic.
ComposeBlockContainerMenu keeps tile/blockEntityState/BlockEntityStateManager
registration; new onMenuOpened()/onMenuClosed(player) hooks let each subclass register
whatever state-tracking its holder needs. Added isPlayerSlotExcluded(index) to freeze one
player-inventory slot in place (mayPlace/mayPickup false, special-cased in quickMoveStack
too) — used by ComposeItemContainerMenu to stop a backpack's own inventory slot accepting
placement or being shift-clicked into itself while its GUI is open. ComposeContainerScreen drops
its second (BlockEntity) type parameter, now <T : ComposeContainerMenuBase<T>>.

Caught and fixed before it shipped: calling onMenuOpened() from
ComposeContainerMenuBase's own init block dispatched into the subclass's override before
the subclass's own constructor-parameter properties (tile/itemAccess) were assigned — a
"leaking this during construction" NPE trap. Each concrete subclass now calls it from its own
init, after its own state is ready.

3b — @Sync wiring for item-backed NBTHolder fields

New SyncedItemHolder interface. ItemStackNBTHolderImpl's field declarations now push through
it the same way NBTHolderImpl already does for BlockEntity, and getSyncTag() is implemented
for real (was a stub returning an empty tag).

Also fixed a real, pre-existing bug this surfaced (not introduced by this change, but first
actually exercised by it): ItemStackNBTHolderImpl's init { loadFromStack() } runs before any
field is declared, so loadFromTag's itemStorage/fluidStorage/energyStorage re-hydration
loop always iterated an empty map — itemField/fluidField/energyField never actually loaded a
previously-saved stack's data into the freshly-constructed storage. Fixed by hydrating each
storage directly from already-loaded raw data at declaration time instead.

3c — the menu itself

ItemContainerAccess (+ PlayerInventoryItemAccess) locates the backing stack, re-resolved fresh
every call since the underlying reference can be swapped out from under the menu.
ComposeItemState/ItemStatePacket/ItemUpdatePacket mirror the BlockEntity state-sync path,
reusing BlockEntityStatePacket.SerializedValue directly; routing needs no position-keyed lookup
on either side since an item-backed menu is inherently 1:1 with one player's session —
context.player.containerMenu is always "the current menu." ItemStateManager drives per-tick
dirty-property sync and force-closes a menu whose itemAccess.stillValid(player) goes false.

Verification

New ComposeItemContainerMenuTests (server, direct construction against
makeMockServerPlayerInLevel — no network round trip) covers slot-content persistence,
stillValid, @Sync serializer registration at declaration time, and ItemStateManager's real
tick-driven force-close. New ComposeItemContainerMenuClientTests (client, real
MenuRegistry.openExtendedMenu + a real TestItemContainerScreen layout pass) covers the
excluded-slot mayPlace/mayPickup/quickMoveStack behavior, which needs updateSlotData to
have actually run — unreachable from a server-only GameTest since packet registration itself is
skipped there (Archie.kt's own gating, unrelated to this feature).

[GameTest] PASS archie:composeitemcontainermenutests.testslotcontentpersiststhroughholder
[GameTest] PASS archie:composeitemcontainermenutests.testitemstatemanagerforceclosesinvalidmenu
[GameTest] PASS archie:composeitemcontainermenutests.teststillvalidreflectsitemaccess
[GameTest] PASS archie:composeitemcontainermenutests.testsyncedfieldregistersserializer
[ClientGameTest] PASS archie_test:testscreengametest.testshowcasescreenopensandconfirmdialogroundtrips
[ClientGameTest] PASS archie_test:composeitemcontainermenuclienttests.testexcludedslotbehaviorviarealmenuopen

Not covered — manual-only, matching precedent (full Compose rendering + real player interaction
isn't GameTest-covered anywhere else in this codebase either): the actual on-screen backpack
open/close/shift-click flow beyond what the client test above exercises, and copyOnDeath-style
cross-mod capability-lookup interop combining Phase 1's exposeItemStorage with a
Phase-3-backed backpack.

Docs: docs/gui.md gets a new ComposeBlockContainerMenu/ComposeItemContainerMenu section plus
an expanded state-sync paragraph covering observeItemProperty; docs/transfer.md's "Wiring
storage into a menu" section now shows both menu kinds.

Final piece of the three-feature pre-release plan (capability lookup / data attachments /
item-backed container menus) — #12 and #13 cover the first two.

Rebased onto latest 1.21.x (picking up #10/#11) before opening; both GameTest suites re-verified
green afterward.

🤖 Generated with Claude Code