Port collections, dropped books, return links and Writing Desk to 26.3

ports/mc263/README.md

@@ -2,14 +2,15 @@
 
 This is an **experimental beta port** for issues #97–#104, not gameplay parity
 with the Minecraft 1.21.1 release. The 26.3 backend persists separate Ages and
-their seeds. Books, the Book Binder, and the Ink Mixer work, and the Binder can
+their seeds. Books, the Book Binder, Ink Mixer, Writing Desk and page collections
+are ported, and the Binder can
 author Standard, Amplified, Island, Flat, Void, or Cave terrain with supported
 biome-distribution pages, selected material/vegetation/structure features, and
 independent Age weather and lighting, multiple authored or seeded celestial
 bodies and eclipses, biome/material completion, and random features/structures.
-Instability, crystal portals, discovery/stations, writing recovery and optional
+Instability, crystal portals, remaining discovery/stations, writing recovery and optional
 integration parity remain unfinished. The latest published beta is
-[1.0.1.98-beta.1](RELEASE_NOTES_1.0.1.98-beta.1.md).
+[1.0.1.106-beta.1](RELEASE_NOTES_1.0.1.106-beta.1.md).
 Use a test world and keep a backup; do not
 substitute this JAR for the 1.21.1 mod or import 1.21.1 saves.
 
@@ -1413,6 +1414,238 @@ overflow/disabled budget arithmetic, unload/reload, reseed and full restart.
 No player was connected for the server checks, so live growth remains an
 in-game acceptance check. The test server was stopped and its world removed.
 
+### Non-collectible arrival platforms
+
+The local `1.0.1.99-beta.1` slice ports 1.21.1's dedicated `cloud_platform`
+block for fallback Age landings. It reuses the existing opaque Crystal Block
+texture, has glass-like breaking strength (0.3), and produces no loot or
+pick-block item. It has no item, recipe, Creative entry or generated material
+Page. Ordinary Crystal Blocks retain their normal behavior.
+
+New fallback platforms use this block. Existing platforms made from ordinary
+Crystal Blocks are not rewritten. This slice changes the fallback material;
+the port's existing landing search and 3-by-3 fallback footprint remain.
+
+Test a new Void Age: arrive on the platform, check its appearance and footing,
+then break a block in Survival and confirm there is no drop. Creative
+pick-block must not supply an item. Compare a normal Crystal Block, and revisit
+the platform after restart. Operator fixtures
+`/rivencraft_port age create_platform <name> <seed>` and
+`/rivencraft_port age platform_probe <name>` validate a disposable Void
+platform's properties and saved blocks.
+The build and disposable dedicated-server checks passed for actual Void
+arrival generation, collision/opacity, strength, loot, pick-block exclusion,
+material-page exclusion, unload/reload and full restart. Shared model assets
+were verified in the JAR. The test server was stopped and its world removed;
+client appearance and Survival breaking remain the in-game check.
+
+### Configurable automatic Return Links
+
+The local `1.0.1.100-beta.1` slice ports the 1.21.1 automatic Return Link
+policy for successful handheld Descriptive Book arrivals. In
+`config/rivencraft-local.toml`, set `[descriptive_books] return_link_mode` to
+`DISABLED` (the default), `ON_CREATION`, or `ALWAYS`. ON_CREATION issues one
+Return Link when the Age is first reached with that mode enabled, shared
+across players in the world. ALWAYS issues one on each successful arrival.
+Disabled/Always arrivals do not consume the ON_CREATION marker, matching
+1.21.1. The marker persists across reload, reseeding and restart.
+
+Return Links retain the exact departure dimension, position, yaw and pitch.
+They use ordinary Linking Book rules and have no automatic Link Panel
+modifiers. They are issued after Disarm and dropped at the destination if
+inventory space is unavailable. Failed travel, binding a book, ordinary
+Linking Book travel and operator teleport probes do not issue Return Links.
+Stands/portals remain pending and will need the same successful-travel hook.
+
+For the in-game check, confirm the default gives no Return Link. Then enable
+ON_CREATION and visit a fresh Age twice: only the first arrival should grant
+one. Use that book to return and check position/facing; restart and revisit
+to confirm no duplicate. In ALWAYS, each arrival should grant a book. Test
+a Disarm Descriptive Book and a full inventory as well. Restore DISABLED
+after testing if automatic Return Links are unwanted.
+The build and disposable-server fixtures passed mode decisions, book target
+components, visit-record codec round trips, world persistence through
+unload/reload, reseeding and restart, and config loading with DISABLED and
+ON_CREATION. No player joined those fixtures; actual travel, Disarm and
+inventory-full delivery remain the in-game acceptance check. The server was
+stopped and its test world removed.
+
+### Handheld books left at departure
+
+The local `1.0.1.101-beta.1` slice ports the 1.21.1 dropped-book entity and
+handheld travel ownership. Successful handheld Linking and Descriptive Book
+travel removes the active book from its hand and leaves it at departure as
+an open-book entity. The existing Linking/Descriptive entity textures and
+skyward-facing model orientation are reused with 26.3's render-state API.
+The other hand and ordinary inventory remain unchanged unless Disarm applies.
+
+Failed travel restores the book. A rejected dropped-entity spawn also restores
+it instead of consuming it. Return Links are issued after the active book is
+left behind. Dropped books have a one-second pickup delay, no ordinary five-
+minute expiry, slow damage every 10,000 loaded ticks, and water/rain damage,
+matching 1.21.1. Book components and the decay counter persist with the entity.
+26.3 pickup particles use the extracted entity render state; 1.21.1's custom
+`ItemEntity.copy()` workaround is not needed on this target.
+
+Test travel from both hands with each book type, return to recover the open
+book, verify pages face upward, and check pickup animation and restart.
+Attempt a blocked/invalid link and confirm the book stays in hand. With
+Disarm, the active book should use its model while other items drop normally.
+With automatic Return Links enabled, the new Return Link should arrive with
+the player. Test rain/water damage with disposable books only.
+
+Build and disposable dedicated-server checks passed both hands, failed travel,
+exception recovery, cancelled entity spawning, successful hand removal, saved
+book components/lifetime, and a full restart with both book entities restored.
+The fixture uses a fake player and does not prove client rendering or actual
+cross-dimension travel. Entity loading is asynchronous: querying in the same
+command batch as chunk loading can briefly see zero books. The server was
+stopped and its world removed after validation. Operator fixtures are
+`age create_dropped_fixture <name> <seed>` and `age dropped_probe <name>`.
+
+### Notebook and Collation Folder
+
+The local `1.0.1.102-beta.1` slice adapts the 1.21.1 Notebook and Collation
+Folder, their server menu, persistent page component and existing page editor.
+Notebook capacity is 252 positions; Folder capacity is 27. Sparse positions,
+dark empty pages through the last occupied position, search, scrolling,
+single-page movement, shift transfers and the held-item lock are retained.
+Search consumes inventory keys while focused. Large pages keep the native
+30-by-40 atlas proportions and use the existing glyph-only item renderer.
+Unsupported symbol pages receive the port's red tint and retain their items.
+
+Both collections appear in Creative. Notebook crafting reuses the 1.21.1
+leather/string pattern. The Folder has no recipe in 1.21.1 and receives none
+here; discovery/library loot is still pending. Link Panels cannot be inserted
+through the collection menu. Unknown symbol pages remain stored and are
+counted in the tooltip. Writing Desk integration, sealed notebooks, Symbol
+Portfolios and bulk Binder interactions remain later work.
+
+Test both collection types and hands. Insert and remove pages by normal and
+shift clicks, place a page near the final position, move it with left/right
+arrows after selection, scroll/search, and type E in the search field. Verify
+Link Panels are rejected and the held collection cannot be moved/swapped.
+Close/reopen, put the collection in a chest, restart and recover its contents.
+Compare large glyphs and page outlines with the 1.21.1 editor.
+Build and disposable-server checks passed both hands and capacities, sparse
+positions, page movement, shift transfers through the actual menu input path,
+Link Panel/non-Page rejection, held-item pickup locking, save/network codec
+round trips, and all four collections stored in a chest across full restart.
+The recipe and adapted recipe-unlock advancement loaded successfully. Shared
+assets were checked in the JAR. No client joined these fixtures, so appearance,
+mouse handling and search keys still need the in-game check. The test server
+was stopped and every disposable test world removed.
+
+The local `1.0.1.103-beta.1` follow-up fixes the Notebook/Folder keyboard port:
+26.3 uses different key values from the old GLFW-based implementation. Escape
+now delegates to normal container closing even with search focused, while
+left/right page movement uses the current key helpers. Search still consumes
+ordinary inventory/hotbar keys. Check Escape with search focused and while
+holding a page on the cursor; closing should use normal carried-item recovery.
+
+### Collection imports in the Book Binder
+
+The local `1.0.1.104-beta.1` slice adapts 1.21.1's transactional collection
+import. Shift-click a Notebook or Collation Folder in the Binder inventory
+to append its pages. Carry one on the cursor and click the page strip to
+insert its pages before that position; clicking the panel position inserts
+at the beginning. Empty collection positions are skipped, preserving the
+relative order of occupied pages. Later Binder pages shift to make room.
+
+The import validates every page and total capacity before changing anything.
+A full Binder, invalid insertion point, empty collection, or conflicting
+Link Panel rejects the transaction without consuming pages. Successful
+imports leave the empty collection on the cursor or in its inventory slot,
+retaining its other components. Ordinary collection menus still reject Link
+Panels; the Binder retains 1.21.1's handling for explicitly supplied collection
+data containing a panel. Dedicated stored-collection input/UI remains unported.
+
+Test shift-click append and cursor insertion for both collection types, using
+distinct ordered pages and gaps. Check that the collection empties only after
+success and that rejected imports leave both sides unchanged. Bind a book
+with the imported pages, inspect its symbols, and restart with pages in the
+Binder and collections in a chest to check persistence.
+Build and disposable-server checks passed full-capacity and panel-conflict
+rejection, invalid positions, sparse cursor insertion, shift append, empty-cover
+retention, real Binder assembly and book page order. The empty collections and
+finished book survived full restart in a chest. No client joined this fixture;
+cursor/shift UI interaction remains the in-game check. The server was stopped
+and its world removed. Include collection imports in the future JEI guide port.
+
+### Symbol Portfolios and Sealed Notebooks
+
+The local `1.0.1.105-beta.1` slice ports the remaining collection items from
+1.21.1. The main Creative tab offers prefilled Symbol Portfolios for every
+symbol-page category, including registered biome/material/fluid pages.
+Categories exceeding 252 pages split into named volumes without truncation.
+Portfolios use the Notebook editor and Binder collection import and can be
+emptied/refilled like ordinary collections. No portfolio recipe is added.
+
+A Sealed Notebook opens server-side into a Collation Folder with 16 random
+pages. As in 1.21.1, the candidate pool excludes IDs under `block/` and
+`biome/` and the corrupted category; repeated draws are allowed. This also
+excludes biome-controller IDs under `biome/`, matching the existing code.
+The pool is not restricted to already-ported effects, so unsupported pages
+retain their red tint. Survival consumes one sealed item; Creative retains
+it. The last item becomes the Folder in hand, otherwise the Folder goes into
+inventory or drops if there is no space. Sealed Notebooks appear in Creative;
+their discovery/library loot remains pending, and no crafting recipe is added.
+
+Test portfolio names, volumes, contents, editor and Binder import. Open sealed
+stacks from both hands in Survival, including with full inventory, and confirm
+each Folder has 16 pages. Check Creative retains the sealed item. Put the
+resulting items in a chest, restart and revisit.
+Build and disposable-server checks passed the 252/253-page boundary, complete
+base-registry category coverage/order, seeded draws and exclusions, both-hand
+opening, Survival/Creative consumption, full-inventory delivery, and portfolio/
+Folder persistence in a chest across restart. Shared models/textures were
+verified in the JAR. The server was stopped and its world removed. No client
+joined those fixtures; Creative presentation, editor and Binder interaction
+remain the in-game check. Future JEI collection guides should cover these items.
+
+### Writing Desk
+
+The local `1.0.1.106-beta.1` slice adapts the 1.21.1 Writing Desk, its
+two-block model, inventory, server catalog and existing GUI. It reuses the
+Legacy desk/scrollbar/page atlases and current block textures. Selected pages
+and white paper stacks render on the desk using the existing offsets.
+
+There are 88 collection tabs, cycled four at a time. Each holds a loose Page
+or a collection with its normal capacity. Search, AZ sorting, ALL view,
+category filtering, page selection, movement and extraction retain the
+1.21.1 menu rules. Link Panels cannot be stored or copied, and no Link Panel
+creation recipe is added to the desk. Unknown pages remain recoverable but
+cannot be copied while unresolved. Unsupported port effects remain red.
+
+Supply paper and Ink Vials, select a known symbol, then take its virtual output
+to copy it. Previewing consumes nothing; taking a copy consumes one paper and
+one ink by default. `[writing] symbol_ink_cost` in `rivencraft-local.toml`
+retains the 1.21.1 configurable cost. Vials fill a 16-unit meter and return
+vanilla glass bottles. Refilling is event-driven and requires bottle space;
+there is no refill server ticker. Originals remain in their collection.
+
+The desk recipe and its recipe-unlock advancement are adapted to 26.3.
+New Minecraft handles Container drops during block-entity removal, so the
+old onRemove drop call is replaced by partner cleanup without duplicate
+inventory drops. The GUI uses current input helpers, including Escape while
+search is focused. The same mouse-button correction fixes Notebook right-click
+and scrollbar dragging. Progression awards and JEI guides remain later work.
+
+Test placement/orientation and opening from both halves, paper/selected-page
+rendering and neighboring block visibility. Check the atlas layout and tab
+numerals, cycling 0–87, searching/sorting/ALL, page dragging into inventory,
+and copying with paper/ink. Confirm costs occur only on pickup, bottles block
+refill when full, and removing bottle space allows refill. Restart with loaded
+collections and a selected page. Break either half and check drops once.
+
+Build and disposable-server checks passed copy preview/pickup costs,
+inventory-full rejection, Link Panel rejection, sparse page movement/extraction,
+88-tab reachability, all four facings and both halves' removal/drop counts.
+Collections, active tab, ink, paper and display page survived full restart.
+Recipe/advancement data loaded; shared models and atlases were verified in
+the JAR. No client joined these fixtures: visuals, mouse and live catalog
+updates remain the in-game check. The server was stopped and world removed.
+
 From the repository root:
 
 ```sh