Match Legacy handheld book drops with model entity (#85 )

Adopt NeoForge 21.1.264 after compatibility testing
Default automatic Return Links to disabled and review compatibility
2026-10-19 16:41:07 -04:00 · 2026-10-19 05:37:46 -04:00 · 2026-10-19 05:21:00 -04:00 · 2026-10-19 04:57:15 -04:00 · 2026-10-19 04:32:35 -04:00 · 2026-10-19 04:01:03 -04:00
82 changed files with 2946 additions and 201 deletions
@@ -105,6 +105,20 @@ JEI is optional; vanilla crafting
 recipes and all writing interactions work without it. For a development client
 with JEI, run `./gradlew runClient -PwithJei=true`.

+Four Crystal Shards craft one Crystal Block; eight Crystal Blocks around an
+empty crafting-grid center make one Book Receptacle. Picking up a shard unlocks
+the block recipe, and picking up a block unlocks the Receptacle recipe. The
+existing Ink Vial recipe uses two black dyes, a glass bottle, and a water
+bucket; the empty bucket stays in the crafting grid. These JSON recipes appear
+in JEI when it is installed and can be replaced by a data pack at
+`data/rivencraft/recipe/<recipe_name>.json`. To test a replacement, use a fresh
+world or `/reload`, then check the result in a crafting table and vanilla
+Crafter. A vanilla Lectern converts to a Rivencraft Book Stand when a Rivencraft
+book or page is placed on it; this in-world interaction has no JEI guide.
+With Create installed, Crystal Blocks and Book Receptacles have an optional Ponder scene
+showing crystal-frame construction, book activation, and a parrot crossing the portal. Use the Ponder shortcut
+while hovering either item; Rivencraft does not require Create to run.
+
 Craft a Book Binder from three iron ingots and five planks. Put leather or an
 empty Notebook in the left cover slot. Enter a title, then place a Link Panel
 Page first in the horizontal page strip. Click a page in the strip with a
@@ -184,7 +198,7 @@ Linking creates a bound Return Link to the exact source position and orientation
 according to the configured Return Link policy.

 Server owners can set `descriptive_books.return_link_mode` in Rivencraft's
-server config to `ON_CREATION` (default), `ALWAYS`, or `DISABLED`.
+server config to `DISABLED` (default), `ON_CREATION`, or `ALWAYS`.
 Age creation, persistence, lifecycle commands, configuration, backups, and
 administrator recovery are documented in [docs/AGES.md](docs/AGES.md).
 Data-pack runtime profiles are documented in
@@ -194,7 +208,7 @@ Data-pack runtime profiles are documented in

 - A Java 21 JDK
 - Minecraft 1.21.1
- NeoForge 21.1.251 or newer in the 21.1 line
+- NeoForge 21.1.264 or newer in the 21.1 line
 - Dynamic Dimensions AR Edition 0.9.1 and Bad Packets 0.8.2 (client and server)

 Create is optional. When installed, Rivencraft uses its Ponder renderer for
@@ -132,6 +132,8 @@ neoForge {

        server {
            server()
+            // Keep dedicated compatibility runs away from the normal dev world.
+            gameDirectory = project.file(project.findProperty('serverRunDir') ?: 'run')
            programArgument '--nogui'
            systemProperty 'neoforge.enabledGameTestNamespaces', project.mod_id
        }
@@ -69,10 +69,9 @@ definition.
 Rivencraft writes gameplay settings to the world/server configuration managed
 by NeoForge. `descriptive_books.return_link_mode` accepts:

- `ON_CREATION` (default): create one Return Link the first time a player
-  enters each Age.
+- `DISABLED` (default): never create Return Links automatically.
+- `ON_CREATION`: create one Return Link the first time a player enters each Age.
 - `ALWAYS`: create a Return Link after every successful Descriptive Book trip.
- `DISABLED`: never create Return Links automatically.

 Each client has a separate `rivencraft-client.toml`. Its `book_preview.mode`
 setting accepts `AUTO`, `IMMERSIVE_PORTALS`, `PONDER`, or `LEGACY`. This changes
@@ -1,7 +1,7 @@
-# Age arrival cloud platform
+# Age arrival platform

-Newly created Ages now place a 5×5 solid cloud platform instead of cobblestone at their saved spawn. The block has full collision, passes skylight, renders translucently, has no loot table, and cannot be obtained with pick-block. Existing Ages retain their already-placed platform; this change does not overwrite a player's saved world.
+Newly created Ages place a 5×5 solid platform instead of cobblestone at their saved spawn. The block has full collision, renders as an opaque full block, breaks as easily as glass (0.3 hardness), has no loot table, and cannot be obtained with pick-block. Existing Ages retain their already-placed platform blocks, which adopt the new appearance and hardness without altering saved terrain.

-The block texture is `assets/rivencraft/textures/block/cloud_platform.png`, verified at exactly 16×16 RGBA. Legacy's supplied assets contain no cloud-block texture, so this one was generated with the built-in image tool, then reduced by nearest-neighbor sampling. The final prompt requested a seamless Minecraft block-face pixel-art tile with 2–3 chunky white, icy-blue, and powder-blue cloud swirls, genuine transparent holes between them, strong 16×16-scale contrast, and no background or text.
+The model reuses `assets/rivencraft/textures/block/crystal_block.png`, the 16×16 Legacy crystal tile. The former generated cloud texture is removed. The internal block ID remains `rivencraft:cloud_platform` to preserve saved worlds.

 The separate [decay provider](INSTABILITY_DECAY.md) protects the saved spawn area by position, so its protection remains in force regardless of the platform's material.
@@ -19,12 +19,12 @@ project's GNU LGPL v3 license. Rivencraft itself uses the same license.
 | `assets/rivencraft/textures/block/book_binder_press.png` | `assets/mystcraft/textures/entity/bookbinder/press_part.png` | `9bc8ddc061845df0cd5ea47f4fdef773cff786ae` | Namespace/path rename only; Book Binder model uses this press texture |
 | `assets/rivencraft/textures/gui/book_binder_legacy.png` | `assets/mystcraft/gui/pagebinder.png` | `9bc8ddc061845df0cd5ea47f4fdef773cff786ae` | Namespace/path rename only; Book Binder GUI uses the original 176×181 panel |
 | `assets/rivencraft/textures/gui/ink_mixer_legacy.png` | `assets/mystcraft/gui/inkmixer.png` | `9bc8ddc061845df0cd5ea47f4fdef773cff786ae` | Namespace/path rename only; Ink Mixer GUI uses the original 176×181 panel |
-| `assets/rivencraft/textures/block/ink_mixer_top.png`, `ink_mixer_side.png`, `ink_mixer_bottom.png` | `assets/mystcraft/textures/blocks/inkmixer_top.png`, `inkmixer_side.png`, `inkmixer_bottom.png` | `9bc8ddc061845df0cd5ea47f4fdef773cff786ae` | Namespace/path rename only; Rivencraft supplies its own block model |
+| `assets/rivencraft/textures/block/inkwell_base.png`, `inkwell_cup.png`, `ink.png`, `ink_glass.png` | `assets/mystcraft/textures/entity/inkwell/` counterparts | Legacy 0.13.7.06 local extraction | Byte-identical copies used by the ported Ink Mixer geometry; the paper overlay uses vanilla white concrete instead of Legacy's black surface |
 | `assets/rivencraft/textures/item/linking_book_unwritten.png` | `assets/mystcraft/textures/items/unlinked.png` | `9bc8ddc061845df0cd5ea47f4fdef773cff786ae` | Namespace/path rename only |
 | `assets/rivencraft/textures/item/page_link_panel.png` | `page_background.png` and `PageBuilder.BasicPageSprite` | `9bc8ddc061845df0cd5ea47f4fdef773cff786ae` | Reproduces the legacy 160 px scale, black panel at `(25,30)`–`(135,75)`, and 128 px resample |
 | `assets/rivencraft/textures/gui/symbolcomponents.png` | `assets/mystcraft/textures/symbolcomponents.png` | `9bc8ddc061845df0cd5ea47f4fdef773cff786ae` | Byte-identical shared 512×512 component sheet for client-side page composition |
 | Runtime-composed symbol pages (`SymbolPageTextures`) | `page_background.png`, `textures/symbolcomponents.png`, `WordData`, `ModSymbols`, and `PageBuilder.PageSprite` | `9bc8ddc061845df0cd5ea47f4fdef773cff786ae` | Replaces the six pre-generated symbol PNGs; layers four poem words on the shared page background and caches bounded client textures |
-| `assets/rivencraft/textures/block/crystal_block.png` | `assets/mystcraft/textures/blocks/crystal.png` | Legacy 0.13.7.06 local extraction | Exact 16×16 blue tile shared by Crystal Block and Budding Crystal models after removing a byte-identical duplicate |
+| `assets/rivencraft/textures/block/crystal_block.png` | `assets/mystcraft/textures/blocks/crystal.png` | Legacy 0.13.7.06 local extraction | Exact 16×16 blue tile shared by Crystal Block, Budding Crystal, and the non-dropping Age arrival platform; its former cloud sprite is removed |
 | `assets/rivencraft/textures/block/{small,medium,large}_crystal_bud.png`, `crystal_cluster.png` | Minecraft 1.21.1 `textures/block/{small,medium,large}_amethyst_bud.png`, `amethyst_cluster.png` | Minecraft 1.21.1 | Original 16×16 alpha masks and silhouettes preserved; hue shifted toward Legacy blue, with brighter saturation; exported as 8-bit RGBA (not indexed PNG) |
 | `assets/rivencraft/textures/item/crystal_shard.png` | Original sprite generated with OpenAI ImageGen from the Legacy crystal palette | 2026-10-05 | Cropped and nearest-neighbor scaled to 16×16 |
 | `assets/rivencraft/sounds/linking/link-fissure.ogg` | `assets/mystcraft/sounds/linking/link-fissure.ogg` | Legacy 0.13.7.06 local extraction | Namespace/path rename only; plays when a Star Fissure returns an entity home |
@@ -32,6 +32,8 @@ project's GNU LGPL v3 license. Rivencraft itself uses the same license.
 | `assets/rivencraft/textures/block/book_receptacle.png` | `assets/mystcraft/textures/blocks/book_receptacle.png` | Legacy 0.13.7.06 local extraction | Byte-identical 16×16 face tile; modern block model recreates the Legacy thin slab |
 | `assets/rivencraft/textures/block/crystal_portal.png` and `.mcmeta` | `assets/mystcraft/textures/blocks/portal.png` and `.mcmeta` | Legacy 0.13.7.06 local extraction | Byte-identical texture and line-ending-normalized animation metadata, used when Immersive Portals is absent |
 | `assets/rivencraft/sounds/linking/link-portal.ogg` | `assets/mystcraft/sounds/linking/link-portal.ogg` | Legacy 0.13.7.06 local extraction | Byte-identical portal-link sound |
+| `assets/rivencraft/sounds/linking/link-disarm.ogg` | `assets/mystcraft/sounds/linking/link-disarm.ogg` | Legacy 0.13.7.06 local extraction | Byte-identical disarm-link sound; takes precedence over the portal sound as in Legacy |
+| `assets/rivencraft/sounds/linking/link-intra.ogg` | `assets/mystcraft/sounds/linking/link-intra.ogg` | Legacy 0.13.7.06 local extraction | Byte-identical intra-link sound for Linking Books |

 Mystcraft Legacy identifies XCompWiz as its project developer and includes the
 full LGPL v3 text in its root `LICENSE` file. Rivencraft's root `LICENSE`
@@ -15,9 +15,13 @@ Rivencraft has books, Ages, symbol writing, book stands, a desk, binder, Ink Mix

 ## Crystal portals: targets for #77–#78

-Issue #77 now has a craftable Book Receptacle (eight Crystal Blocks around an empty center), a bounded loaded-chunk crystal-network validator, persistent book holder/source pointers, animated Legacy portal cells, and portal collision routed through the existing Linking/Descriptive Book travel services. A book is only taken after a nonempty frame plan and destination dimension are validated. Removing the book or breaking its support removes the portal; a periodic server repair pass checks the loaded frame after restarts or edits. The Descriptive Book path preserves the configured automatic Return Link policy and link modifiers. Crystal-portal arrival does not generate a landing platform, matching Legacy's external travel semantics. A normal Linking Book still needs Intra Linking for same-dimension travel.
+Issue #77 now has a craftable Book Receptacle (eight Crystal Blocks around an empty center), a bounded loaded-chunk crystal-network validator, persistent book holder/source pointers, animated Legacy portal cells, and portal collision routed through the existing Linking/Descriptive Book travel services. A book is only taken after a nonempty frame plan and destination dimension are validated. Removing the book or breaking its support removes the portal; portal cells validate on neighboring block changes, like vanilla portals, rather than self-destructing on recurring ticks during chunk loading. The Descriptive Book path preserves the configured automatic Return Link policy and link modifiers. Crystal-portal arrival does not generate a landing platform, matching Legacy's external travel semantics. A normal Linking Book still needs Intra Linking for same-dimension travel.

-When Immersive Portals is present, render-only, non-teleporting IP portal entities show the book's destination through both faces of each coplanar opening; individual crystal cells are combined into one shaped surface so the destination is not repeated tile by tile. The view's central camera is aligned to the same safe arrival position and yaw/pitch used by book travel (at standing eye height). Perspective still changes naturally as the observer moves in front of a live portal. Each live view is recessed inside the opening; the fallback portal texture is always hidden while IP is installed, and crystal blocks render after the IP view so the frame appears on top. Without IP, the animated Legacy portal texture remains visible. Rivencraft portal-block contact remains the travel authority. This is an optional compile-only integration. The first placement of a Descriptive Book can generate/load its Age to establish a view destination. If the optional view is absent after restart, the holder's periodic pass recreates it. #78 retains exhaustive multiplayer, protection, destination deletion, and chunk-ticket hardening.
+When Immersive Portals is present, render-only, non-teleporting IP portal entities show the book's destination through both faces of each coplanar opening; individual crystal cells are combined into one shaped surface so the destination is not repeated tile by tile. The view's central camera is aligned to the same safe arrival position and yaw/pitch used by book travel (at standing eye height). Perspective still changes naturally as the observer moves in front of a live portal. Each live view is recessed inside the opening; the animated fallback texture stays visible until the live view is established, and crystal blocks render after the IP view so the frame appears on top. Without IP, the animated Legacy portal texture remains visible. Rivencraft portal-block contact remains the travel authority. This is an optional compile-only integration. The first placement of a Descriptive Book can generate/load its Age to establish a view destination. If the optional view is absent after restart, the holder's maintenance pass recreates it. Portal contact uses IP's instant transfer only if the destination's 3×3 chunk area was already loaded; otherwise it uses vanilla Minecraft's dimension transfer.
+
+Issue #78 hardening: placing each new portal cell fires a NeoForge entity-place protection event attributed to the player who inserted the book. If any cell is rejected, portal placement rolls back and the book remains with the player. Cells are placed without intermediate neighbor notifications so the frame validator cannot remove the first cells before the whole opening exists. Unattended maintenance never generates missing cells or tears down a saved portal during restart: block-change validation handles local frame damage, while the book remains retrievable. Portal owner positions are NBT integer arrays (not compound tags); the reader now matches that format, live-view state changes preserve the block entity's owner, and an intact saved surface with ownerless cells can recover its pointers from the adjacent book receptacle without placing new blocks. A missing neighboring chunk is treated as unknown, not as a broken frame. Portal cooldowns are per-player and session-only, never saved against a server tick counter that resets on restart. A Descriptive Book portal now searches for existing safe footing without creating a platform; Linking Books retain their intentionally floor-optional destination rule. Missing destination dimensions keep the book retrievable and remove any stale Immersive Portals view. Portal blocks and crystal frames are explicitly decay-protected. Book-GUI preview chunk loaders close on GUI exit, travel, logout, and server stop, with a five-minute fail-safe if a release packet is lost; crystal portals themselves add no Rivencraft chunk tickets.
+
+Manual #78 matrix (use two players where noted): restart with an active portal and confirm the book, surface, and destination view return once its chunk loads; walk through it immediately and after 10 seconds without reinserting the book. Then unload/reload the Age and repeat. With destination chunks loaded, contact should transfer instantly; with them unloaded, it should use Minecraft's normal dimension transfer while the animated fallback remains visible until the live view is ready. Have both players enter the same portal, return through separately bound books, and confirm each cooldown is independent and neither loops immediately. Test a Descriptive Book destination with unsafe feet/head space and with no existing footing: it must choose another footed spot or refuse travel, never generate a platform. Deny a portal cell with a block-protection mod and confirm activation consumes no book and leaves no partial surface. Break one cell and confirm it does not silently reappear. Remove or unload the destination dimension and confirm no crash or stale live view, while the book can still be retrieved. Open a book preview with Immersive Portals, close it, and confirm its temporary chunk loader is released; an abandoned preview should expire within five minutes. Repeat with Immersive Portals absent to confirm the fallback texture and book travel.

 Manual #77 check: build a 3×3 vertical Crystal Block ring, put the Receptacle on one frame crystal's outward face, then insert a bound Linking Book. The center should animate and link on contact; the book stays in the Receptacle. Confirm unbound books and incomplete frames do not consume items; empty-hand right-click retrieves the book and clears the surface. Repeat with a Descriptive Book and with Immersive Portals installed: the latter should show the destination live. Restart with the portal active and confirm the surface/view returns; break the support crystal and confirm book/portal cleanup.

@@ -42,13 +46,13 @@ For a manual check, create a fresh surface Age and run `/rivencraft library near

 Issue #75's comment calls this a despawning drop. The code differs subtly: [`EntityLinkbook`](https://github.com/Mystcraft/Mystcraft-Legacy/blob/9bc8ddc061845df0cd5ea47f4fdef773cff786ae/src/main/java/com/xcompwiz/mystcraft/entity/EntityLinkbook.java#L190-L224) explicitly cannot despawn, but takes one starvation damage every 10,000 ticks and damage while wet. It can eventually be destroyed if left unattended; a vanilla item entity's fixed five-minute timeout is not parity. A modern equivalent should retain the visible book and avoid silently deleting its Age identity at that timeout.

-Legacy's travel path creates no automatic Return Link. Rivencraft currently defaults to `ON_CREATION` via `DescriptiveBookItem` and `descriptive_books.return_link_mode`. Per #75's comment, change the **new-config default** to `DISABLED` while retaining `ON_CREATION` and `ALWAYS` as opt-ins. Existing saved server configs must keep their explicit value. Handheld-book drop and Return Link default are tracked in [#85](https://truenas-scale.tail180fb1.ts.net:8443/dnorberg/rivencraft/issues/85), not portal-frame logic.
+Legacy's travel path creates no automatic Return Link. Rivencraft now defaults to `DISABLED` in new server configs while retaining `ON_CREATION` and `ALWAYS` as opt-ins. Existing saved server configs keep their explicit value. Issue #85 adds the active-book drop only to hand-held Linking and Descriptive Book travel. On a successful link, the exact active stack becomes a dedicated `DroppedBookEntity` at the departure point, rendered with the same open `BookModel` and textures as the book stand; a rejected link restores it to the original hand. Stand and portal use leave their books in place. The entity has unlimited vanilla lifetime and loses one of its five item-health points every 10,000 loaded ticks, plus one per wet tick, matching Legacy's slow/wet decay. Unlike Legacy's custom entity, the modern book is picked up by ordinary contact, not sneaking with an empty hand, and remains subject to ordinary item hazards. Following is not yet a Rivencraft modifier, so no Following exception is exposed or silently simulated. Both hands can activate a book, whereas Legacy's explicit stack removal tested only its selected main-hand slot.

 ## Crafting, sounds, and progression

 | Area | Legacy evidence and modern boundary |
 | --- | --- |
-| Crafting | [Legacy recipes](https://github.com/Mystcraft/Mystcraft-Legacy/tree/9bc8ddc061845df0cd5ea47f4fdef773cff786ae/src/main/resources/assets/mystcraft/recipes) specify the Receptacle, Binder, Mixer, Folder, Desk, and other writing blocks. [`RecipeLinkingbook`](https://github.com/Mystcraft/Mystcraft-Legacy/blob/9bc8ddc061845df0cd5ea47f4fdef773cff786ae/src/main/java/com/xcompwiz/mystcraft/data/RecipeLinkingbook.java#L28-L60) combines one Link Panel and leather anywhere in the grid. Rivencraft already has Binder, Mixer, Ink Vial, Notebook, Desk, Crystal Block, and Linking Book recipes. #79 adds only missing recipes/processes; preserve vanilla-Lectern conversion, noncraftable Blank Pages, and optional JEI. |
+| Crafting | [Legacy recipes](https://github.com/Mystcraft/Mystcraft-Legacy/tree/9bc8ddc061845df0cd5ea47f4fdef773cff786ae/src/main/resources/assets/mystcraft/recipes) specify the Receptacle, Binder, Mixer, Folder, Desk, and other writing blocks. [`RecipeLinkingbook`](https://github.com/Mystcraft/Mystcraft-Legacy/blob/9bc8ddc061845df0cd5ea47f4fdef773cff786ae/src/main/java/com/xcompwiz/mystcraft/data/RecipeLinkingbook.java#L28-L60) combines one Link Panel and leather anywhere in the grid. Rivencraft has Binder, Mixer, Ink Vial, Notebook, Desk, Crystal Block, Linking Book, and Receptacle recipes. #79 keeps these data-driven and adds recipe-book unlocks for Crystal Block, Receptacle, and Ink Vial. The Legacy potion-based ink variant is omitted: in 1.21.1 a simple potion ingredient does not return its glass bottle, while the existing water-bucket recipe returns its bucket. The Legacy Folder/Portfolio use Rivencraft's Notebook; the old two-part Desk is one item; the old Lectern/Book Stand recipes use a vanilla Lectern converted in-world by adding a Rivencraft book or page. Blank Pages remain noncraftable and Link Panels remain outside the Desk. JEI automatically displays the JSON crafting recipes; its existing optional categories cover Mixer, Desk, and Binder processes. The lectern interaction intentionally has no JEI guide. With Create installed, an optional Ponder scene attached to the Receptacle item demonstrates frame construction and book insertion; the core mod still runs without Create. |
 | Sounds | [`Sounds`](https://github.com/Mystcraft/Mystcraft-Legacy/blob/9bc8ddc061845df0cd5ea47f4fdef773cff786ae/src/main/java/com/xcompwiz/mystcraft/data/Sounds.java#L8-L26) registers pop, link, disarm, following, intra-link, fissure-link, portal-link, and meteor roar. The matching OGGs are in the local extraction. Rivencraft already carries link, fissure-link, and meteor roar. #80 should reuse and credit available Legacy files before creating alternatives. |
 | Advancements | [Legacy advancement JSONs](https://github.com/Mystcraft/Mystcraft-Legacy/tree/9bc8ddc061845df0cd5ea47f4fdef773cff786ae/src/main/resources/assets/mystcraft/advancements) have inventory milestones for a symbol page, unlinked Linking Book, and Age Book; a Writing Desk trigger; a safe Age-travel trigger; and a hidden Quinn trigger. #81 should use modern server-owned criteria. Quinn has no established Rivencraft equivalent and should be documented or deliberately omitted, not awarded on preview. |

@@ -0,0 +1,40 @@
+# Milestone 7 advancements and discovery (#81)
+
+Rivencraft's advancement tab follows the visible progression in Mystcraft
+Legacy's `assets/mystcraft/advancements/`: Page, unwritten Linking Book,
+Writing Desk writing, Age Book, and safe Age travel. Titles such as *The Ending
+Has Not Yet Been Written*, *D'ni Ink*, and *The Art of Writing* reference Myst
+without requiring any assets from that game. The Legacy hidden Quinn trigger
+has no established Rivencraft action and is deliberately omitted.
+
+`root`, `page`, and `linking_book` use vanilla server-side tick/inventory
+criteria. `link_panel`, `copy_page`, `bind_age`, `open_portal`, and `enter_age`
+use an impossible criterion awarded only after the server commits the
+corresponding action. The Age-travel award requires a successful book or portal
+link ending in a registered Rivencraft Age. Opening a book GUI, rendering a
+destination preview, viewing a recipe, or merely loading an Age cannot award
+it. Progress is stored by Minecraft per player and survives world restarts.
+
+Vanilla recipe-book unlock advancements now cover the Writing Desk, Ink Mixer,
+Book Binder, and Notebook, in addition to the existing Ink Vial, Crystal
+Block, and Book Receptacle unlocks. The component-sensitive Linking Book
+crafting recipe remains a special recipe: its Link Panel requirement and the
+Writing Desk/Ink Mixer/Book Binder processes are explained by Rivencraft's
+optional JEI integration. No recipe or advancement requires JEI, Create, or
+Immersive Portals to be installed.
+
+Manual Survival check: collect a Page and Linking Book; use the Ink Mixer to
+take a Link Panel; copy a Page at the Writing Desk; bind a Descriptive Book;
+enter its Age; activate a Crystal Portal. Confirm each advancement appears
+only after the completed action, not from an output preview or GUI opening.
+Repeat the actions with two players to confirm only the actor receives each
+award. Restart an existing save and confirm completed progress remains, then
+complete one previously unearned milestone. With JEI absent, the vanilla
+recipe book should still reveal standard crafting recipes as their ingredients
+are discovered; with JEI installed, the special writing guides should appear.
+
+The automated Book Binder output-award scenario stalls in the GameTest storage
+runner, so it is intentionally omitted under the project test policy. For its
+manual check, open a ready Binder, observe that merely previewing the finished
+book does not award *A Book of Ages*, then take the book and confirm the award.
+Repeat by shift-clicking the result in a fresh Binder.
@@ -0,0 +1,53 @@
+# Milestone 7 compatibility review (#82)
+
+Reviewed 2026-10-19 for Minecraft 1.21.1. The project now compiles against
+NeoForge 21.1.264 and advertises that as its minimum. The official
+[NeoForge Maven metadata](https://maven.neoforged.net/releases/net/neoforged/neoforge/maven-metadata.xml)
+lists 21.1.264 as the newest 21.1 release. Its
+[changelog](https://maven.neoforged.net/releases/net/neoforged/neoforge/21.1.264/neoforge-21.1.264-changelog.txt)
+includes received split-packet size checks (21.1.260), network setup payload
+direction/decoding limits (21.1.261), ad-hoc channel identifier limits
+(21.1.262), and an initial attachment-sync fix (21.1.264). Those are concrete
+reasons to evaluate an upgrade, but do not by themselves prove Rivencraft and
+its optional integrations work on that loader.
+
+**Decision: adopt 21.1.264 beginning with 0.6.6.2.** An override build
+succeeded, but its GameTest server repeated its storage-progress display
+without producing test results. That run was stopped; it is neither a pass nor
+evidence of a NeoForge defect. The player subsequently passed an in-game
+singleplayer test on 21.1.264 with the optional stack, then passed a dedicated
+server test including Immersive Portals travel to a Rivencraft Age. The
+dedicated server also reached the ready state with only the required mods
+before the full optional stack was installed. Both modes used Rivencraft
+0.6.6.1. The earlier 21.1.251 baseline passed 70 required GameTests for
+release V0.6.6.0.
+
+| Dependency | Project baseline | Newest checked 1.21.1 release | Follow-up |
+| --- | --- | --- | --- |
+| Dynamic Dimensions AR Edition (required) | 0.9.1 | 0.9.1 | No newer release found on [CurseForge](https://www.curseforge.com/minecraft/mc-mods/dynamicdimension-ar-edition/files/all). |
+| Bad Packets (required) | neo-0.8.2 | neo-0.8.2 | No newer matching [Modrinth](https://modrinth.com/mod/badpackets/versions) release found. |
+| JEI (optional) | 19.57.0.449 | 19.64.0.455 | Separate update issue; verify recipe categories and GUI discovery. |
+| Create (optional) | 6.0.10 | 6.0.10 | No newer matching [Modrinth](https://modrinth.com/mod/create/versions) release found. Its jar bundles Ponder 1.0.82. |
+| Ponder (bundled with Create) | 1.0.82 | 1.0.87 library artifact | [Maven](https://maven.createmod.net/net/createmod/ponder/ponder-neoforge/maven-metadata.xml) has a newer artifact, but Create 6.0.10 still bundles 1.0.82. Do not treat this as a separately installed Create update. |
+| Immersive Portals (optional) | 6.0.7 | 6.0.7 | No newer matching [Modrinth](https://modrinth.com/mod/immersive-portals-neoforge/versions) release found. |
+| TerraBlender (optional) | 4.1.0.8 | 4.1.0.8 | No newer matching [Modrinth](https://modrinth.com/mod/terrablender/versions) release found. |
+| Serene Seasons (optional) | 10.1.0.8 compile target | 10.1.0.9 | Separate update issue; the user's Prism instance already contains 10.1.0.9, but that is not a recorded compatibility pass. |
+| GlitchCore (Serene dependency) | 2.1.0.2 | 2.1.0.2 | No newer matching [Modrinth](https://modrinth.com/mod/glitchcore/versions) release found. |
+| Biomes O' Plenty (TerraBlender test addon) | 21.1.0.14 in user's Prism instance | 21.1.0.14 | No newer matching [Modrinth](https://modrinth.com/mod/biomes-o-plenty/versions) release found. |
+
+The Modrinth version comparisons above were filtered to **NeoForge and
+Minecraft 1.21.1** on 2026-10-19. Create's bundled Ponder version was read
+from `META-INF/jarjar/metadata.json` in `create-1.21.1-6.0.10.jar`; the
+separate library-artifact comparison came from Create's Maven. Dynamic
+Dimensions was checked on CurseForge. Versions for other Minecraft lines and
+similarly named mods were excluded.
+
+The full dedicated test stack contained Create/Ponder, Immersive Portals, JEI,
+TerraBlender with Biomes O' Plenty, and Serene Seasons with GlitchCore. The
+server loaded a new `rivencraft:age/test`, and its shutdown log confirms that
+all Overworld, Nether, End, and Age chunks were saved. The player explicitly
+approved 21.1.264 after that test. This does not independently certify every
+optional combination, the LEGACY preview fallback on a client without Create
+and Immersive Portals, or a full restart/rejoin cycle; keep those in the
+regression checklist. Serene's GameTest mock-player network limitation still
+requires real-client checks for seasonal behavior.
@@ -0,0 +1,63 @@
+# Milestone 7 visual and audio polish (#80)
+
+The source is the local Mystcraft 0.13.7.06 extraction under
+`/home/dnorberg/Documents/mystcraft-src/mystcraft-1.12.2-0.13.7.06/`.
+Reused textures and OGG files are recorded in [asset provenance](ASSET_PROVENANCE.md).
+The `dev images/book binder.png` and `dev images/ink mixer.png` screenshots
+are the Legacy model references used for this slice.
+
+## Legacy comparison and modern boundary
+
+- The Crystal Block, Book Receptacle, and 16×512 portal animation already use
+  Legacy sprites. The Receptacle's 16×16×6 model already matches the Legacy
+  slab. The fallback portal now uses Legacy's four-pixel-deep, double-faced
+  `linkportal_ns.json` geometry, with the original animation; it declares a
+  translucent render layer and portal particle texture. The block remains
+  non-occluding. When Immersive Portals supplies a live view, the fallback
+  model is hidden, while the crystal frame is drawn over the view.
+- The Age arrival platform now reuses the same Legacy crystal tile as Crystal
+  Block. It is an opaque, occluding full block, while retaining its empty loot
+  table and unobtainable pick-block behavior. It has glass-like 0.3 hardness.
+  The old cloud sprite is unused and removed.
+- The Book Binder now includes the two inner braces and central press/book
+  piece omitted by the earlier model, using the existing byte-identical
+  Legacy textures. The Ink Mixer uses Legacy's `inkwell_model.json` geometry
+  and four original inkwell textures. A thin white paper surface replaces the
+  black paper appearance from the reference; the old simplified mixer tiles
+  are no longer used. The half-alpha glass atlas is intentionally rendered on
+  a cutout layer; its more opaque look passed the player's in-game check.
+- Legacy's link listener selects Disarm before a custom portal sound, then
+  Following, Intra Linking, and ordinary Link. Rivencraft has no Following
+  modifier yet, so it selects Disarm, portal, Intra Linking, or ordinary Link
+  in that order. The Disarm and Intra OGGs are byte-identical Legacy copies.
+- Legacy sends 50 small neutral link particles in roughly a one-by-two-block
+  region at both departure and arrival. Its fixed-function particle class is
+  not portable to 1.21.1. Rivencraft uses a one-shot burst of 50 vanilla Cloud
+  particles at both ends, emitted only after successful server-authoritative
+  travel. There is no continuous portal-particle loop in the inspected Legacy
+  `BlockLinkPortal` class, so the portal surface itself adds none.
+- The Legacy `textures/entity/linkbook.png` and `linking/pop.ogg` are inspected
+  but not copied in this slice. The custom dropped Linkbook entity is part of
+  #85; adding its assets before the entity exists would leave unused resources.
+  Library walls, shelves, chest, and webs use vanilla blocks in the template,
+  so there are no separate library art files to port.
+
+## Manual visual/audio check
+
+Use the same bound book in a held use and a Crystal Portal. Confirm the link
+particles and audio play at both ends, and the portal landing matches the book.
+Repeat with Disarm and Intra Linking panels to check the distinct sounds.
+Compare the fallback portal, crystal frame, and Receptacle with Immersive
+Portals absent; verify the animated surface is visible from both sides and
+does not expose caves or other geometry through solid blocks. With Immersive
+Portals installed, confirm the live view replaces only the fallback surface,
+the frame draws in front, and no fallback texture covers the live view.
+Create/Ponder is optional and must not affect either rendering path.
+Check a freshly generated arrival platform from above and below: the crystal
+tile should be opaque, break about as quickly as glass, and drop no block item.
+Compare the Book Binder press and Ink Mixer cup/glass against the `dev images`
+references; the mixer paper should appear white, and neither block should
+show missing-texture checkerboards or see-through-world artifacts.
+
+The player reported that the in-game visual and audio checks pass on 2026-10-19,
+including acceptance of the cutout glass appearance and current block sounds.
@@ -45,7 +45,7 @@ being captured in the preview.

 ## Supported combinations and upstream limits

-The compatibility baseline is Minecraft 1.21.1, NeoForge 21.1.251, Create
+The compatibility baseline is Minecraft 1.21.1, NeoForge 21.1.264, Create
 6.0.10, and Immersive Portals 6.0.7. Core Age generation and the `LEGACY`
 backend run without Create or Immersive Portals; the headless GameTest server
 uses that dependency-free path.
@@ -18,7 +18,7 @@ minecraft_version=1.21.1
 # as they do not follow standard versioning conventions.
 minecraft_version_range=[1.21.1]
 # The Neo version must agree with the Minecraft version to get a valid artifact
-neo_version=21.1.251
+neo_version=21.1.264
 ponder_version=1.0.82
 dynamic_dimensions_file_id=7707789
 badpackets_version=0.8.2
@@ -36,7 +36,7 @@ mod_name=Rivencraft
 # The license of the mod. Review your options at https://choosealicense.com/. All Rights Reserved is the default.
 mod_license=LGPL-3.0-or-later
 # The mod version. Rivencraft uses the x.y.z.b policy documented in README.md.
-mod_version=0.6.2.4
+mod_version=0.6.6.6
 immersive_portals_version=6.0.7
 terrablender_version=4.1.0.8
 serene_seasons_version_id=B6nTjh4b
@@ -54,6 +54,7 @@ public final class Rivencraft {
        ModBiomeSources.register(modEventBus);
        ModChunkGenerators.register(modEventBus);
        ModBlocks.register(modEventBus);
+        net.dnorberg.rivencraft.registry.ModEntities.register(modEventBus);
        ModBlockEntities.register(modEventBus);
        ModItems.register(modEventBus);
        ModMenus.register(modEventBus);
@@ -76,6 +77,7 @@ public final class Rivencraft {
        NeoForge.EVENT_BUS.addListener(AgeCelestialAngleSync::onPlayerLoggedIn);
        NeoForge.EVENT_BUS.addListener(AgeCelestialAngleSync::onPlayerChangedDimension);
        NeoForge.EVENT_BUS.addListener(AgeLifecycleEvents::onPlayerLoggedOut);
+        NeoForge.EVENT_BUS.addListener(AgeLifecycleEvents::onServerTickPost);
        NeoForge.EVENT_BUS.addListener(AgeLifecycleEvents::onServerStopping);
        NeoForge.EVENT_BUS.addListener(AgeInstabilityRuntime::onServerStopping);
        NeoForge.EVENT_BUS.addListener(AgeEnvironmentalProviders::onServerStopping);
@@ -0,0 +1,30 @@
+package net.dnorberg.rivencraft.advancement;
+
+import net.dnorberg.rivencraft.Rivencraft;
+import net.dnorberg.rivencraft.book.AgeRegistrySavedData;
+import net.minecraft.resources.ResourceLocation;
+import net.minecraft.server.level.ServerPlayer;
+
+/** Awards action-only progression after the server has committed the action. */
+public final class ProgressionAdvancements {
+    public static final String LINK_PANEL = "link_panel";
+    public static final String COPY_PAGE = "copy_page";
+    public static final String BIND_AGE = "bind_age";
+    public static final String OPEN_PORTAL = "open_portal";
+    public static final String ENTER_AGE = "enter_age";
+
+    private ProgressionAdvancements() {}
+
+    public static void award(ServerPlayer player, String path) {
+        var advancement = player.getServer().getAdvancements().get(
+                ResourceLocation.fromNamespaceAndPath(Rivencraft.MOD_ID, "progression/" + path));
+        if (advancement != null) player.getAdvancements().award(advancement, "completed");
+    }
+
+    public static void awardAgeTravel(ServerPlayer player) {
+        if (AgeRegistrySavedData.get(player.serverLevel()).findByDimension(
+                player.serverLevel().dimension().location()).isPresent()) {
+            award(player, ENTER_AGE);
+        }
+    }
+}
@@ -1,5 +1,6 @@
 package net.dnorberg.rivencraft.block;

+import net.dnorberg.rivencraft.advancement.ProgressionAdvancements;
 import com.mojang.serialization.MapCodec;
 import net.dnorberg.rivencraft.block.entity.BookReceptacleBlockEntity;
 import net.dnorberg.rivencraft.portal.CrystalPortalNetwork;
@@ -104,14 +105,21 @@ public final class BookReceptacleBlock extends BaseEntityBlock {
        }
        holder.setBook(stack.copyWithCount(1));
        holder.setDestination(destination);
-        if (!CrystalPortalNetwork.activate(server, pos, plan)) {
+        if (!CrystalPortalNetwork.activate(server, pos, plan, player)) {
            holder.takeBook();
            return ItemInteractionResult.FAIL;
        }
        if (!player.getAbilities().instabuild) stack.shrink(1);
-        if (net.neoforged.fml.ModList.get().isLoaded("immersive_portals_core"))
-            net.dnorberg.rivencraft.compat.ImmersivePortalsCrystalView.activate(server, pos, plan, destination);
+        if (net.neoforged.fml.ModList.get().isLoaded("immersive_portals_core")) {
+            net.dnorberg.rivencraft.compat.ImmersivePortalsCrystalView.activate(server, pos, plan, destination,
+                    holder.getBook().is(ModItems.DESCRIPTIVE_BOOK.get()));
+            CrystalPortalNetwork.setLiveView(server, plan,
+                    net.dnorberg.rivencraft.compat.ImmersivePortalsCrystalView.complete(
+                            server, pos, plan, destination));
+        }
        level.playSound(null, pos, SoundEvents.ENCHANTMENT_TABLE_USE, SoundSource.BLOCKS, 1, 1);
+        if (player instanceof ServerPlayer serverPlayer)
+            ProgressionAdvancements.award(serverPlayer, ProgressionAdvancements.OPEN_PORTAL);
        return ItemInteractionResult.SUCCESS;
    }

@@ -132,7 +140,8 @@ public final class BookReceptacleBlock extends BaseEntityBlock {
    @Override protected void neighborChanged(BlockState state, Level level, BlockPos pos, Block neighbor,
            BlockPos neighborPos, boolean moved) {
        super.neighborChanged(state, level, pos, neighbor, neighborPos, moved);
-        if (!level.isClientSide && !level.getBlockState(pos.relative(state.getValue(FACING).getOpposite()))
+        BlockPos support = pos.relative(state.getValue(FACING).getOpposite());
+        if (!level.isClientSide && level.hasChunkAt(support) && !level.getBlockState(support)
                .is(ModBlocks.CRYSTAL_BLOCK.get())) level.destroyBlock(pos, true);
    }

@@ -1,14 +1,12 @@
 package net.dnorberg.rivencraft.block;

 import net.minecraft.core.BlockPos;
-import net.minecraft.core.Direction;
 import net.minecraft.world.item.ItemStack;
-import net.minecraft.world.level.BlockGetter;
 import net.minecraft.world.level.LevelReader;
 import net.minecraft.world.level.block.Block;
 import net.minecraft.world.level.block.state.BlockState;

-/** Solid footing for Age arrivals, rendered as a translucent cloud. */
+/** Solid crystal-textured footing for Age arrivals that cannot be collected. */
 public final class CloudPlatformBlock extends Block {
    public CloudPlatformBlock(Properties properties) {
        super(properties);
@@ -18,19 +16,4 @@ public final class CloudPlatformBlock extends Block {
    public ItemStack getCloneItemStack(LevelReader level, BlockPos pos, BlockState state) {
        return ItemStack.EMPTY;
    }
-
-    @Override
-    protected boolean skipRendering(BlockState state, BlockState adjacent, Direction side) {
-        return adjacent.is(this) || super.skipRendering(state, adjacent, side);
-    }
-
-    @Override
-    protected boolean propagatesSkylightDown(BlockState state, BlockGetter level, BlockPos pos) {
-        return true;
-    }
-
-    @Override
-    protected int getLightBlock(BlockState state, BlockGetter level, BlockPos pos) {
-        return 0;
-    }
 }
@@ -3,14 +3,13 @@ package net.dnorberg.rivencraft.block;
 import com.mojang.serialization.MapCodec;
 import net.dnorberg.rivencraft.block.entity.BookReceptacleBlockEntity;
 import net.dnorberg.rivencraft.block.entity.CrystalPortalBlockEntity;
-import net.dnorberg.rivencraft.item.DescriptiveBookItem;
-import net.dnorberg.rivencraft.item.LinkingBookItem;
 import net.dnorberg.rivencraft.portal.CrystalPortalNetwork;
 import net.dnorberg.rivencraft.portal.PortalTravelCooldown;
+import net.dnorberg.rivencraft.portal.PortalTravelQueue;
 import net.dnorberg.rivencraft.registry.ModBlocks;
 import net.dnorberg.rivencraft.registry.ModItems;
 import net.minecraft.core.BlockPos;
-import net.minecraft.nbt.Tag;
+import net.minecraft.core.Direction;
 import net.minecraft.server.level.ServerLevel;
 import net.minecraft.server.level.ServerPlayer;
 import net.minecraft.util.RandomSource;
@@ -24,6 +23,7 @@ import net.minecraft.world.level.block.entity.BlockEntity;
 import net.minecraft.world.level.block.state.BlockState;
 import net.minecraft.world.level.block.state.StateDefinition;
 import net.minecraft.world.level.block.state.properties.BooleanProperty;
+import net.minecraft.world.level.block.state.properties.EnumProperty;
 import net.minecraft.world.level.material.Fluid;
 import net.neoforged.fml.ModList;

@@ -32,21 +32,20 @@ public final class CrystalPortalBlock extends BaseEntityBlock {
    public static final MapCodec<CrystalPortalBlock> CODEC = simpleCodec(CrystalPortalBlock::new);
    // Retained so portal blocks already saved with this state still deserialize.
    public static final BooleanProperty LIVE_VIEW = BooleanProperty.create("live_view");
-    private static final String COOLDOWN = "RivencraftCrystalPortalCooldown";
+    public static final EnumProperty<Direction.Axis> AXIS = EnumProperty.create("axis", Direction.Axis.class);

    public CrystalPortalBlock(Properties properties) {
        super(properties);
-        registerDefaultState(stateDefinition.any().setValue(LIVE_VIEW, false));
+        registerDefaultState(stateDefinition.any().setValue(LIVE_VIEW, false).setValue(AXIS, Direction.Axis.Z));
    }
    @Override protected MapCodec<? extends BaseEntityBlock> codec() { return CODEC; }
    @Override protected void createBlockStateDefinition(StateDefinition.Builder<Block, BlockState> builder) {
-        builder.add(LIVE_VIEW);
+        builder.add(LIVE_VIEW, AXIS);
    }
    @Override protected RenderShape getRenderShape(BlockState state) {
-        // The live-view flag can lag behind portal-entity creation or fail to
-        // synchronize for an existing frame. Never draw the fallback texture
-        // when Immersive Portals owns the view for this installation.
-        return ModList.get().isLoaded("immersive_portals_core")
+        // Keep the animated fallback until the optional destination view has
+        // actually been established, including after a world restart.
+        return ModList.get().isLoaded("immersive_portals_core") && state.getValue(LIVE_VIEW)
                ? RenderShape.INVISIBLE : RenderShape.MODEL;
    }
    @Override public BlockEntity newBlockEntity(BlockPos pos, BlockState state) {
@@ -57,35 +56,30 @@ public final class CrystalPortalBlock extends BaseEntityBlock {
    @Override protected void entityInside(BlockState state, Level level, BlockPos pos, Entity entity) {
        if (!(level instanceof ServerLevel server) || !(entity instanceof ServerPlayer player)) return;
        long now = server.getServer().getTickCount();
-        long previous = player.getPersistentData().contains(COOLDOWN, Tag.TAG_LONG)
-                ? player.getPersistentData().getLong(COOLDOWN) : -1;
-        if (previous > now) {
-            player.getPersistentData().remove(COOLDOWN);
-            previous = -1;
-        }
-        if (PortalTravelCooldown.blocked(now, previous)) return;
+        if (PortalTravelCooldown.blocked(player, now)) return;
        if (!(level.getBlockEntity(pos) instanceof CrystalPortalBlockEntity portal)
                || portal.receptacle() == null || !level.hasChunkAt(portal.receptacle())
                || !(level.getBlockEntity(portal.receptacle()) instanceof BookReceptacleBlockEntity holder)) return;
        ItemStack book = holder.getBook();
        if (book.isEmpty()) return;
-        player.getPersistentData().putLong(COOLDOWN, now);
-        if (book.is(ModItems.LINKING_BOOK.get())) LinkingBookItem.usePortalBook(player, book);
-        else if (book.is(ModItems.DESCRIPTIVE_BOOK.get())) DescriptiveBookItem.usePortalBook(player, book);
+        PortalTravelCooldown.mark(player, now);
+        PortalTravelQueue.enqueue(player, server, pos, portal.receptacle(), book, now);
    }

    @Override protected void neighborChanged(BlockState state, Level level, BlockPos pos, Block neighbor,
            BlockPos neighborPos, boolean moved) {
        super.neighborChanged(state, level, pos, neighbor, neighborPos, moved);
-        if (level instanceof ServerLevel server) server.scheduleTick(pos, this, 2);
+        if (!(level instanceof ServerLevel server)
+                || !(level.getBlockEntity(pos) instanceof CrystalPortalBlockEntity portal)
+                || portal.receptacle() == null) return;
+        // Like a vanilla portal, validate when the frame changes, not on a
+        // repeating timer that can race block entities loading after restart.
+        if (CrystalPortalNetwork.cellStatus(server, pos, portal.receptacle())
+                == CrystalPortalNetwork.CellStatus.INVALID) server.removeBlock(pos, false);
    }

    @Override protected void tick(BlockState state, ServerLevel level, BlockPos pos, RandomSource random) {
-        if (!(level.getBlockEntity(pos) instanceof CrystalPortalBlockEntity portal)
-                || portal.receptacle() == null || !CrystalPortalNetwork.validCell(level, pos, portal.receptacle())) {
-            level.removeBlock(pos, false);
-            return;
-        }
-        level.scheduleTick(pos, this, 100);
+        // Ignore validation ticks saved by older builds. Frame edits are
+        // handled by neighborChanged, and the receptacle maintains the view.
    }
 }
@@ -22,6 +22,7 @@ public final class BookReceptacleBlockEntity extends BlockEntity {
    private static final String DESTINATION_TAG = "Destination";
    private ItemStack book = ItemStack.EMPTY;
    private LinkTarget destination;
+    private boolean restoreView = true;

    public BookReceptacleBlockEntity(BlockPos pos, BlockState state) {
        super(ModBlockEntities.BOOK_RECEPTACLE.get(), pos, state);
@@ -62,6 +63,7 @@ public final class BookReceptacleBlockEntity extends BlockEntity {
                : ItemStack.EMPTY;
        destination = tag.contains(DESTINATION_TAG)
                ? LinkTarget.CODEC.parse(NbtOps.INSTANCE, tag.get(DESTINATION_TAG)).result().orElse(null) : null;
+        restoreView = true;
    }

    @Override
@@ -83,13 +85,38 @@ public final class BookReceptacleBlockEntity extends BlockEntity {
    public static void serverTick(net.minecraft.world.level.Level world, BlockPos pos, BlockState state,
                                  BookReceptacleBlockEntity holder) {
        if (!(world instanceof ServerLevel level)) return;
-        if (level.getGameTime() % 200 != 0 || holder.book.isEmpty()) return;
-        CrystalPortalNetwork.reconcile(level, pos);
-        if (holder.destination == null || !ModList.get().isLoaded("immersive_portals_core")) return;
-        if (!net.dnorberg.rivencraft.compat.ImmersivePortalsCrystalView.exists(level, pos)) {
-            CrystalPortalNetwork.Plan plan = CrystalPortalNetwork.plan(level, pos);
-            if (plan.valid()) net.dnorberg.rivencraft.compat.ImmersivePortalsCrystalView.activate(
-                    level, pos, plan, holder.destination);
+        if (holder.book.isEmpty() || (!holder.restoreView && level.getGameTime() % 200 != 0)) return;
+        // Startup maintenance must never turn a saved portal off while its
+        // chunks and block entities are still arriving. Structural edits are
+        // validated by the portal blocks' neighbor updates instead.
+        if (holder.restoreView) CrystalPortalNetwork.recoverSavedOwners(level, pos);
+        CrystalPortalNetwork.Plan plan = CrystalPortalNetwork.plan(level, pos);
+        if (!plan.valid()) return;
+        if (!ModList.get().isLoaded("immersive_portals_core")) {
+            holder.restoreView = false;
+            return;
        }
+        if (holder.restoreView) CrystalPortalNetwork.setLiveView(level, plan, false);
+        holder.restoreView = false;
+        if (holder.destination == null) {
+            net.dnorberg.rivencraft.compat.ImmersivePortalsCrystalView.remove(level, pos);
+            CrystalPortalNetwork.setLiveView(level, plan, false);
+            return;
+        }
+        if (level.getServer().getLevel(holder.destination.location().dimension()) == null) {
+            net.dnorberg.rivencraft.compat.ImmersivePortalsCrystalView.remove(level, pos);
+            CrystalPortalNetwork.setLiveView(level, plan, false);
+            return;
+        }
+        if (!net.dnorberg.rivencraft.compat.ImmersivePortalsCrystalView.complete(
+                level, pos, plan, holder.destination)) {
+            CrystalPortalNetwork.setLiveView(level, plan, false);
+            net.dnorberg.rivencraft.compat.ImmersivePortalsCrystalView.activate(
+                    level, pos, plan, holder.destination,
+                    holder.book.is(net.dnorberg.rivencraft.registry.ModItems.DESCRIPTIVE_BOOK.get()));
+        }
+        CrystalPortalNetwork.setLiveView(level, plan,
+                net.dnorberg.rivencraft.compat.ImmersivePortalsCrystalView.complete(
+                        level, pos, plan, holder.destination));
    }
 }
@@ -31,8 +31,7 @@ public final class CrystalPortalBlockEntity extends BlockEntity {
    @Override
    protected void loadAdditional(CompoundTag tag, HolderLookup.Provider registries) {
        super.loadAdditional(tag, registries);
-        receptacle = tag.contains(SOURCE_TAG, CompoundTag.TAG_COMPOUND)
-                ? net.minecraft.nbt.NbtUtils.readBlockPos(tag, SOURCE_TAG).orElse(null) : null;
+        receptacle = net.minecraft.nbt.NbtUtils.readBlockPos(tag, SOURCE_TAG).orElse(null);
    }

    @Override
@@ -20,6 +20,9 @@ public final class CloudPlatformGameTests {
        helper.getLevel().setBlock(pos, state, 2);
        helper.assertTrue(!state.getCollisionShape(helper.getLevel(), pos).isEmpty(),
                "Cloud platform must support a standing player");
+        helper.assertTrue(state.canOcclude(), "Arrival platform must be opaque");
+        helper.assertValueEqual(state.getDestroySpeed(helper.getLevel(), pos), 0.3F,
+                "Arrival platform should break as easily as glass");
        helper.assertTrue(ModBlocks.CLOUD_PLATFORM.get().getCloneItemStack(helper.getLevel(), pos, state).isEmpty(),
                "Cloud platform must not provide a pick-block item");
        helper.succeed();
@@ -0,0 +1,127 @@
+package net.dnorberg.rivencraft.book;
+
+import net.dnorberg.rivencraft.Rivencraft;
+import net.dnorberg.rivencraft.entity.DroppedBookEntity;
+import net.dnorberg.rivencraft.registry.ModEntities;
+import net.dnorberg.rivencraft.registry.ModItems;
+import net.minecraft.core.BlockPos;
+import net.minecraft.core.GlobalPos;
+import net.minecraft.gametest.framework.GameTest;
+import net.minecraft.gametest.framework.GameTestHelper;
+import net.minecraft.nbt.CompoundTag;
+import net.minecraft.world.InteractionHand;
+import net.minecraft.world.entity.item.ItemEntity;
+import net.minecraft.world.item.ItemStack;
+import net.minecraft.world.item.Items;
+import net.minecraft.world.level.block.Blocks;
+import net.minecraft.world.phys.AABB;
+import net.neoforged.neoforge.gametest.GameTestHolder;
+import net.neoforged.neoforge.gametest.PrefixGameTestTemplate;
+
+@GameTestHolder(Rivencraft.MOD_ID)
+@PrefixGameTestTemplate(false)
+public final class HandheldBookTravelGameTests {
+    private HandheldBookTravelGameTests() {
+    }
+
+    @GameTest(template = "empty")
+    public static void successfulHandheldTravelLeavesOnlyActiveBookAtOrigin(GameTestHelper helper) {
+        var player = helper.makeMockServerPlayerInLevel();
+        ItemStack book = new ItemStack(ModItems.LINKING_BOOK.get());
+        player.setItemInHand(InteractionHand.MAIN_HAND, book);
+        player.getInventory().setItem(1, new ItemStack(Items.DIAMOND));
+        var source = player.position();
+        BlockPos destination = helper.absolutePos(new BlockPos(2, 1, 2));
+        helper.getLevel().setBlock(destination, Blocks.AIR.defaultBlockState(), 2);
+        helper.getLevel().setBlock(destination.above(), Blocks.AIR.defaultBlockState(), 2);
+        LinkTarget target = new LinkTarget(GlobalPos.of(helper.getLevel().dimension(), destination), 0, 0);
+
+        helper.assertValueEqual(LinkingService.travelHandheld(player, InteractionHand.MAIN_HAND, book, target,
+                        new LinkProperties(LinkProperties.INTRA_LINKING), false), LinkingService.LinkResult.SUCCESS,
+                "A valid intra-dimensional handheld link must succeed");
+        helper.assertTrue(player.getMainHandItem().isEmpty(), "Only the active book must leave the hand");
+        helper.assertTrue(player.getInventory().getItem(1).is(Items.DIAMOND),
+                "An unrelated inventory item must remain with the player");
+        var drops = helper.getLevel().getEntitiesOfClass(DroppedBookEntity.class, new AABB(source, source).inflate(2.0),
+                entity -> entity.getItem().is(ModItems.LINKING_BOOK.get()));
+        helper.assertValueEqual(drops.size(), 1, "Exactly one recoverable book must remain at the departure point");
+        helper.assertTrue(drops.getFirst().getItem() == book,
+                "The model-rendered entity must retain the exact active book stack");
+        helper.assertTrue(drops.getFirst().copy() instanceof DroppedBookEntity,
+                "The pickup-animation copy must keep the custom renderer's entity type");
+        helper.succeed();
+    }
+
+    @GameTest(template = "empty")
+    public static void rejectedHandheldTravelKeepsBook(GameTestHelper helper) {
+        var player = helper.makeMockServerPlayerInLevel();
+        ItemStack book = new ItemStack(ModItems.LINKING_BOOK.get());
+        player.setItemInHand(InteractionHand.OFF_HAND, book);
+        LinkTarget target = new LinkTarget(GlobalPos.of(helper.getLevel().dimension(), player.blockPosition()), 0, 0);
+
+        helper.assertValueEqual(LinkingService.travelHandheld(player, InteractionHand.OFF_HAND, book, target,
+                        LinkProperties.NONE, false), LinkingService.LinkResult.INTRA_LINKING_REQUIRED,
+                "A same-dimension link without Intra Linking must be rejected");
+        helper.assertTrue(player.getOffhandItem() == book, "The exact rejected book must be restored to its hand");
+        helper.assertTrue(helper.getLevel().getEntitiesOfClass(ItemEntity.class,
+                new AABB(player.position(), player.position()).inflate(2.0),
+                entity -> entity.getItem().is(ModItems.LINKING_BOOK.get())).isEmpty(),
+                "A rejected link must not leave a second copy at the origin");
+        helper.succeed();
+    }
+
+    @GameTest(template = "empty")
+    public static void disarmDropsOtherInventoryWithoutDuplicatingActiveBook(GameTestHelper helper) {
+        var player = helper.makeMockServerPlayerInLevel();
+        ItemStack book = new ItemStack(ModItems.LINKING_BOOK.get());
+        player.setItemInHand(InteractionHand.MAIN_HAND, book);
+        player.getInventory().setItem(1, new ItemStack(Items.DIAMOND));
+        var source = player.position();
+        BlockPos destination = helper.absolutePos(new BlockPos(2, 1, 2));
+        helper.getLevel().setBlock(destination, Blocks.AIR.defaultBlockState(), 2);
+        helper.getLevel().setBlock(destination.above(), Blocks.AIR.defaultBlockState(), 2);
+        LinkTarget target = new LinkTarget(GlobalPos.of(helper.getLevel().dimension(), destination), 0, 0);
+
+        helper.assertValueEqual(LinkingService.travelHandheld(player, InteractionHand.MAIN_HAND, book, target,
+                        new LinkProperties(LinkProperties.INTRA_LINKING | LinkProperties.DISARM), false),
+                LinkingService.LinkResult.SUCCESS, "Disarm must not block handheld travel");
+        var drops = helper.getLevel().getEntitiesOfClass(ItemEntity.class, new AABB(source, source).inflate(2.0));
+        helper.assertValueEqual(drops.stream().filter(entity -> entity instanceof DroppedBookEntity).count(),
+                1L, "Disarm must not create a second copy of the active book");
+        helper.assertValueEqual(drops.stream().filter(entity -> entity.getItem().is(Items.DIAMOND)).count(),
+                1L, "Disarm must still drop unrelated inventory items");
+        helper.succeed();
+    }
+
+    @GameTest(template = "empty")
+    public static void originBookUsesSlowDecayWithoutVanillaDespawn(GameTestHelper helper) {
+        DroppedBookEntity book = new DroppedBookEntity(helper.getLevel(),
+                net.minecraft.world.phys.Vec3.ZERO, new ItemStack(ModItems.LINKING_BOOK.get()));
+        CompoundTag seeded = new CompoundTag();
+        book.saveWithoutId(seeded);
+        seeded.putInt("BookDecayTicks", 9_999);
+        book.readAdditionalSaveData(seeded);
+        book.tick();
+        CompoundTag saved = new CompoundTag();
+        book.saveWithoutId(saved);
+        helper.assertValueEqual(saved.getShort("Age"), (short)-32_768,
+                "The dropped book must not expire after vanilla's five minutes");
+        helper.assertValueEqual(saved.getShort("Health"), (short)4,
+                "A dropped book must lose one item-health point after 10,000 loaded ticks");
+        helper.assertValueEqual(saved.getInt("BookDecayTicks"), 0,
+                "Slow decay must reset its interval and persist across a restart");
+        DroppedBookEntity restored = new DroppedBookEntity(ModEntities.DROPPED_BOOK.get(), helper.getLevel());
+        restored.readAdditionalSaveData(saved);
+        CompoundTag resaved = new CompoundTag();
+        restored.saveWithoutId(resaved);
+        helper.assertTrue(restored.getItem().is(ModItems.LINKING_BOOK.get()),
+                "The custom book entity must retain its book on reload");
+        helper.assertValueEqual(resaved.getShort("Age"), (short)-32_768,
+                "The custom book must remain non-despawning after reload");
+        helper.assertValueEqual(resaved.getShort("Health"), (short)4,
+                "Decay damage must persist after reload");
+        helper.assertTrue(restored.copy().getItem().is(ModItems.LINKING_BOOK.get()),
+                "A pickup-animation copy must retain the book data after reload");
+        helper.succeed();
+    }
+}
@@ -0,0 +1,41 @@
+package net.dnorberg.rivencraft.book;
+
+import net.dnorberg.rivencraft.registry.ModSounds;
+import net.minecraft.core.particles.ParticleTypes;
+import net.minecraft.server.level.ServerLevel;
+import net.minecraft.server.level.ServerPlayer;
+import net.minecraft.sounds.SoundEvent;
+import net.minecraft.sounds.SoundSource;
+import net.minecraft.world.phys.Vec3;
+
+/** Legacy-style sound and particle bursts at both ends of a successful link. */
+public final class LinkVisualEffects {
+    private static final int PARTICLE_COUNT = 50;
+
+    private LinkVisualEffects() {}
+
+    public static SoundEvent sound(LinkProperties properties, boolean portal) {
+        // Legacy's Disarm flag takes precedence over a portal's sound override.
+        if (properties.has(LinkProperties.DISARM)) return ModSounds.LINK_DISARM.get();
+        if (portal) return ModSounds.LINK_PORTAL.get();
+        if (properties.has(LinkProperties.INTRA_LINKING)) return ModSounds.LINK_INTRA.get();
+        return ModSounds.LINK.get();
+    }
+
+    public static void play(ServerLevel source, Vec3 departure, ServerPlayer player,
+                            LinkProperties properties, boolean portal) {
+        SoundEvent event = sound(properties, portal);
+        burst(source, departure, event);
+        burst(player.serverLevel(), player.position(), event);
+    }
+
+    private static void burst(ServerLevel level, Vec3 position, SoundEvent event) {
+        level.playSound(null, position.x, position.y, position.z, event,
+                SoundSource.PLAYERS, 0.8F, level.random.nextFloat() * 0.2F + 0.9F);
+        // Legacy emitted 50 small neutral particles in a roughly one-by-two-
+        // block space. Cloud particles are a vanilla gray-white stand-in for
+        // its removed fixed-function particle class.
+        level.sendParticles(ParticleTypes.CLOUD, position.x, position.y, position.z,
+                PARTICLE_COUNT, 0.5, 1.0, 0.5, 0.005);
+    }
+}
@@ -5,10 +5,13 @@ import java.util.Optional;
 import java.util.stream.IntStream;
 import java.util.stream.Stream;
 import net.dnorberg.rivencraft.compat.ImmersivePortalsChunkLoaders;
+import net.dnorberg.rivencraft.entity.DroppedBookEntity;
 import net.minecraft.core.BlockPos;
 import net.minecraft.core.Direction;
 import net.minecraft.server.level.ServerLevel;
 import net.minecraft.server.level.ServerPlayer;
+import net.minecraft.world.InteractionHand;
+import net.minecraft.world.item.ItemStack;
 import net.minecraft.tags.BlockTags;
 import net.minecraft.world.level.border.WorldBorder;
 import net.minecraft.world.level.levelgen.Heightmap;
@@ -29,7 +32,42 @@ public final class LinkingService {
    }

    public static LinkResult travel(ServerPlayer player, LinkTarget target, LinkProperties properties) {
-        return travel(player, target, false, properties);
+        return travel(player, target, false, properties, false);
+    }
+
+    /** Removes only the active handheld book after a successful link, leaving it at the departure point. */
+    public static LinkResult travelHandheld(ServerPlayer player, InteractionHand hand, ItemStack activeBook,
+                                            LinkTarget target, LinkProperties properties, boolean requiresFooting) {
+        if (player.getItemInHand(hand) != activeBook || activeBook.isEmpty()) {
+            return LinkResult.NO_SAFE_DESTINATION;
+        }
+
+        ServerLevel sourceLevel = player.serverLevel();
+        Vec3 sourcePosition = player.position();
+        player.setItemInHand(hand, ItemStack.EMPTY);
+        boolean dropped = false;
+        try {
+            LinkResult result = requiresFooting
+                    ? travelWithFooting(player, target, properties)
+                    : travel(player, target, properties);
+            if (result != LinkResult.SUCCESS) return result;
+
+            DroppedBookEntity book = new DroppedBookEntity(sourceLevel, sourcePosition, activeBook);
+            dropped = sourceLevel.addFreshEntity(book);
+            return result;
+        } finally {
+            // Failed validation or a rejected entity spawn must never eat the book.
+            if (!dropped) {
+                if (player.getItemInHand(hand).isEmpty()) player.setItemInHand(hand, activeBook);
+                else if (!player.getInventory().add(activeBook)) player.drop(activeBook, false);
+            }
+            player.containerMenu.broadcastChanges();
+        }
+    }
+
+    /** Portal travel uses the vanilla transfer if its destination is not yet loaded. */
+    public static LinkResult travelPortal(ServerPlayer player, LinkTarget target, LinkProperties properties) {
+        return travel(player, target, false, properties, true);
    }

    public static Optional<Vec3> resolveDestination(ServerLevel level, BlockPos origin, boolean ageArrival) {
@@ -56,28 +94,29 @@ public final class LinkingService {
        Vec3 position = destination.get();
        Vec3 momentum = player.getDeltaMovement();
        if (properties.has(LinkProperties.DISARM)) dropInventoryAtSource(player);
-        teleport(player, destinationLevel, position, target);
+        teleport(player, destinationLevel, position, target, true);
        if (properties.has(LinkProperties.MAINTAIN_MOMENTUM)) player.setDeltaMovement(momentum);
        player.resetFallDistance();
        return LinkResult.SUCCESS;
    }

-    /** A descriptive portal uses the book's Age destination without requiring a landing platform. */
+    /** A descriptive portal requires existing footing, but never generates a landing platform. */
    public static LinkResult travelDescriptivePortal(ServerPlayer player, LinkTarget target, LinkProperties properties) {
        ServerLevel destinationLevel = player.getServer().getLevel(target.location().dimension());
        if (destinationLevel == null) return LinkResult.MISSING_DIMENSION;
-        Optional<Vec3> destination = resolveDestination(destinationLevel, target.location().pos(), false);
+        boolean instant = destinationChunksLoaded(destinationLevel, target.location().pos());
+        Optional<Vec3> destination = resolveDestination(destinationLevel, target.location().pos(), true);
        if (destination.isEmpty()) return LinkResult.NO_SAFE_DESTINATION;
        Vec3 momentum = player.getDeltaMovement();
        if (properties.has(LinkProperties.DISARM)) dropInventoryAtSource(player);
-        teleport(player, destinationLevel, destination.get(), target);
+        teleport(player, destinationLevel, destination.get(), target, instant);
        if (properties.has(LinkProperties.MAINTAIN_MOMENTUM)) player.setDeltaMovement(momentum);
        player.resetFallDistance();
        return LinkResult.SUCCESS;
    }

    private static LinkResult travel(ServerPlayer player, LinkTarget target, boolean requiresFooting,
-                                     LinkProperties properties) {
+                                     LinkProperties properties, boolean portal) {
        ServerLevel destinationLevel = player.getServer().getLevel(target.location().dimension());
        if (destinationLevel == null) {
            return LinkResult.MISSING_DIMENSION;
@@ -85,6 +124,7 @@ public final class LinkingService {
        if (destinationLevel == player.level() && !properties.has(LinkProperties.INTRA_LINKING))
            return LinkResult.INTRA_LINKING_REQUIRED;

+        boolean instant = !portal || destinationChunksLoaded(destinationLevel, target.location().pos());
        Optional<Vec3> destination = resolveDestination(destinationLevel, target.location().pos(), requiresFooting);
        if (destination.isEmpty()) {
            return LinkResult.NO_SAFE_DESTINATION;
@@ -93,7 +133,7 @@ public final class LinkingService {
        Vec3 position = destination.get();
        Vec3 momentum = player.getDeltaMovement();
        if (properties.has(LinkProperties.DISARM)) dropInventoryAtSource(player);
-        teleport(player, destinationLevel, position, target);
+        teleport(player, destinationLevel, position, target, instant);
        if (properties.has(LinkProperties.MAINTAIN_MOMENTUM)) player.setDeltaMovement(momentum);
        player.resetFallDistance();
        return LinkResult.SUCCESS;
@@ -115,22 +155,36 @@ public final class LinkingService {
            ServerPlayer player,
            ServerLevel destinationLevel,
            Vec3 position,
-            LinkTarget target
+            LinkTarget target,
+            boolean instant
    ) {
        if (ModList.get().isLoaded("immersive_portals_core")) {
            ImmersivePortalsChunkLoaders.close(player);
-            ImmersivePortalsChunkLoaders.teleport(
-                    player, destinationLevel, position, target.yaw(), target.pitch());
-        } else {
-            player.teleportTo(
-                    destinationLevel,
-                    position.x,
-                    position.y,
-                    position.z,
-                    target.yaw(),
-                    target.pitch()
-            );
+            if (instant) {
+                ImmersivePortalsChunkLoaders.teleport(
+                        player, destinationLevel, position, target.yaw(), target.pitch());
+                return;
+            }
        }
+        player.teleportTo(
+                destinationLevel,
+                position.x,
+                position.y,
+                position.z,
+                target.yaw(),
+                target.pitch()
+        );
+    }
+
+    private static boolean destinationChunksLoaded(ServerLevel level, BlockPos center) {
+        int chunkX = center.getX() >> 4;
+        int chunkZ = center.getZ() >> 4;
+        for (int x = chunkX - 1; x <= chunkX + 1; x++) {
+            for (int z = chunkZ - 1; z <= chunkZ + 1; z++) {
+                if (!level.getChunkSource().hasChunk(x, z)) return false;
+            }
+        }
+        return true;
    }

    static Optional<Vec3> findSafeDestination(ServerLevel level, BlockPos origin) {
@@ -5,6 +5,7 @@ import net.dnorberg.rivencraft.registry.ModBlockEntities;
 import net.dnorberg.rivencraft.registry.ModBlocks;
 import net.dnorberg.rivencraft.registry.ModDataComponents;
 import net.dnorberg.rivencraft.registry.ModItems;
+import net.dnorberg.rivencraft.registry.ModEntities;
 import net.minecraft.client.renderer.item.ItemProperties;
 import net.minecraft.client.renderer.ItemBlockRenderTypes;
 import net.minecraft.client.renderer.RenderType;
@@ -34,6 +35,7 @@ public final class ClientEvents {

    @SubscribeEvent
    public static void registerRenderers(EntityRenderersEvent.RegisterRenderers event) {
+        event.registerEntityRenderer(ModEntities.DROPPED_BOOK.get(), DroppedBookRenderer::new);
        event.registerBlockEntityRenderer(ModBlockEntities.BOOK_STAND.get(), BookStandRenderer::new);
        event.registerBlockEntityRenderer(ModBlockEntities.WRITING_DESK.get(), WritingDeskRenderer::new);
        event.registerBlockEntityRenderer(ModBlockEntities.STAR_FISSURE.get(), StarFissureRenderer::new);
@@ -78,13 +80,15 @@ public final class ClientEvents {
            ItemBlockRenderTypes.setRenderLayer(ModBlocks.MEDIUM_CRYSTAL_BUD.get(), RenderType.cutout());
            ItemBlockRenderTypes.setRenderLayer(ModBlocks.LARGE_CRYSTAL_BUD.get(), RenderType.cutout());
            ItemBlockRenderTypes.setRenderLayer(ModBlocks.CRYSTAL_CLUSTER.get(), RenderType.cutout());
-            ItemBlockRenderTypes.setRenderLayer(ModBlocks.CLOUD_PLATFORM.get(), RenderType.translucent());
+            ItemBlockRenderTypes.setRenderLayer(ModBlocks.INK_MIXER.get(), RenderType.cutout());
            ItemBlockRenderTypes.setRenderLayer(ModBlocks.CRYSTAL_PORTAL.get(), RenderType.translucent());
            // Immersive Portals composes the remote view before translucent blocks.
            // Draw the opaque crystal frame in that later pass so it masks the view;
            // the portal cell itself is invisible while its live view is active.
            if (ModList.get().isLoaded("immersive_portals_core"))
                ItemBlockRenderTypes.setRenderLayer(ModBlocks.CRYSTAL_BLOCK.get(), RenderType.translucent());
+            if (ModList.get().isLoaded("create"))
+                net.dnorberg.rivencraft.compat.RivencraftPonderGuide.register();
        });
        NeoForge.EVENT_BUS.addListener(ClientBookInteractionHandler::onRightClickItem);
        NeoForge.EVENT_BUS.addListener(ClientBookInteractionHandler::onRightClickBlock);
@@ -0,0 +1,51 @@
+package net.dnorberg.rivencraft.client;
+
+import com.mojang.blaze3d.vertex.PoseStack;
+import com.mojang.blaze3d.vertex.VertexConsumer;
+import com.mojang.math.Axis;
+import net.dnorberg.rivencraft.entity.DroppedBookEntity;
+import net.dnorberg.rivencraft.registry.ModItems;
+import net.minecraft.client.model.BookModel;
+import net.minecraft.client.model.geom.ModelLayers;
+import net.minecraft.client.renderer.MultiBufferSource;
+import net.minecraft.client.renderer.RenderType;
+import net.minecraft.client.renderer.entity.EntityRenderer;
+import net.minecraft.client.renderer.entity.EntityRendererProvider;
+import net.minecraft.resources.ResourceLocation;
+
+/** Renders the same open book model and textures as Rivencraft's book stands. */
+public final class DroppedBookRenderer extends EntityRenderer<DroppedBookEntity> {
+    private static final ResourceLocation LINKING_TEXTURE = ResourceLocation.fromNamespaceAndPath(
+            "rivencraft", "textures/entity/linking_book.png");
+    private static final ResourceLocation DESCRIPTIVE_TEXTURE = ResourceLocation.fromNamespaceAndPath(
+            "rivencraft", "textures/entity/descriptive_book.png");
+    private final BookModel model;
+
+    public DroppedBookRenderer(EntityRendererProvider.Context context) {
+        super(context);
+        model = new BookModel(context.bakeLayer(ModelLayers.BOOK));
+        shadowRadius = 0.25F;
+    }
+
+    @Override
+    public void render(DroppedBookEntity entity, float yaw, float partialTick, PoseStack poseStack,
+                       MultiBufferSource buffers, int packedLight) {
+        poseStack.pushPose();
+        poseStack.translate(0.0F, 0.0625F, 0.0F);
+        poseStack.mulPose(Axis.YP.rotationDegrees(yaw + 90.0F));
+        // The opened model's covers rotate toward the YZ plane. As in Legacy's
+        // dropped-book renderer, a Z-axis quarter-turn lays the pages skyward.
+        poseStack.mulPose(Axis.ZP.rotationDegrees(90.0F));
+        poseStack.scale(0.8F, 0.8F, 0.8F);
+        model.setupAnim(0.0F, 0.0F, 0.0F, 1.2F);
+        VertexConsumer vertices = buffers.getBuffer(RenderType.entitySolid(getTextureLocation(entity)));
+        model.render(poseStack, vertices, packedLight, net.minecraft.client.renderer.texture.OverlayTexture.NO_OVERLAY, -1);
+        poseStack.popPose();
+        super.render(entity, yaw, partialTick, poseStack, buffers, packedLight);
+    }
+
+    @Override
+    public ResourceLocation getTextureLocation(DroppedBookEntity entity) {
+        return entity.getItem().is(ModItems.DESCRIPTIVE_BOOK.get()) ? DESCRIPTIVE_TEXTURE : LINKING_TEXTURE;
+    }
+}
@@ -16,7 +16,10 @@ import qouteall.q_misc_util.dimension.DimensionIntId;

 /** Isolated server bridge; this class is loaded only when Immersive Portals is installed. */
 public final class ImmersivePortalsChunkLoaders {
-    private static final Map<ServerPlayer, ChunkLoader> LOADERS = new IdentityHashMap<>();
+    private static final long MAX_PREVIEW_TICKS = 20L * 60 * 5;
+    private static final Map<ServerPlayer, PreviewLoader> LOADERS = new IdentityHashMap<>();
+
+    private record PreviewLoader(ChunkLoader loader, long expiresAt) {}

    private ImmersivePortalsChunkLoaders() {
    }
@@ -35,29 +38,40 @@ public final class ImmersivePortalsChunkLoaders {

        ChunkLoader loader = new ChunkLoader(level.dimension(), centerChunkX, centerChunkZ, 8);
        PortalAPI.addChunkLoaderForPlayer(player, loader);
-        LOADERS.put(player, loader);
+        LOADERS.put(player, new PreviewLoader(loader, player.getServer().getTickCount() + MAX_PREVIEW_TICKS));
        ImmPtlChunkTracking.immediatelyUpdateForPlayer(player);
    }

    public static synchronized void close(ServerPlayer player) {
-        ChunkLoader loader = LOADERS.remove(player);
-        if (loader != null) {
-            PortalAPI.removeChunkLoaderForPlayer(player, loader);
+        PreviewLoader preview = LOADERS.remove(player);
+        if (preview != null) {
+            PortalAPI.removeChunkLoaderForPlayer(player, preview.loader());
        }
    }

+    /** Fail-safe for a lost close packet: no book preview can hold chunks indefinitely. */
+    public static synchronized void expire(MinecraftServer server) {
+        if (server.getTickCount() % 20 != 0) return;
+        LOADERS.entrySet().removeIf(entry -> {
+            if (server.getTickCount() < entry.getValue().expiresAt()
+                    && server.getLevel(entry.getValue().loader().dimension()) != null) return false;
+            PortalAPI.removeChunkLoaderForPlayer(entry.getKey(), entry.getValue().loader());
+            return true;
+        });
+    }
+
    public static synchronized void closeForDimension(ResourceKey<Level> dimension) {
        LOADERS.entrySet().removeIf(entry -> {
-            if (!entry.getValue().dimension().equals(dimension)) {
+            if (!entry.getValue().loader().dimension().equals(dimension)) {
                return false;
            }
-            PortalAPI.removeChunkLoaderForPlayer(entry.getKey(), entry.getValue());
+            PortalAPI.removeChunkLoaderForPlayer(entry.getKey(), entry.getValue().loader());
            return true;
        });
    }

    public static synchronized void closeAll() {
-        LOADERS.forEach(PortalAPI::removeChunkLoaderForPlayer);
+        LOADERS.forEach((player, preview) -> PortalAPI.removeChunkLoaderForPlayer(player, preview.loader()));
        LOADERS.clear();
    }

@@ -23,12 +23,12 @@ public final class ImmersivePortalsCrystalView {
    private ImmersivePortalsCrystalView() {}

    public static void activate(ServerLevel source, BlockPos receptacle,
-                                CrystalPortalNetwork.Plan plan, LinkTarget target) {
+                                CrystalPortalNetwork.Plan plan, LinkTarget target, boolean requireFooting) {
        remove(source, receptacle);
        ServerLevel destinationLevel = source.getServer().getLevel(target.location().dimension());
        if (destinationLevel == null) return;
        // This is the same safe-location search used by portal book travel.
-        var arrival = LinkingService.resolveDestination(destinationLevel, target.location().pos(), false);
+        var arrival = LinkingService.resolveDestination(destinationLevel, target.location().pos(), requireFooting);
        if (arrival.isEmpty()) return;
        Vec3 arrivalEye = arrival.get().add(0, 1.62, 0);
        for (CrystalPortalSurfaces.Surface surface : CrystalPortalSurfaces.group(source, plan)) {
@@ -46,11 +46,15 @@ public final class ImmersivePortalsCrystalView {
                        && (entity.portalTag.equals(tag) || entity.portalTag.equals(oldTag)))) portal.discard();
    }

-    public static boolean exists(ServerLevel source, BlockPos receptacle) {
+    public static boolean complete(ServerLevel source, BlockPos receptacle,
+                                   CrystalPortalNetwork.Plan plan, LinkTarget target) {
        String tag = tag(receptacle);
-        return !source.getEntitiesOfClass(Portal.class,
+        var views = source.getEntitiesOfClass(Portal.class,
                new AABB(receptacle).inflate(CrystalPortalNetwork.MAX_RADIUS + 2),
-                entity -> tag.equals(entity.portalTag)).isEmpty();
+                entity -> tag.equals(entity.portalTag));
+        int expected = CrystalPortalSurfaces.group(source, plan).size() * 2;
+        return expected > 0 && views.size() == expected && views.stream()
+                .allMatch(view -> target.location().dimension().equals(view.getDestDim()));
    }

    private static void spawn(ServerLevel source, BlockPos receptacle, CrystalPortalSurfaces.Surface surface,
@@ -0,0 +1,108 @@
+package net.dnorberg.rivencraft.compat;
+
+import net.createmod.ponder.api.PonderPalette;
+import net.createmod.ponder.api.registration.PonderPlugin;
+import net.createmod.ponder.api.registration.PonderSceneRegistrationHelper;
+import net.createmod.ponder.api.scene.SceneBuilder;
+import net.createmod.ponder.api.scene.SceneBuildingUtil;
+import net.createmod.ponder.foundation.PonderIndex;
+import net.dnorberg.rivencraft.Rivencraft;
+import net.dnorberg.rivencraft.block.BookReceptacleBlock;
+import net.dnorberg.rivencraft.block.CrystalPortalBlock;
+import net.dnorberg.rivencraft.registry.ModBlocks;
+import net.dnorberg.rivencraft.registry.ModItems;
+import net.minecraft.core.BlockPos;
+import net.minecraft.core.Direction;
+import net.minecraft.resources.ResourceLocation;
+import net.minecraft.world.entity.EntityType;
+import net.minecraft.world.item.ItemStack;
+import net.minecraft.world.level.block.Blocks;
+
+/** Create-only Ponder registration; this class is never loaded without Create. */
+public final class RivencraftPonderGuide implements PonderPlugin {
+    private static final ResourceLocation DEPOT_TEMPLATE = ResourceLocation.fromNamespaceAndPath("create", "depot");
+
+    private RivencraftPonderGuide() {}
+
+    public static void register() {
+        PonderIndex.addPlugin(new RivencraftPonderGuide());
+    }
+
+    @Override
+    public String getModId() {
+        return Rivencraft.MOD_ID;
+    }
+
+    @Override
+    public void registerScenes(PonderSceneRegistrationHelper<ResourceLocation> helper) {
+        // Create is already present when this plugin is registered. Its small
+        // depot schematic supplies an emptyable 6×4×6 canvas, so Rivencraft
+        // does not need to ship a separate binary Ponder template.
+        helper.forComponents(ModItems.BOOK_RECEPTACLE.getId(), ModItems.CRYSTAL_BLOCK.getId())
+                .addStoryBoard(DEPOT_TEMPLATE, RivencraftPonderGuide::crystalPortal);
+    }
+
+    private static void crystalPortal(SceneBuilder scene, SceneBuildingUtil util) {
+        scene.title("crystal_portal", "Building a Crystal Portal");
+        scene.configureBasePlate(0, 0, 6);
+        scene.scaleSceneView(0.85F);
+        scene.showBasePlate();
+        scene.world().setBlocks(util.select().fromTo(0, 1, 0, 5, 3, 5),
+                Blocks.AIR.defaultBlockState(), false);
+        scene.idle(10);
+
+        BlockPos center = util.grid().at(3, 2, 3);
+        scene.overlay().showText(65).text("Build a closed crystal frame with an open center.")
+                .pointAt(util.vector().centerOf(center)).placeNearTarget();
+        for (int x = 2; x <= 4; x++) {
+            for (int y = 1; y <= 3; y++) {
+                if (x == 3 && y == 2) continue;
+                BlockPos pos = util.grid().at(x, y, 3);
+                scene.world().setBlock(pos, ModBlocks.CRYSTAL_BLOCK.get().defaultBlockState(), false);
+                scene.world().showSection(util.select().position(pos), Direction.DOWN);
+                scene.idle(3);
+            }
+        }
+        scene.idle(30);
+
+        BlockPos receptacle = util.grid().at(2, 1, 2);
+        scene.overlay().showText(70).text("Attach a Book Receptacle to one crystal, facing outward.")
+                .pointAt(util.vector().centerOf(receptacle)).placeNearTarget();
+        scene.world().setBlock(receptacle, ModBlocks.BOOK_RECEPTACLE.get().defaultBlockState()
+                .setValue(BookReceptacleBlock.FACING, Direction.NORTH), false);
+        scene.world().showSection(util.select().position(receptacle), Direction.DOWN);
+        scene.idle(75);
+
+        scene.overlay().showText(65).text("Insert a bound Linking or Descriptive Book to activate the portal.")
+                .colored(PonderPalette.INPUT).pointAt(util.vector().centerOf(receptacle)).placeNearTarget();
+        scene.overlay().showControls(util.vector().centerOf(receptacle),
+                net.createmod.catnip.math.Pointing.RIGHT, 55)
+                .rightClick().withItem(new ItemStack(ModItems.LINKING_BOOK.get()));
+        scene.idle(65);
+
+        scene.world().setBlock(center, ModBlocks.CRYSTAL_PORTAL.get().defaultBlockState()
+                .setValue(CrystalPortalBlock.AXIS, Direction.Axis.Z), false);
+        scene.world().showSection(util.select().position(center), Direction.DOWN);
+        scene.effects().indicateSuccess(center);
+        scene.overlay().showText(80).text("Step through the portal. Remove the book to close it.")
+                .colored(PonderPalette.OUTPUT).pointAt(util.vector().centerOf(center)).placeNearTarget();
+        scene.idle(20);
+        var parrot = scene.world().createEntity(world -> {
+            var bird = EntityType.PARROT.create(world);
+            bird.setNoAi(true);
+            bird.setPos(3.5, 2.05, 1.5);
+            bird.setYRot(0);
+            return bird;
+        });
+        scene.idle(10);
+        for (int step = 1; step <= 7; step++) {
+            double z = 1.5 + step * 0.42;
+            scene.world().modifyEntity(parrot, bird -> bird.setPos(3.5, 2.05, z));
+            scene.idle(5);
+        }
+        scene.world().modifyEntity(parrot, bird -> bird.discard());
+        scene.effects().indicateSuccess(center);
+        scene.idle(20);
+        scene.markAsFinished();
+    }
+}
@@ -75,7 +75,7 @@ public final class RivencraftConfig {
                        "Controls automatic Return Link creation for Descriptive Book travel.",
                        "ON_CREATION creates one link when an Age is first reached; ALWAYS creates one on every arrival; DISABLED creates none."
                )
-                .defineEnum("return_link_mode", ReturnLinkMode.ON_CREATION);
+                .defineEnum("return_link_mode", ReturnLinkMode.DISABLED);
        builder.pop();
        builder.push("libraries");
        LIBRARY_LOOT_MODE = builder.comment(
@@ -0,0 +1,62 @@
+package net.dnorberg.rivencraft.entity;
+
+import net.dnorberg.rivencraft.registry.ModEntities;
+import net.minecraft.nbt.CompoundTag;
+import net.minecraft.world.entity.EntityType;
+import net.minecraft.world.entity.item.ItemEntity;
+import net.minecraft.world.item.ItemStack;
+import net.minecraft.world.level.Level;
+import net.minecraft.world.phys.Vec3;
+
+/** A recoverable, model-rendered book left behind by handheld linking. */
+public final class DroppedBookEntity extends ItemEntity {
+    private static final String DECAY_TICKS_TAG = "BookDecayTicks";
+    private static final int SLOW_DECAY_INTERVAL = 10_000;
+    private int decayTicks;
+
+    public DroppedBookEntity(EntityType<DroppedBookEntity> type, Level level) {
+        super(type, level);
+    }
+
+    public DroppedBookEntity(Level level, Vec3 position, ItemStack stack) {
+        this(ModEntities.DROPPED_BOOK.get(), level);
+        setPos(position.x, position.y + 0.25, position.z);
+        setDeltaMovement(Vec3.ZERO);
+        setItem(stack);
+        setUnlimitedLifetime();
+        setPickUpDelay(20);
+    }
+
+    /** Vanilla's pickup particle calls ItemEntity.copy() and renders the returned entity. */
+    @Override
+    public DroppedBookEntity copy() {
+        DroppedBookEntity copy = new DroppedBookEntity(ModEntities.DROPPED_BOOK.get(), level());
+        copy.copyPosition(this);
+        copy.setItem(getItem().copy());
+        copy.setUnlimitedLifetime();
+        return copy;
+    }
+
+    @Override
+    public void tick() {
+        super.tick();
+        if (level().isClientSide || isRemoved()) return;
+        if (++decayTicks >= SLOW_DECAY_INTERVAL) {
+            decayTicks = 0;
+            hurt(damageSources().starve(), 1.0F);
+        }
+        if (!isRemoved() && isInWaterOrRain()) hurt(damageSources().drown(), 1.0F);
+    }
+
+    @Override
+    public void addAdditionalSaveData(CompoundTag tag) {
+        super.addAdditionalSaveData(tag);
+        tag.putInt(DECAY_TICKS_TAG, decayTicks);
+    }
+
+    @Override
+    public void readAdditionalSaveData(CompoundTag tag) {
+        super.readAdditionalSaveData(tag);
+        decayTicks = Math.max(0, Math.min(tag.getInt(DECAY_TICKS_TAG), SLOW_DECAY_INTERVAL - 1));
+    }
+}
@@ -1,10 +1,13 @@
 package net.dnorberg.rivencraft.event;

 import net.dnorberg.rivencraft.compat.ImmersivePortalsChunkLoaders;
+import net.dnorberg.rivencraft.portal.PortalTravelCooldown;
+import net.dnorberg.rivencraft.portal.PortalTravelQueue;
 import net.minecraft.server.level.ServerPlayer;
 import net.neoforged.fml.ModList;
 import net.neoforged.neoforge.event.entity.player.PlayerEvent;
 import net.neoforged.neoforge.event.server.ServerStoppingEvent;
+import net.neoforged.neoforge.event.tick.ServerTickEvent;

 /** Server-authoritative cleanup for resources that exist only while a preview is active. */
 public final class AgeLifecycleEvents {
@@ -12,6 +15,10 @@ public final class AgeLifecycleEvents {
    }

    public static void onPlayerLoggedOut(PlayerEvent.PlayerLoggedOutEvent event) {
+        if (event.getEntity() instanceof ServerPlayer player) {
+            PortalTravelCooldown.forget(player);
+            PortalTravelQueue.forget(player);
+        }
        if (event.getEntity() instanceof ServerPlayer player
                && ModList.get().isLoaded("immersive_portals_core")) {
            ImmersivePortalsChunkLoaders.close(player);
@@ -19,8 +26,16 @@ public final class AgeLifecycleEvents {
    }

    public static void onServerStopping(ServerStoppingEvent event) {
+        PortalTravelCooldown.clear();
+        PortalTravelQueue.clear();
        if (ModList.get().isLoaded("immersive_portals_core")) {
            ImmersivePortalsChunkLoaders.closeAll();
        }
    }
+
+    public static void onServerTickPost(ServerTickEvent.Post event) {
+        PortalTravelQueue.process(event.getServer());
+        if (ModList.get().isLoaded("immersive_portals_core"))
+            ImmersivePortalsChunkLoaders.expire(event.getServer());
+    }
 }
@@ -2,6 +2,7 @@ package net.dnorberg.rivencraft.gametest;

 import net.dnorberg.rivencraft.Rivencraft;
 import net.dnorberg.rivencraft.block.BookReceptacleBlock;
+import net.dnorberg.rivencraft.block.CrystalPortalBlock;
 import net.dnorberg.rivencraft.block.entity.BookReceptacleBlockEntity;
 import net.dnorberg.rivencraft.block.entity.CrystalPortalBlockEntity;
 import net.dnorberg.rivencraft.book.LinkTarget;
@@ -15,7 +16,10 @@ import net.minecraft.core.Direction;
 import net.minecraft.core.GlobalPos;
 import net.minecraft.gametest.framework.GameTest;
 import net.minecraft.gametest.framework.GameTestHelper;
+import net.minecraft.nbt.CompoundTag;
+import net.minecraft.server.level.ServerLevel;
 import net.minecraft.world.item.ItemStack;
+import net.minecraft.world.level.block.Blocks;
 import net.neoforged.neoforge.gametest.GameTestHolder;
 import net.neoforged.neoforge.gametest.PrefixGameTestTemplate;

@@ -28,14 +32,17 @@ public final class CrystalPortalGameTests {
    public static void completeFrameActivatesAndReleasesBook(GameTestHelper helper) {
        var level = helper.getLevel();
        for (int x = 0; x < 3; x++) for (int y = 1; y < 4; y++) {
-            if (x == 1 && y == 2) continue;
+            if (x == 1 && y == 2) {
+                level.setBlock(helper.absolutePos(new BlockPos(x, y, 1)), Blocks.AIR.defaultBlockState(), 3);
+                continue;
+            }
            level.setBlock(helper.absolutePos(new BlockPos(x, y, 1)),
                    ModBlocks.CRYSTAL_BLOCK.get().defaultBlockState(), 3);
        }
        BlockPos holderPos = helper.absolutePos(new BlockPos(0, 1, 0));
        level.setBlock(holderPos, ModBlocks.BOOK_RECEPTACLE.get().defaultBlockState()
                .setValue(BookReceptacleBlock.FACING, Direction.NORTH), 3);
-        CrystalPortalNetwork.Plan plan = CrystalPortalNetwork.plan(level, holderPos);
+        CrystalPortalNetwork.Plan plan = planLoaded(level, holderPos);
        helper.assertTrue(plan.valid(), "A closed crystal frame must form a portal");
        BookReceptacleBlockEntity holder = (BookReceptacleBlockEntity) level.getBlockEntity(holderPos);
        holder.setBook(new ItemStack(ModItems.LINKING_BOOK.get()));
@@ -43,21 +50,120 @@ public final class CrystalPortalGameTests {
        holder.setDestination(destination);
        BookReceptacleBlockEntity restored = new BookReceptacleBlockEntity(holderPos, holder.getBlockState());
        restored.loadWithComponents(holder.saveWithoutMetadata(level.registryAccess()), level.registryAccess());
+        helper.assertTrue(restored.getBook().is(ModItems.LINKING_BOOK.get()),
+                "The book itself must survive a save/reload cycle");
        helper.assertValueEqual(restored.destination(), destination,
                "The portal destination must survive a save/reload cycle");
        helper.assertTrue(CrystalPortalNetwork.activate(level, holderPos, plan), "Portal placement must succeed");
        BlockPos center = helper.absolutePos(new BlockPos(1, 2, 1));
        helper.assertTrue(level.getBlockEntity(center) instanceof CrystalPortalBlockEntity portal
                && holderPos.equals(portal.receptacle()), "The portal must point to its one book holder");
+        CrystalPortalBlockEntity savedPortal = (CrystalPortalBlockEntity) level.getBlockEntity(center);
+        CrystalPortalBlockEntity restoredPortal = new CrystalPortalBlockEntity(center, savedPortal.getBlockState());
+        CompoundTag savedPortalTag = savedPortal.saveWithoutMetadata(level.registryAccess());
+        helper.assertTrue(savedPortalTag.contains("Receptacle"), "Portal owner must serialize: " + savedPortalTag);
+        restoredPortal.loadWithComponents(savedPortalTag,
+                level.registryAccess());
+        helper.assertTrue(restoredPortal.receptacle() != null, "Portal owner must deserialize: " + savedPortalTag);
+        helper.assertValueEqual(restoredPortal.receptacle(), holderPos,
+                "The portal-to-receptacle pointer must survive a full chunk save");
+        helper.assertTrue(CrystalPortalNetwork.reconcile(level, holderPos),
+                "A saved portal must recover without duplicating cells");
+        CrystalPortalNetwork.setLiveView(level, plan, true);
+        CrystalPortalBlockEntity livePortal = (CrystalPortalBlockEntity) level.getBlockEntity(center);
+        helper.assertValueEqual(livePortal.receptacle(), holderPos,
+                "Switching to the live view must retain the portal's book holder");
+        helper.assertTrue(livePortal.saveWithoutMetadata(level.registryAccess()).contains("Receptacle"),
+                "The live-view portal must persist its holder pointer to disk");
+        CrystalPortalNetwork.setLiveView(level, plan, false);
+        helper.assertValueEqual(((CrystalPortalBlockEntity) level.getBlockEntity(center)).receptacle(), holderPos,
+                "Switching back to the fallback texture must retain the holder");
+        helper.assertValueEqual(level.getBlockState(center).getValue(CrystalPortalBlock.AXIS), Direction.Axis.Z,
+                "A north/south opening must only show its two player-facing sides");
        CrystalPortalNetwork.shutdown(level, holderPos);
        helper.assertTrue(level.getBlockState(center).isAir(), "Removing the book must release the portal");
        helper.succeed();
    }

+    @GameTest(template = "empty")
+    public static void backgroundRepairDoesNotRecreateMissingCells(GameTestHelper helper) {
+        var level = helper.getLevel();
+        for (int x = 0; x < 3; x++) for (int y = 1; y < 4; y++) {
+            if (x == 1 && y == 2) {
+                level.setBlock(helper.absolutePos(new BlockPos(x, y, 1)), Blocks.AIR.defaultBlockState(), 3);
+                continue;
+            }
+            level.setBlock(helper.absolutePos(new BlockPos(x, y, 1)),
+                    ModBlocks.CRYSTAL_BLOCK.get().defaultBlockState(), 3);
+        }
+        BlockPos holderPos = helper.absolutePos(new BlockPos(0, 1, 0));
+        level.setBlock(holderPos, ModBlocks.BOOK_RECEPTACLE.get().defaultBlockState()
+                .setValue(BookReceptacleBlock.FACING, Direction.NORTH), 3);
+        BookReceptacleBlockEntity holder = (BookReceptacleBlockEntity) level.getBlockEntity(holderPos);
+        holder.setBook(new ItemStack(ModItems.LINKING_BOOK.get()));
+        helper.assertTrue(CrystalPortalNetwork.activate(level, holderPos, planLoaded(level, holderPos)),
+                "Portal must activate before the repair check");
+        BlockPos center = helper.absolutePos(new BlockPos(1, 2, 1));
+        level.removeBlock(center, false);
+        helper.assertTrue(!CrystalPortalNetwork.reconcile(level, holderPos),
+                "An unattended repair must not place a new cell across a protection boundary");
+        helper.assertTrue(level.getBlockState(center).isAir() && !holder.getBook().isEmpty(),
+                "A broken portal stays shut down while its one stored book remains retrievable");
+        helper.succeed();
+    }
+
    private static BlockPos centerTarget(GameTestHelper helper) {
        return helper.absolutePos(new BlockPos(1, 2, 1));
    }

+    @GameTest(template = "empty")
+    public static void eastWestOpeningOrientsFallbackSurface(GameTestHelper helper) {
+        var level = helper.getLevel();
+        for (int z = 1; z <= 3; z++) for (int y = 1; y <= 3; y++) {
+            if (z == 2 && y == 2) {
+                level.setBlock(helper.absolutePos(new BlockPos(1, y, z)), Blocks.AIR.defaultBlockState(), 3);
+                continue;
+            }
+            level.setBlock(helper.absolutePos(new BlockPos(1, y, z)),
+                    ModBlocks.CRYSTAL_BLOCK.get().defaultBlockState(), 3);
+        }
+        BlockPos holderPos = helper.absolutePos(new BlockPos(1, 1, 0));
+        level.setBlock(holderPos, ModBlocks.BOOK_RECEPTACLE.get().defaultBlockState()
+                .setValue(BookReceptacleBlock.FACING, Direction.NORTH), 3);
+        ((BookReceptacleBlockEntity) level.getBlockEntity(holderPos))
+                .setBook(new ItemStack(ModItems.LINKING_BOOK.get()));
+        helper.assertTrue(CrystalPortalNetwork.activate(level, holderPos, planLoaded(level, holderPos)),
+                "The east/west crystal opening must activate");
+        helper.assertValueEqual(level.getBlockState(helper.absolutePos(new BlockPos(1, 2, 2)))
+                .getValue(CrystalPortalBlock.AXIS), Direction.Axis.X,
+                "The fallback surface must face east and west, not north and south");
+        helper.succeed();
+    }
+
+    @GameTest(template = "empty")
+    public static void horizontalOpeningOrientsFallbackSurface(GameTestHelper helper) {
+        var level = helper.getLevel();
+        for (int x = 0; x < 3; x++) for (int z = 0; z < 3; z++) {
+            if (x == 1 && z == 1) {
+                level.setBlock(helper.absolutePos(new BlockPos(x, 1, z)), Blocks.AIR.defaultBlockState(), 3);
+                continue;
+            }
+            level.setBlock(helper.absolutePos(new BlockPos(x, 1, z)),
+                    ModBlocks.CRYSTAL_BLOCK.get().defaultBlockState(), 3);
+        }
+        BlockPos holderPos = helper.absolutePos(new BlockPos(0, 2, 1));
+        level.setBlock(holderPos, ModBlocks.BOOK_RECEPTACLE.get().defaultBlockState()
+                .setValue(BookReceptacleBlock.FACING, Direction.UP), 3);
+        ((BookReceptacleBlockEntity) level.getBlockEntity(holderPos))
+                .setBook(new ItemStack(ModItems.LINKING_BOOK.get()));
+        helper.assertTrue(CrystalPortalNetwork.activate(level, holderPos, planLoaded(level, holderPos)),
+                "The horizontal crystal opening must activate");
+        helper.assertValueEqual(level.getBlockState(helper.absolutePos(new BlockPos(1, 1, 1)))
+                .getValue(CrystalPortalBlock.AXIS), Direction.Axis.Y,
+                "The fallback surface must face up and down");
+        helper.succeed();
+    }
+
    @GameTest(template = "empty")
    public static void incompleteFrameCannotActivate(GameTestHelper helper) {
        var level = helper.getLevel();
@@ -66,7 +172,7 @@ public final class CrystalPortalGameTests {
                ModBlocks.CRYSTAL_BLOCK.get().defaultBlockState(), 3);
        level.setBlock(holderPos, ModBlocks.BOOK_RECEPTACLE.get().defaultBlockState()
                .setValue(BookReceptacleBlock.FACING, Direction.NORTH), 3);
-        helper.assertTrue(!CrystalPortalNetwork.plan(level, holderPos).valid(),
+        helper.assertTrue(!planLoaded(level, holderPos).valid(),
                "An incomplete frame must not take a book or leave portal cells");
        helper.succeed();
    }
@@ -75,28 +181,89 @@ public final class CrystalPortalGameTests {
    public static void multiCellOpeningHasOneContinuousView(GameTestHelper helper) {
        var level = helper.getLevel();
        for (int x = 0; x < 3; x++) for (int y = 1; y < 5; y++) {
-            if (x == 1 && (y == 2 || y == 3)) continue;
+            if (x == 1 && (y == 2 || y == 3)) {
+                level.setBlock(helper.absolutePos(new BlockPos(x, y, 1)), Blocks.AIR.defaultBlockState(), 3);
+                continue;
+            }
            level.setBlock(helper.absolutePos(new BlockPos(x, y, 1)),
                    ModBlocks.CRYSTAL_BLOCK.get().defaultBlockState(), 3);
        }
        BlockPos holderPos = helper.absolutePos(new BlockPos(0, 1, 0));
        level.setBlock(holderPos, ModBlocks.BOOK_RECEPTACLE.get().defaultBlockState()
                .setValue(BookReceptacleBlock.FACING, Direction.NORTH), 3);
-        CrystalPortalNetwork.Plan plan = CrystalPortalNetwork.plan(level, holderPos);
+        CrystalPortalNetwork.Plan plan = planLoaded(level, holderPos);
        helper.assertValueEqual(plan.portalCells().size(), 2, "The opening contains two portal cells");
+        ((BookReceptacleBlockEntity) level.getBlockEntity(holderPos))
+                .setBook(new ItemStack(ModItems.LINKING_BOOK.get()));
+        helper.assertTrue(CrystalPortalNetwork.activate(level, holderPos, plan),
+                "The two-cell opening must activate before its live-view grouping is inspected");
        helper.assertValueEqual(CrystalPortalSurfaces.group(level, plan).size(), 1,
                "Both cells must share one coherent Immersive Portals view");
        helper.succeed();
    }

    @GameTest(template = "empty")
-    public static void savedCooldownFromPreviousServerCannotBlockPortal(GameTestHelper helper) {
-        helper.assertTrue(!PortalTravelCooldown.blocked(5, -1),
-                "A player with no prior portal use must link immediately");
-        helper.assertTrue(!PortalTravelCooldown.blocked(5, 12000),
-                "A saved tick from the previous server session must not block travel");
-        helper.assertTrue(PortalTravelCooldown.blocked(105, 100),
-                "A recent portal use in the current session must still prevent loops");
+    public static void largeOpeningSurvivesAtomicActivation(GameTestHelper helper) {
+        var level = helper.getLevel();
+        for (int x = 0; x < 5; x++) for (int y = 1; y < 6; y++) {
+            if (x > 0 && x < 4 && y > 1 && y < 5) {
+                level.setBlock(helper.absolutePos(new BlockPos(x, y, 1)), Blocks.AIR.defaultBlockState(), 3);
+                continue;
+            }
+            level.setBlock(helper.absolutePos(new BlockPos(x, y, 1)),
+                    ModBlocks.CRYSTAL_BLOCK.get().defaultBlockState(), 3);
+        }
+        BlockPos holderPos = helper.absolutePos(new BlockPos(0, 1, 0));
+        level.setBlock(holderPos, ModBlocks.BOOK_RECEPTACLE.get().defaultBlockState()
+                .setValue(BookReceptacleBlock.FACING, Direction.NORTH), 3);
+        BookReceptacleBlockEntity holder = (BookReceptacleBlockEntity) level.getBlockEntity(holderPos);
+        holder.setBook(new ItemStack(ModItems.LINKING_BOOK.get()));
+        CrystalPortalNetwork.Plan plan = planLoaded(level, holderPos);
+        helper.assertValueEqual(plan.portalCells().size(), 9, "The large frame has a 3×3 opening");
+        helper.assertTrue(CrystalPortalNetwork.activate(level, holderPos, plan),
+                "The complete opening must activate");
+        for (BlockPos pos : plan.portalCells()) {
+            helper.assertTrue(level.getBlockState(pos).is(ModBlocks.CRYSTAL_PORTAL.get())
+                    && level.getBlockEntity(pos) instanceof CrystalPortalBlockEntity portal
+                    && holderPos.equals(portal.receptacle()),
+                    "Activation must retain every cell with the same book holder");
+        }
+        CrystalPortalNetwork.setLiveView(level, plan, true);
+        for (BlockPos pos : plan.portalCells()) {
+            ((CrystalPortalBlockEntity) level.getBlockEntity(pos))
+                    .loadWithComponents(new CompoundTag(), level.registryAccess());
+        }
+        helper.assertTrue(CrystalPortalNetwork.recoverSavedOwners(level, holderPos),
+                "An intact saved surface can recover its lost holder pointers without placing blocks");
+        for (BlockPos pos : plan.portalCells()) {
+            CrystalPortalBlockEntity portal = (CrystalPortalBlockEntity) level.getBlockEntity(pos);
+            helper.assertValueEqual(portal.receptacle(), holderPos,
+                    "Every recovered cell must point to the book holder");
+        }
        helper.succeed();
    }
+
+    @GameTest(template = "empty")
+    public static void portalCooldownIsIndependentAndSessionOnly(GameTestHelper helper) {
+        var first = helper.makeMockServerPlayerInLevel();
+        var second = helper.makeMockServerPlayerInLevel();
+        helper.assertTrue(!PortalTravelCooldown.blocked(5, -1),
+                "A player with no prior portal use must link immediately");
+        PortalTravelCooldown.mark(first, 100);
+        helper.assertTrue(PortalTravelCooldown.blocked(first, 105)
+                && !PortalTravelCooldown.blocked(second, 105),
+                "One player's loop protection must not block another player");
+        PortalTravelCooldown.clear();
+        helper.assertTrue(!PortalTravelCooldown.blocked(first, 105),
+                "A new server session must never inherit a saved portal cooldown");
+        helper.succeed();
+    }
+
+    private static CrystalPortalNetwork.Plan planLoaded(ServerLevel level, BlockPos holderPos) {
+        int chunkX = holderPos.getX() >> 4;
+        int chunkZ = holderPos.getZ() >> 4;
+        for (int x = chunkX - 1; x <= chunkX + 1; x++)
+            for (int z = chunkZ - 1; z <= chunkZ + 1; z++) level.getChunk(x, z);
+        return CrystalPortalNetwork.plan(level, holderPos);
+    }
 }
@@ -0,0 +1,122 @@
+package net.dnorberg.rivencraft.gametest;
+
+import java.util.List;
+import net.dnorberg.rivencraft.Rivencraft;
+import net.dnorberg.rivencraft.advancement.ProgressionAdvancements;
+import net.dnorberg.rivencraft.block.entity.InkMixerBlockEntity;
+import net.dnorberg.rivencraft.block.entity.WritingDeskBlockEntity;
+import net.dnorberg.rivencraft.item.PageItem;
+import net.dnorberg.rivencraft.menu.InkMixerMenu;
+import net.dnorberg.rivencraft.menu.WritingDeskMenu;
+import net.dnorberg.rivencraft.registry.ModBlocks;
+import net.dnorberg.rivencraft.registry.ModItems;
+import net.dnorberg.rivencraft.writing.SymbolReference;
+import net.minecraft.core.BlockPos;
+import net.minecraft.gametest.framework.GameTest;
+import net.minecraft.gametest.framework.GameTestHelper;
+import net.minecraft.resources.ResourceLocation;
+import net.minecraft.server.level.ServerPlayer;
+import net.minecraft.world.inventory.ClickType;
+import net.minecraft.world.item.ItemStack;
+import net.minecraft.world.item.Items;
+import net.neoforged.neoforge.gametest.GameTestHolder;
+import net.neoforged.neoforge.gametest.PrefixGameTestTemplate;
+
+@GameTestHolder(Rivencraft.MOD_ID)
+@PrefixGameTestTemplate(false)
+public final class Milestone7AdvancementGameTests {
+    private Milestone7AdvancementGameTests() {}
+
+    @GameTest(template = "empty")
+    public static void progressionAndRecipeUnlocksLoad(GameTestHelper helper) {
+        var registry = helper.getLevel().getServer().getAdvancements();
+        for (String path : List.of("root", "page", "linking_book", "link_panel",
+                "copy_page", "bind_age", "enter_age", "open_portal")) {
+            helper.assertTrue(registry.get(id("progression/" + path)) != null,
+                    "Progression advancement must load: " + path);
+        }
+        for (String path : List.of("book_binder", "book_receptacle", "crystal_block",
+                "ink_mixer", "ink_vial", "notebook", "writing_desk")) {
+            helper.assertTrue(registry.get(id("recipes/misc/" + path)) != null,
+                    "Recipe-book unlock must load: " + path);
+        }
+        var player = helper.makeMockServerPlayerInLevel();
+        for (String path : List.of("book_binder", "ink_mixer", "notebook", "writing_desk")) {
+            player.getAdvancements().award(registry.get(id("recipes/misc/" + path)), "has_material");
+            helper.assertTrue(player.getRecipeBook().contains(id(path)),
+                    "Discovering the material must unlock the " + path + " recipe");
+        }
+        helper.succeed();
+    }
+
+    @GameTest(template = "empty")
+    public static void actionAwardsAreServerOwnedAndPerPlayer(GameTestHelper helper) {
+        var first = helper.makeMockServerPlayerInLevel();
+        var second = helper.makeMockServerPlayerInLevel();
+        var advancement = helper.getLevel().getServer().getAdvancements().get(id("progression/copy_page"));
+        helper.assertFalse(first.getAdvancements().getOrStartProgress(advancement).isDone(),
+                "Opening a menu or preview must not award a copied Page");
+        helper.assertFalse(second.getAdvancements().getOrStartProgress(advancement).isDone(),
+                "Another player must not inherit the advancement");
+        ProgressionAdvancements.awardAgeTravel(first);
+        var travel = helper.getLevel().getServer().getAdvancements().get(id("progression/enter_age"));
+        helper.assertFalse(first.getAdvancements().getOrStartProgress(travel).isDone(),
+                "Overworld travel or a preview must not count as entering an Age");
+        ProgressionAdvancements.award(first, ProgressionAdvancements.COPY_PAGE);
+        helper.assertTrue(first.getAdvancements().getOrStartProgress(advancement).isDone(),
+                "The server must award the player who completed the action");
+        helper.assertFalse(second.getAdvancements().getOrStartProgress(advancement).isDone(),
+                "Advancement progress must remain per-player in multiplayer");
+        helper.succeed();
+    }
+
+    @GameTest(template = "empty")
+    public static void mixerPreviewDoesNotAwardButTakingPanelDoes(GameTestHelper helper) {
+        BlockPos pos = helper.absolutePos(new BlockPos(1, 1, 1));
+        helper.getLevel().setBlock(pos, ModBlocks.INK_MIXER.get().defaultBlockState(), 3);
+        var mixer = (InkMixerBlockEntity) helper.getLevel().getBlockEntity(pos);
+        mixer.setItem(InkMixerBlockEntity.PAPER, new ItemStack(Items.PAPER));
+        mixer.setItem(InkMixerBlockEntity.INK, new ItemStack(ModItems.INK_VIAL.get()));
+        var player = nearbyPlayer(helper, pos);
+        var menu = new InkMixerMenu(1, player.getInventory(), mixer);
+        helper.assertFalse(done(player, ProgressionAdvancements.LINK_PANEL),
+                "Opening the Ink Mixer must not award its milestone");
+        menu.clicked(InkMixerMenu.RESULT, 0, ClickType.PICKUP, player);
+        helper.assertTrue(done(player, ProgressionAdvancements.LINK_PANEL),
+                "Taking the completed Link Panel must award its milestone");
+        helper.succeed();
+    }
+
+    @GameTest(template = "empty")
+    public static void deskPreviewDoesNotAwardButCopyingDoes(GameTestHelper helper) {
+        BlockPos pos = helper.absolutePos(new BlockPos(1, 1, 1));
+        helper.getLevel().setBlock(pos, ModBlocks.WRITING_DESK.get().defaultBlockState(), 3);
+        var desk = (WritingDeskBlockEntity) helper.getLevel().getBlockEntity(pos);
+        desk.setItem(0, PageItem.createSymbolPage(new SymbolReference(id("terrain/standard"))));
+        desk.setItem(WritingDeskBlockEntity.PAPER, new ItemStack(Items.PAPER));
+        desk.setItem(WritingDeskBlockEntity.INK, new ItemStack(ModItems.INK_VIAL.get()));
+        var player = nearbyPlayer(helper, pos);
+        var menu = new WritingDeskMenu(1, player.getInventory(), desk);
+        helper.assertFalse(done(player, ProgressionAdvancements.COPY_PAGE),
+                "Opening the Writing Desk must not award a copied Page");
+        menu.clicked(WritingDeskMenu.COPY_RESULT, 0, ClickType.PICKUP, player);
+        helper.assertTrue(done(player, ProgressionAdvancements.COPY_PAGE),
+                "Taking a copied Page must award its milestone");
+        helper.succeed();
+    }
+
+    private static ServerPlayer nearbyPlayer(GameTestHelper helper, BlockPos pos) {
+        var player = helper.makeMockServerPlayerInLevel();
+        player.moveTo(pos.getX() + 0.5, pos.getY() + 0.5, pos.getZ() + 0.5);
+        return player;
+    }
+
+    private static boolean done(ServerPlayer player, String path) {
+        var advancement = player.getServer().getAdvancements().get(id("progression/" + path));
+        return player.getAdvancements().getOrStartProgress(advancement).isDone();
+    }
+
+    private static ResourceLocation id(String path) {
+        return ResourceLocation.fromNamespaceAndPath(Rivencraft.MOD_ID, path);
+    }
+}
@@ -0,0 +1,105 @@
+package net.dnorberg.rivencraft.gametest;
+
+import java.util.ArrayList;
+import java.util.List;
+import net.dnorberg.rivencraft.Rivencraft;
+import net.dnorberg.rivencraft.item.PageItem;
+import net.dnorberg.rivencraft.registry.ModItems;
+import net.minecraft.gametest.framework.GameTest;
+import net.minecraft.gametest.framework.GameTestHelper;
+import net.minecraft.resources.ResourceLocation;
+import net.minecraft.world.item.ItemStack;
+import net.minecraft.world.item.Items;
+import net.minecraft.world.item.crafting.CraftingInput;
+import net.minecraft.world.item.crafting.RecipeType;
+import net.neoforged.neoforge.gametest.GameTestHolder;
+import net.neoforged.neoforge.gametest.PrefixGameTestTemplate;
+
+/** Data-driven Milestone 7 crafting checks; every result is obtained from the loaded recipe manager. */
+@GameTestHolder(Rivencraft.MOD_ID)
+@PrefixGameTestTemplate(false)
+public final class Milestone7CraftingGameTests {
+    private Milestone7CraftingGameTests() {}
+
+    @GameTest(template = "empty")
+    public static void crystalProgressionMatchesLegacyCounts(GameTestHelper helper) {
+        var level = helper.getLevel();
+        ItemStack shard = new ItemStack(ModItems.CRYSTAL_SHARD.get());
+        CraftingInput crystalInput = CraftingInput.of(2, 2, List.of(shard, shard, shard, shard));
+        var crystalRecipe = level.getRecipeManager().getRecipeFor(RecipeType.CRAFTING, crystalInput, level)
+                .orElseThrow();
+        helper.assertValueEqual(crystalRecipe.id(), id("crystal_block"),
+                "Four shards must craft a Crystal Block");
+        ItemStack crystal = crystalRecipe.value().assemble(crystalInput, level.registryAccess());
+        helper.assertTrue(crystal.is(ModItems.CRYSTAL_BLOCK.get()) && crystal.getCount() == 1,
+                "The shard recipe must yield one Crystal Block");
+
+        List<ItemStack> ring = new ArrayList<>();
+        for (int slot = 0; slot < 9; slot++) ring.add(slot == 4 ? ItemStack.EMPTY : crystal.copy());
+        CraftingInput receptacleInput = CraftingInput.of(3, 3, ring);
+        var receptacleRecipe = level.getRecipeManager()
+                .getRecipeFor(RecipeType.CRAFTING, receptacleInput, level).orElseThrow();
+        helper.assertValueEqual(receptacleRecipe.id(), id("book_receptacle"),
+                "The Legacy eight-block ring must craft the Receptacle");
+        ItemStack result = receptacleRecipe.value().assemble(receptacleInput, level.registryAccess());
+        helper.assertTrue(result.is(ModItems.BOOK_RECEPTACLE.get()) && result.getCount() == 1,
+                "One ring must yield exactly one Book Receptacle");
+        helper.assertTrue(receptacleRecipe.value().getRemainingItems(receptacleInput).stream()
+                .allMatch(ItemStack::isEmpty), "Crystal crafting must not duplicate source blocks as remainders");
+        ring.set(4, crystal.copy());
+        helper.assertTrue(level.getRecipeManager().getRecipeFor(RecipeType.CRAFTING,
+                CraftingInput.of(3, 3, ring), level).isEmpty(),
+                "A filled center must not match the Book Receptacle ring");
+        helper.succeed();
+    }
+
+    @GameTest(template = "empty")
+    public static void bucketInkReturnsItsContainer(GameTestHelper helper) {
+        var level = helper.getLevel();
+        ItemStack dye = new ItemStack(Items.BLACK_DYE);
+        CraftingInput bucketInput = CraftingInput.of(2, 2, List.of(
+                dye, dye, new ItemStack(Items.GLASS_BOTTLE), new ItemStack(Items.WATER_BUCKET)));
+        var bucketRecipe = level.getRecipeManager().getRecipeFor(RecipeType.CRAFTING, bucketInput, level)
+                .orElseThrow();
+        helper.assertValueEqual(bucketRecipe.id(), id("ink_vial"), "Bucket ink recipe must remain registered");
+        helper.assertTrue(bucketRecipe.value().assemble(bucketInput, level.registryAccess())
+                .is(ModItems.INK_VIAL.get()), "Bucket recipe must yield an Ink Vial");
+        helper.assertTrue(bucketRecipe.value().getRemainingItems(bucketInput).stream()
+                .anyMatch(stack -> stack.is(Items.BUCKET)), "The water bucket must return an empty bucket");
+
+        helper.succeed();
+    }
+
+    @GameTest(template = "empty")
+    public static void recipeUnlocksAreLoadedAndBlankPagesStayUncraftable(GameTestHelper helper) {
+        var level = helper.getLevel();
+        for (String path : List.of("crystal_block", "book_receptacle", "ink_vial")) {
+            helper.assertTrue(level.getServer().getAdvancements().get(id("recipes/misc/" + path)) != null,
+                    "Recipe unlock must load for " + path);
+        }
+        var player = helper.makeMockServerPlayerInLevel();
+        var shardUnlock = level.getServer().getAdvancements().get(id("recipes/misc/crystal_block"));
+        player.getAdvancements().award(shardUnlock, "has_crystal_shard");
+        helper.assertTrue(player.getRecipeBook().contains(id("crystal_block")),
+                "Discovering a shard must unlock the Crystal Block recipe");
+        var receptacleUnlock = level.getServer().getAdvancements().get(id("recipes/misc/book_receptacle"));
+        player.getAdvancements().award(receptacleUnlock, "has_crystal_block");
+        helper.assertTrue(player.getRecipeBook().contains(id("book_receptacle")),
+                "Discovering a Crystal Block must unlock the Receptacle recipe");
+        CraftingInput blankInput = CraftingInput.of(2, 2, List.of(
+                new ItemStack(Items.PAPER), new ItemStack(ModItems.INK_VIAL.get()),
+                ItemStack.EMPTY, ItemStack.EMPTY));
+        helper.assertTrue(level.getRecipeManager().getRecipeFor(RecipeType.CRAFTING, blankInput, level).isEmpty(),
+                "Blank Pages and Link Panels must not become grid-craftable");
+        ItemStack panel = PageItem.createLinkPanelPage();
+        CraftingInput linkInput = CraftingInput.of(2, 1, List.of(panel, new ItemStack(Items.LEATHER)));
+        helper.assertValueEqual(level.getRecipeManager().getRecipeFor(RecipeType.CRAFTING, linkInput, level)
+                .orElseThrow().id(), id("linking_book"),
+                "Link Panel crafting remains limited to the established Linking Book recipe");
+        helper.succeed();
+    }
+
+    private static ResourceLocation id(String path) {
+        return ResourceLocation.fromNamespaceAndPath(Rivencraft.MOD_ID, path);
+    }
+}
@@ -0,0 +1,31 @@
+package net.dnorberg.rivencraft.gametest;
+
+import net.dnorberg.rivencraft.Rivencraft;
+import net.dnorberg.rivencraft.book.LinkProperties;
+import net.dnorberg.rivencraft.book.LinkVisualEffects;
+import net.dnorberg.rivencraft.registry.ModSounds;
+import net.minecraft.gametest.framework.GameTest;
+import net.minecraft.gametest.framework.GameTestHelper;
+import net.neoforged.neoforge.gametest.GameTestHolder;
+import net.neoforged.neoforge.gametest.PrefixGameTestTemplate;
+
+@GameTestHolder(Rivencraft.MOD_ID)
+@PrefixGameTestTemplate(false)
+public final class Milestone7PolishGameTests {
+    private Milestone7PolishGameTests() {}
+
+    @GameTest(template = "empty")
+    public static void linkSoundPriorityMatchesLegacy(GameTestHelper helper) {
+        helper.assertTrue(LinkVisualEffects.sound(LinkProperties.NONE, false) == ModSounds.LINK.get(),
+                "Ordinary book travel uses the Legacy link sound");
+        helper.assertTrue(LinkVisualEffects.sound(new LinkProperties(LinkProperties.INTRA_LINKING), false)
+                        == ModSounds.LINK_INTRA.get(),
+                "Intra Linking uses its Legacy sound");
+        helper.assertTrue(LinkVisualEffects.sound(LinkProperties.NONE, true) == ModSounds.LINK_PORTAL.get(),
+                "Portal travel uses its Legacy sound");
+        helper.assertTrue(LinkVisualEffects.sound(new LinkProperties(LinkProperties.DISARM), true)
+                        == ModSounds.LINK_DISARM.get(),
+                "Legacy Disarm takes precedence over the portal sound");
+        helper.succeed();
+    }
+}
@@ -1,26 +1,28 @@
 package net.dnorberg.rivencraft.item;

+import net.dnorberg.rivencraft.advancement.ProgressionAdvancements;
 import java.util.List;
 import net.dnorberg.rivencraft.book.AgeReference;
 import net.dnorberg.rivencraft.book.AgeVisitSavedData;
 import net.dnorberg.rivencraft.book.LinkTarget;
 import net.dnorberg.rivencraft.book.LinkProperties;
 import net.dnorberg.rivencraft.book.LinkingService;
+import net.dnorberg.rivencraft.book.LinkVisualEffects;
 import net.dnorberg.rivencraft.book.AgeDimensionService;
 import net.dnorberg.rivencraft.config.RivencraftConfig;
 import net.dnorberg.rivencraft.registry.ModDataComponents;
 import net.dnorberg.rivencraft.registry.ModItems;
-import net.dnorberg.rivencraft.registry.ModSounds;
 import net.minecraft.ChatFormatting;
 import net.minecraft.core.component.DataComponents;
 import net.minecraft.network.chat.Component;
 import net.minecraft.network.chat.MutableComponent;
 import net.minecraft.server.level.ServerPlayer;
-import net.minecraft.sounds.SoundSource;
 import net.minecraft.server.level.ServerLevel;
+import net.minecraft.world.InteractionHand;
 import net.minecraft.world.item.Item;
 import net.minecraft.world.item.ItemStack;
 import net.minecraft.world.item.TooltipFlag;
+import net.minecraft.world.phys.Vec3;

 /**
 * A book that will eventually describe and link to a generated Age.
@@ -40,14 +42,18 @@ public final class DescriptiveBookItem extends Item {
    }

    public static boolean useWrittenBook(ServerPlayer player, ItemStack stack) {
-        return useWrittenBook(player, stack, false);
+        return useWrittenBook(player, stack, false, null);
+    }
+
+    public static boolean useHandheldBook(ServerPlayer player, InteractionHand hand) {
+        return useWrittenBook(player, player.getItemInHand(hand), false, hand);
    }

    public static boolean usePortalBook(ServerPlayer player, ItemStack stack) {
-        return useWrittenBook(player, stack, true);
+        return useWrittenBook(player, stack, true, null);
    }

-    private static boolean useWrittenBook(ServerPlayer player, ItemStack stack, boolean portal) {
+    private static boolean useWrittenBook(ServerPlayer player, ItemStack stack, boolean portal, InteractionHand hand) {
        AgeReference age = stack.get(ModDataComponents.AGE_REFERENCE.get());
        if (age == null) {
            player.displayClientMessage(Component.translatable("message.rivencraft.descriptive_book.unwritten"), true);
@@ -62,12 +68,13 @@ public final class DescriptiveBookItem extends Item {
        }

        ServerLevel sourceLevel = player.serverLevel();
-        var sourcePosition = player.blockPosition();
+        Vec3 sourcePosition = player.position();
        LinkProperties properties = stack.getOrDefault(ModDataComponents.LINK_PROPERTIES.get(), LinkProperties.NONE)
                .forDescriptiveBook();
        LinkingService.LinkResult result = portal
                ? LinkingService.travelDescriptivePortal(player, ageTarget, properties)
-                : LinkingService.travelWithFooting(player, ageTarget, properties);
+                : hand == null ? LinkingService.travelWithFooting(player, ageTarget, properties)
+                : LinkingService.travelHandheld(player, hand, stack, ageTarget, properties, true);
        if (result != LinkingService.LinkResult.SUCCESS) {
            player.displayClientMessage(Component.translatable("message.rivencraft.descriptive_book.unsafe"), true);
            return false;
@@ -85,10 +92,8 @@ public final class DescriptiveBookItem extends Item {
                player.drop(returnBook, false);
            }
        }
-        sourceLevel.playSound(null, sourcePosition, (portal ? ModSounds.LINK_PORTAL : ModSounds.LINK).get(), SoundSource.PLAYERS,
-                0.8F, sourceLevel.random.nextFloat() * 0.2F + 0.9F);
-        player.level().playSound(null, player.blockPosition(), (portal ? ModSounds.LINK_PORTAL : ModSounds.LINK).get(), SoundSource.PLAYERS,
-                0.8F, player.level().random.nextFloat() * 0.2F + 0.9F);
+        LinkVisualEffects.play(sourceLevel, sourcePosition, player, properties, portal);
+        ProgressionAdvancements.awardAgeTravel(player);
        player.displayClientMessage(Component.translatable(
                createReturnLink ? "message.rivencraft.descriptive_book.linked_first" : "message.rivencraft.descriptive_book.linked",
                age.name()
@@ -1,19 +1,19 @@
 package net.dnorberg.rivencraft.item;

+import net.dnorberg.rivencraft.advancement.ProgressionAdvancements;
 import java.util.List;
 import net.dnorberg.rivencraft.book.LinkTarget;
 import net.dnorberg.rivencraft.book.AgeRegistrySavedData;
 import net.dnorberg.rivencraft.book.LinkingService;
+import net.dnorberg.rivencraft.book.LinkVisualEffects;
 import net.dnorberg.rivencraft.book.LinkProperties;
 import net.dnorberg.rivencraft.registry.ModDataComponents;
-import net.dnorberg.rivencraft.registry.ModSounds;
 import net.minecraft.ChatFormatting;
 import net.minecraft.core.BlockPos;
 import net.minecraft.network.chat.Component;
 import net.minecraft.resources.ResourceLocation;
 import net.minecraft.server.level.ServerPlayer;
 import net.minecraft.server.level.ServerLevel;
-import net.minecraft.sounds.SoundSource;
 import net.minecraft.world.InteractionHand;
 import net.minecraft.world.InteractionResultHolder;
 import net.minecraft.world.entity.player.Player;
@@ -21,6 +21,7 @@ import net.minecraft.world.item.Item;
 import net.minecraft.world.item.ItemStack;
 import net.minecraft.world.item.TooltipFlag;
 import net.minecraft.world.level.Level;
+import net.minecraft.world.phys.Vec3;

 public final class LinkingBookItem extends Item {
    public LinkingBookItem(Properties properties) {
@@ -42,35 +43,35 @@ public final class LinkingBookItem extends Item {
    }

    public static InteractionResultHolder<ItemStack> useBoundBook(ServerPlayer player, ItemStack stack) {
-        return useBoundBook(player, stack, false);
+        return useBoundBook(player, stack, false, null);
+    }
+
+    public static InteractionResultHolder<ItemStack> useHandheldBook(ServerPlayer player, InteractionHand hand) {
+        return useBoundBook(player, player.getItemInHand(hand), false, hand);
    }

    public static InteractionResultHolder<ItemStack> usePortalBook(ServerPlayer player, ItemStack stack) {
-        return useBoundBook(player, stack, true);
+        return useBoundBook(player, stack, true, null);
    }

-    private static InteractionResultHolder<ItemStack> useBoundBook(ServerPlayer player, ItemStack stack, boolean portal) {
+    private static InteractionResultHolder<ItemStack> useBoundBook(ServerPlayer player, ItemStack stack, boolean portal,
+                                                                   InteractionHand hand) {
        LinkTarget target = stack.get(ModDataComponents.LINK_TARGET.get());
        if (target == null) {
            player.displayClientMessage(Component.translatable("message.rivencraft.linking_book.unbound"), true);
            return InteractionResultHolder.fail(stack);
        }

-        Level sourceLevel = player.level();
-        BlockPos sourcePosition = player.blockPosition();
+        ServerLevel sourceLevel = player.serverLevel();
+        Vec3 sourcePosition = player.position();
        LinkProperties properties = stack.getOrDefault(ModDataComponents.LINK_PROPERTIES.get(), LinkProperties.NONE);
-        LinkingService.LinkResult result = LinkingService.travel(player, target, properties);
+        LinkingService.LinkResult result = portal
+                ? LinkingService.travelPortal(player, target, properties)
+                : hand == null ? LinkingService.travel(player, target, properties)
+                : LinkingService.travelHandheld(player, hand, stack, target, properties, false);
        if (result == LinkingService.LinkResult.SUCCESS) {
-            sourceLevel.playSound(null, sourcePosition, (portal ? ModSounds.LINK_PORTAL : ModSounds.LINK).get(), SoundSource.PLAYERS,
-                    0.8F, sourceLevel.random.nextFloat() * 0.2F + 0.9F);
-            player.level().playSound(
-                    null,
-                    player.blockPosition(),
-                    (portal ? ModSounds.LINK_PORTAL : ModSounds.LINK).get(),
-                    SoundSource.PLAYERS,
-                    0.8F,
-                    player.level().random.nextFloat() * 0.2F + 0.9F
-            );
+            LinkVisualEffects.play(sourceLevel, sourcePosition, player, properties, portal);
+            ProgressionAdvancements.awardAgeTravel(player);
            player.displayClientMessage(Component.translatable("message.rivencraft.linking_book.linked"), true);
            return InteractionResultHolder.success(stack);
        }
@@ -1,5 +1,6 @@
 package net.dnorberg.rivencraft.menu;

+import net.dnorberg.rivencraft.advancement.ProgressionAdvancements;
 import java.util.Optional;
 import net.dnorberg.rivencraft.block.entity.BookBinderBlockEntity;
 import net.dnorberg.rivencraft.item.PageItem;
@@ -9,6 +10,7 @@ import net.dnorberg.rivencraft.registry.ModMenus;
 import net.dnorberg.rivencraft.writing.PageContent;
 import net.dnorberg.rivencraft.writing.WritingGrammar;
 import net.minecraft.network.RegistryFriendlyByteBuf;
+import net.minecraft.server.level.ServerPlayer;
 import net.minecraft.world.Container;
 import net.minecraft.world.SimpleContainer;
 import net.minecraft.world.entity.player.Inventory;
@@ -210,7 +212,9 @@ public final class BookBinderMenu extends AbstractContainerMenu {
            if (!moveItemStackTo(remainder, PLAYER_START, slots.size(), true) || !remainder.isEmpty()) {
                return ItemStack.EMPTY;
            }
-            binder.consumeAssembly();
+            if (!binder.consumeAssembly()) return ItemStack.EMPTY;
+            if (player instanceof ServerPlayer serverPlayer)
+                ProgressionAdvancements.award(serverPlayer, ProgressionAdvancements.BIND_AGE);
            refreshResult();
            return book;
        }
@@ -284,7 +288,11 @@ public final class BookBinderMenu extends AbstractContainerMenu {
            return clientSide ? hasItem() : stillValid(player) && binder.canAssemble();
        }
        @Override public void onTake(Player player, ItemStack stack) {
-            if (!clientSide && binder.consumeAssembly()) refreshResult();
+            if (!clientSide && binder.consumeAssembly()) {
+                if (player instanceof ServerPlayer serverPlayer)
+                    ProgressionAdvancements.award(serverPlayer, ProgressionAdvancements.BIND_AGE);
+                refreshResult();
+            }
            super.onTake(player, stack);
        }
    }
@@ -1,10 +1,12 @@
 package net.dnorberg.rivencraft.menu;

+import net.dnorberg.rivencraft.advancement.ProgressionAdvancements;
 import net.dnorberg.rivencraft.block.entity.InkMixerBlockEntity;
 import net.dnorberg.rivencraft.item.PageItem;
 import net.dnorberg.rivencraft.registry.ModItems;
 import net.dnorberg.rivencraft.registry.ModMenus;
 import net.minecraft.network.RegistryFriendlyByteBuf;
+import net.minecraft.server.level.ServerPlayer;
 import net.minecraft.world.Container;
 import net.minecraft.world.SimpleContainer;
 import net.minecraft.world.entity.player.Inventory;
@@ -109,6 +111,8 @@ public final class InkMixerMenu extends AbstractContainerMenu {
            if (!moveItemStackTo(remainder, PLAYER_START, slots.size(), true) || !remainder.isEmpty())
                return ItemStack.EMPTY;
            if (!mixer.consumeLinkPanelMaterials()) return ItemStack.EMPTY;
+            if (player instanceof ServerPlayer serverPlayer)
+                ProgressionAdvancements.award(serverPlayer, ProgressionAdvancements.LINK_PANEL);
            refreshResult();
            return output;
        }
@@ -148,7 +152,11 @@ public final class InkMixerMenu extends AbstractContainerMenu {
            return clientSide ? hasItem() : stillValid(player) && mixer.canCreateLinkPanel();
        }
        @Override public void onTake(Player player, ItemStack stack) {
-            if (!clientSide && mixer.consumeLinkPanelMaterials()) refreshResult();
+            if (!clientSide && mixer.consumeLinkPanelMaterials()) {
+                if (player instanceof ServerPlayer serverPlayer)
+                    ProgressionAdvancements.award(serverPlayer, ProgressionAdvancements.LINK_PANEL);
+                refreshResult();
+            }
            super.onTake(player, stack);
        }
    }
@@ -1,5 +1,6 @@
 package net.dnorberg.rivencraft.menu;

+import net.dnorberg.rivencraft.advancement.ProgressionAdvancements;
 import net.dnorberg.rivencraft.block.entity.WritingDeskBlockEntity;
 import net.dnorberg.rivencraft.item.PageItem;
 import net.dnorberg.rivencraft.registry.ModDataComponents;
@@ -317,7 +318,9 @@ public final class WritingDeskMenu extends AbstractContainerMenu {
            if (!moveItemStackTo(movingCopy, PLAYER_START, slots.size(), true) || !movingCopy.isEmpty()) {
                return ItemStack.EMPTY;
            }
-            blockEntity.consumeCopyMaterials();
+            if (!blockEntity.consumeCopyMaterials()) return ItemStack.EMPTY;
+            if (player instanceof ServerPlayer serverPlayer)
+                ProgressionAdvancements.award(serverPlayer, ProgressionAdvancements.COPY_PAGE);
            refreshOutput();
            return copy;
        }
@@ -434,7 +437,11 @@ public final class WritingDeskMenu extends AbstractContainerMenu {
            return clientSide ? hasItem() : WritingDeskMenu.this.stillValid(player) && canCopy();
        }
        @Override public void onTake(Player player, ItemStack stack) {
-            if (!clientSide && blockEntity.consumeCopyMaterials()) refreshOutput();
+            if (!clientSide && blockEntity.consumeCopyMaterials()) {
+                if (player instanceof ServerPlayer serverPlayer)
+                    ProgressionAdvancements.award(serverPlayer, ProgressionAdvancements.COPY_PAGE);
+                refreshOutput();
+            }
            super.onTake(player, stack);
        }
    }
@@ -211,7 +211,7 @@ public final class ModNetworking {

        ItemStack stack = player.getItemInHand(hand(payload.offhand()));
        if (stack.is(ModItems.LINKING_BOOK.get()) && stack.has(ModDataComponents.LINK_TARGET.get())) {
-            LinkingBookItem.useBoundBook(player, stack);
+            LinkingBookItem.useHandheldBook(player, hand(payload.offhand()));
        }
    }

@@ -245,7 +245,8 @@ public final class ModNetworking {
        }

        if (stack.is(ModItems.DESCRIPTIVE_BOOK.get())) {
-            DescriptiveBookItem.useWrittenBook(player, stack);
+            if (payload.fromStand()) DescriptiveBookItem.useWrittenBook(player, stack);
+            else DescriptiveBookItem.useHandheldBook(player, hand(payload.offhand()));
        }
    }

@@ -7,14 +7,19 @@ import java.util.LinkedHashSet;
 import java.util.List;
 import java.util.Set;
 import net.dnorberg.rivencraft.block.BookReceptacleBlock;
+import net.dnorberg.rivencraft.block.CrystalPortalBlock;
 import net.dnorberg.rivencraft.block.entity.BookReceptacleBlockEntity;
 import net.dnorberg.rivencraft.block.entity.CrystalPortalBlockEntity;
 import net.dnorberg.rivencraft.registry.ModBlocks;
 import net.minecraft.core.BlockPos;
 import net.minecraft.core.Direction;
 import net.minecraft.server.level.ServerLevel;
+import net.minecraft.world.entity.Entity;
 import net.minecraft.world.level.block.Blocks;
 import net.minecraft.world.level.block.state.BlockState;
+import net.neoforged.neoforge.common.NeoForge;
+import net.neoforged.neoforge.common.util.BlockSnapshot;
+import net.neoforged.neoforge.event.level.BlockEvent;

 /** Bounded, loaded-chunk-only adaptation of Legacy's crystal network flood. */
 public final class CrystalPortalNetwork {
@@ -31,14 +36,22 @@ public final class CrystalPortalNetwork {

    private CrystalPortalNetwork() {}

-    public record Plan(List<BlockPos> portalCells) {
+    public record Plan(List<BlockPos> portalCells, boolean waitingForChunks) {
+        public Plan(List<BlockPos> portalCells) { this(portalCells, false); }
        public boolean valid() { return !portalCells.isEmpty(); }
    }

+    public enum CellStatus { VALID, INVALID, WAITING_FOR_CHUNKS }
+
    public static Plan plan(ServerLevel level, BlockPos receptacle) {
+        return plan(level, receptacle, false);
+    }
+
+    private static Plan plan(ServerLevel level, BlockPos receptacle, boolean allowUnownedCells) {
        BlockState holder = level.getBlockState(receptacle);
        if (!holder.is(ModBlocks.BOOK_RECEPTACLE.get())) return new Plan(List.of());
        BlockPos base = receptacle.relative(holder.getValue(BookReceptacleBlock.FACING).getOpposite());
+        if (!level.hasChunkAt(base)) return new Plan(List.of(), true);
        if (!level.getBlockState(base).is(ModBlocks.CRYSTAL_BLOCK.get())) return new Plan(List.of());

        Set<BlockPos> crystals = new HashSet<>();
@@ -47,7 +60,7 @@ public final class CrystalPortalNetwork {
        while (!pendingCrystals.isEmpty()) {
            BlockPos pos = pendingCrystals.removeFirst();
            if (!within(base, pos) || !level.isInWorldBounds(pos)) continue;
-            if (!level.hasChunkAt(pos)) return new Plan(List.of());
+            if (!level.hasChunkAt(pos)) return new Plan(List.of(), true);
            if (!level.getBlockState(pos).is(ModBlocks.CRYSTAL_BLOCK.get()) || !crystals.add(pos)) continue;
            if (atBoundary(base, pos)) return new Plan(List.of());
            if (crystals.size() > MAX_CRYSTALS) return new Plan(List.of());
@@ -61,8 +74,9 @@ public final class CrystalPortalNetwork {
        while (!candidates.isEmpty()) {
            BlockPos pos = candidates.removeFirst();
            queued.remove(pos);
-            if (!level.isInWorldBounds(pos) || !level.hasChunkAt(pos)) return new Plan(List.of());
-            if (portals.contains(pos) || !mayFill(level, pos, receptacle)) continue;
+            if (!level.isInWorldBounds(pos)) return new Plan(List.of());
+            if (!level.hasChunkAt(pos)) return new Plan(List.of(), true);
+            if (portals.contains(pos) || !mayFill(level, pos, receptacle, allowUnownedCells)) continue;
            if (adjacentCount(pos, crystals, portals) < 2) continue;
            portals.add(pos);
            if (portals.size() > MAX_PORTALS) return new Plan(List.of());
@@ -96,6 +110,28 @@ public final class CrystalPortalNetwork {
    }

    public static boolean activate(ServerLevel level, BlockPos receptacle, Plan plan) {
+        return activate(level, receptacle, plan, null);
+    }
+
+    /** Repairs only existing, framed cells whose owner pointer was lost by an older live-view update. */
+    public static boolean recoverSavedOwners(ServerLevel level, BlockPos receptacle) {
+        if (!(level.getBlockEntity(receptacle) instanceof BookReceptacleBlockEntity holder)
+                || holder.getBook().isEmpty()) return false;
+        Plan plan = plan(level, receptacle, true);
+        if (!plan.valid()) return false;
+        for (BlockPos pos : plan.portalCells()) {
+            if (!(level.getBlockEntity(pos) instanceof CrystalPortalBlockEntity portal)
+                    || portal.receptacle() != null && !receptacle.equals(portal.receptacle())) return false;
+        }
+        for (BlockPos pos : plan.portalCells()) {
+            CrystalPortalBlockEntity portal = (CrystalPortalBlockEntity) level.getBlockEntity(pos);
+            if (portal.receptacle() == null) portal.setReceptacle(receptacle);
+        }
+        return true;
+    }
+
+    /** The player who inserted the book owns each newly placed portal cell for claim checks. */
+    public static boolean activate(ServerLevel level, BlockPos receptacle, Plan plan, Entity actor) {
        if (!plan.valid() || !(level.getBlockEntity(receptacle) instanceof BookReceptacleBlockEntity holder)
                || holder.getBook().isEmpty()) return false;
        List<BlockPos> placed = new ArrayList<>();
@@ -105,20 +141,41 @@ public final class CrystalPortalNetwork {
                return false;
            }
            if (level.getBlockState(pos).isAir()) {
-                if (!level.setBlock(pos, ModBlocks.CRYSTAL_PORTAL.get().defaultBlockState(), 3)) {
+                BlockSnapshot snapshot = actor == null ? null : BlockSnapshot.create(level.dimension(), level, pos);
+                BlockState prior = level.getBlockState(pos);
+                // Defer neighbor notifications until the entire opening exists.
+                // Otherwise the first cells see an incomplete brace and the
+                // portal's neighbor validator removes them during activation.
+                if (!level.setBlock(pos, ModBlocks.CRYSTAL_PORTAL.get().defaultBlockState(), 2)) {
                    rollback(level, placed);
                    return false;
                }
+                if (snapshot != null) {
+                    var event = new BlockEvent.EntityPlaceEvent(snapshot, prior, actor);
+                    NeoForge.EVENT_BUS.post(event);
+                    if (event.isCanceled()) {
+                        snapshot.restore();
+                        rollback(level, placed);
+                        return false;
+                    }
+                }
                placed.add(pos);
            }
            if (level.getBlockEntity(pos) instanceof CrystalPortalBlockEntity portal) {
                portal.setReceptacle(receptacle);
-                level.scheduleTick(pos, ModBlocks.CRYSTAL_PORTAL.get(), 40);
            } else {
                rollback(level, placed);
                return false;
            }
        }
+        orientSurfaces(level, plan);
+        for (BlockPos pos : plan.portalCells()) {
+            if (!(level.getBlockEntity(pos) instanceof CrystalPortalBlockEntity portal)
+                    || !receptacle.equals(portal.receptacle())) {
+                rollback(level, placed);
+                return false;
+            }
+        }
        return true;
    }

@@ -137,13 +194,24 @@ public final class CrystalPortalNetwork {
    }

    /** One bounded repair pass per receptacle, rather than a full flood per portal cell. */
-    public static void reconcile(ServerLevel level, BlockPos receptacle) {
+    public static boolean reconcile(ServerLevel level, BlockPos receptacle) {
        Plan plan = plan(level, receptacle);
        if (!plan.valid()) {
-            shutdown(level, receptacle);
-            return;
+            // Neighboring chunks can still be loading when the receptacle first
+            // ticks after a restart. An incomplete view is not a broken frame.
+            if (!plan.waitingForChunks()) shutdown(level, receptacle);
+            return false;
        }
        Set<BlockPos> wanted = new HashSet<>(plan.portalCells());
+        // A background pass must not create blocks without the owner present:
+        // that would bypass the placement/protection event used at activation.
+        for (BlockPos pos : wanted) {
+            if (!(level.getBlockEntity(pos) instanceof CrystalPortalBlockEntity portal)
+                    || !receptacle.equals(portal.receptacle())) {
+                shutdown(level, receptacle);
+                return false;
+            }
+        }
        for (BlockPos pos : BlockPos.betweenClosed(receptacle.offset(-CLEANUP_RADIUS, -CLEANUP_RADIUS, -CLEANUP_RADIUS),
                receptacle.offset(CLEANUP_RADIUS, CLEANUP_RADIUS, CLEANUP_RADIUS))) {
            if (!level.hasChunkAt(pos)) continue;
@@ -151,29 +219,64 @@ public final class CrystalPortalNetwork {
                    && receptacle.equals(portal.receptacle()) && !wanted.contains(pos))
                level.setBlock(pos, Blocks.AIR.defaultBlockState(), 3);
        }
-        activate(level, receptacle, plan);
+        orientSurfaces(level, plan);
+        return true;
    }

-    public static boolean validCell(ServerLevel level, BlockPos pos, BlockPos receptacle) {
+    private static void orientSurfaces(ServerLevel level, Plan plan) {
+        for (CrystalPortalSurfaces.Surface surface : CrystalPortalSurfaces.group(level, plan)) {
+            for (BlockPos pos : surface.cells()) {
+                BlockState state = level.getBlockState(pos);
+                Direction.Axis axis = surface.normal().getAxis();
+                if (state.getValue(CrystalPortalBlock.AXIS) != axis)
+                    updatePortalState(level, pos, state.setValue(CrystalPortalBlock.AXIS, axis));
+            }
+        }
+    }
+
+    /** The vanilla-style surface remains visible until its optional live view is ready. */
+    public static void setLiveView(ServerLevel level, Plan plan, boolean live) {
+        for (BlockPos pos : plan.portalCells()) {
+            BlockState state = level.getBlockState(pos);
+            if (state.is(ModBlocks.CRYSTAL_PORTAL.get()) && state.getValue(CrystalPortalBlock.LIVE_VIEW) != live)
+                updatePortalState(level, pos, state.setValue(CrystalPortalBlock.LIVE_VIEW, live));
+        }
+    }
+
+    private static void updatePortalState(ServerLevel level, BlockPos pos, BlockState replacement) {
+        BlockPos owner = level.getBlockEntity(pos) instanceof CrystalPortalBlockEntity portal
+                ? portal.receptacle() : null;
+        if (!level.setBlock(pos, replacement, 2) || owner == null) return;
+        if (level.getBlockEntity(pos) instanceof CrystalPortalBlockEntity portal
+                && !owner.equals(portal.receptacle())) portal.setReceptacle(owner);
+    }
+
+    public static CellStatus cellStatus(ServerLevel level, BlockPos pos, BlockPos receptacle) {
        if (Math.abs(receptacle.getX() - pos.getX()) > CLEANUP_RADIUS
                || Math.abs(receptacle.getY() - pos.getY()) > CLEANUP_RADIUS
-                || Math.abs(receptacle.getZ() - pos.getZ()) > CLEANUP_RADIUS
-                || !level.hasChunkAt(receptacle)
-                || !(level.getBlockEntity(receptacle) instanceof BookReceptacleBlockEntity holder)
-                || holder.getBook().isEmpty()) return false;
+                || Math.abs(receptacle.getZ() - pos.getZ()) > CLEANUP_RADIUS) return CellStatus.INVALID;
+        if (!level.hasChunkAt(receptacle)) return CellStatus.WAITING_FOR_CHUNKS;
        BlockState state = level.getBlockState(receptacle);
-        if (!state.is(ModBlocks.BOOK_RECEPTACLE.get()) || !level.getBlockState(receptacle.relative(
-                state.getValue(BookReceptacleBlock.FACING).getOpposite())).is(ModBlocks.CRYSTAL_BLOCK.get()))
-            return false;
+        if (!state.is(ModBlocks.BOOK_RECEPTACLE.get())) return CellStatus.INVALID;
+        BlockPos base = receptacle.relative(state.getValue(BookReceptacleBlock.FACING).getOpposite());
+        if (!level.hasChunkAt(base)) return CellStatus.WAITING_FOR_CHUNKS;
+        if (!level.getBlockState(base).is(ModBlocks.CRYSTAL_BLOCK.get())) return CellStatus.INVALID;
+        if (!(level.getBlockEntity(receptacle) instanceof BookReceptacleBlockEntity holder))
+            return CellStatus.WAITING_FOR_CHUNKS;
+        if (holder.getBook().isEmpty()) return CellStatus.INVALID;
+        // A neighboring chunk may hold one of the braces. Do not tear down a
+        // persisted portal until all six neighbors are available to inspect.
+        for (Direction direction : Direction.values())
+            if (!level.hasChunkAt(pos.relative(direction))) return CellStatus.WAITING_FOR_CHUNKS;
        for (Direction.Axis axis : Direction.Axis.values()) {
            // Quick tension check before the bounded network/path revalidation.
            if (!axisBraced(level, pos, axis)) continue;
            int other = 0;
            for (Direction.Axis alternative : Direction.Axis.values())
                if (alternative != axis && axisBraced(level, pos, alternative)) other++;
-            if (other > 0) return true;
+            if (other > 0) return CellStatus.VALID;
        }
-        return false;
+        return CellStatus.INVALID;
    }

    private static boolean axisBraced(ServerLevel level, BlockPos pos, Direction.Axis axis) {
@@ -194,11 +297,15 @@ public final class CrystalPortalNetwork {
    }

    private static boolean mayFill(ServerLevel level, BlockPos pos, BlockPos receptacle) {
+        return mayFill(level, pos, receptacle, false);
+    }
+
+    private static boolean mayFill(ServerLevel level, BlockPos pos, BlockPos receptacle, boolean allowUnowned) {
        if (!level.hasChunkAt(pos) || !level.isInWorldBounds(pos)) return false;
        BlockState state = level.getBlockState(pos);
        return state.isAir() || state.is(ModBlocks.CRYSTAL_PORTAL.get())
                && level.getBlockEntity(pos) instanceof CrystalPortalBlockEntity portal
-                && receptacle.equals(portal.receptacle());
+                && (receptacle.equals(portal.receptacle()) || allowUnowned && portal.receptacle() == null);
    }

    private static int adjacentCount(BlockPos pos, Set<BlockPos> crystals, Set<BlockPos> portals) {
@@ -1,12 +1,33 @@
 package net.dnorberg.rivencraft.portal;

-/** Server tick counters restart with the process; old saved values cannot block new sessions. */
+import java.util.Map;
+import java.util.WeakHashMap;
+import net.minecraft.server.level.ServerPlayer;
+
+/** Session-only portal cooldowns: tick counters must never be saved with players. */
 public final class PortalTravelCooldown {
    public static final long TICKS = 40;
+    private static final Map<ServerPlayer, Long> LAST_USE = new WeakHashMap<>();

    private PortalTravelCooldown() {}

    public static boolean blocked(long now, long previous) {
        return previous >= 0 && now >= previous && now - previous < TICKS;
    }
+
+    public static boolean blocked(ServerPlayer player, long now) {
+        return blocked(now, LAST_USE.getOrDefault(player, -1L));
+    }
+
+    public static void mark(ServerPlayer player, long now) {
+        LAST_USE.put(player, now);
+    }
+
+    public static void forget(ServerPlayer player) {
+        LAST_USE.remove(player);
+    }
+
+    public static void clear() {
+        LAST_USE.clear();
+    }
 }
@@ -0,0 +1,64 @@
+package net.dnorberg.rivencraft.portal;
+
+import java.util.ArrayList;
+import java.util.IdentityHashMap;
+import java.util.Iterator;
+import java.util.List;
+import java.util.Map;
+import net.dnorberg.rivencraft.block.entity.BookReceptacleBlockEntity;
+import net.dnorberg.rivencraft.block.entity.CrystalPortalBlockEntity;
+import net.dnorberg.rivencraft.item.DescriptiveBookItem;
+import net.dnorberg.rivencraft.item.LinkingBookItem;
+import net.dnorberg.rivencraft.registry.ModItems;
+import net.minecraft.core.BlockPos;
+import net.minecraft.server.MinecraftServer;
+import net.minecraft.server.level.ServerLevel;
+import net.minecraft.server.level.ServerPlayer;
+import net.minecraft.world.item.ItemStack;
+
+/** Defers block-collision travel until the movement packet that entered the portal has finished. */
+public final class PortalTravelQueue {
+    private static final Map<ServerPlayer, Pending> PENDING = new IdentityHashMap<>();
+
+    private record Pending(ServerLevel source, BlockPos portal, BlockPos receptacle,
+                           ItemStack book, long queuedTick) {}
+    private record Travel(ServerPlayer player, Pending pending) {}
+
+    private PortalTravelQueue() {}
+
+    public static void enqueue(ServerPlayer player, ServerLevel source, BlockPos portal,
+                               BlockPos receptacle, ItemStack book, long now) {
+        PENDING.putIfAbsent(player, new Pending(source, portal.immutable(), receptacle.immutable(),
+                book.copyWithCount(1), now));
+    }
+
+    public static void process(MinecraftServer server) {
+        List<Travel> ready = new ArrayList<>();
+        Iterator<Map.Entry<ServerPlayer, Pending>> iterator = PENDING.entrySet().iterator();
+        while (iterator.hasNext()) {
+            var entry = iterator.next();
+            if (server.getTickCount() <= entry.getValue().queuedTick()) continue;
+            ready.add(new Travel(entry.getKey(), entry.getValue()));
+            iterator.remove();
+        }
+        // Travel can itself cause block-collision callbacks, so do not keep an
+        // iterator over the pending map while changing the player's dimension.
+        for (Travel travel : ready) {
+            ServerPlayer player = travel.player();
+            Pending pending = travel.pending();
+            if (server.getPlayerList().getPlayer(player.getUUID()) != player
+                    || !player.isAlive() || player.serverLevel() != pending.source()
+                    || !(pending.source().getBlockEntity(pending.portal()) instanceof CrystalPortalBlockEntity portal)
+                    || !pending.receptacle().equals(portal.receptacle())
+                    || !(pending.source().getBlockEntity(pending.receptacle()) instanceof BookReceptacleBlockEntity holder)
+                    || !ItemStack.isSameItemSameComponents(holder.getBook(), pending.book())) continue;
+            if (pending.book().is(ModItems.LINKING_BOOK.get()))
+                LinkingBookItem.usePortalBook(player, pending.book());
+            else if (pending.book().is(ModItems.DESCRIPTIVE_BOOK.get()))
+                DescriptiveBookItem.usePortalBook(player, pending.book());
+        }
+    }
+
+    public static void forget(ServerPlayer player) { PENDING.remove(player); }
+    public static void clear() { PENDING.clear(); }
+}
@@ -70,8 +70,8 @@ public final class ModBlocks {
            DecayBlock::new, BlockBehaviour.Properties.ofFullCopy(Blocks.STONE)
                    .strength(5.0F, 10.0F).noLootTable());
    public static final DeferredBlock<CloudPlatformBlock> CLOUD_PLATFORM = BLOCKS.registerBlock("cloud_platform",
-            CloudPlatformBlock::new, BlockBehaviour.Properties.ofFullCopy(Blocks.WHITE_STAINED_GLASS)
-                    .strength(1.5F).noOcclusion().noLootTable());
+            CloudPlatformBlock::new, BlockBehaviour.Properties.ofFullCopy(Blocks.AMETHYST_BLOCK)
+                    .mapColor(MapColor.COLOR_BLUE).strength(0.3F).noLootTable());

    private ModBlocks() {
    }
@@ -0,0 +1,30 @@
+package net.dnorberg.rivencraft.registry;
+
+import net.dnorberg.rivencraft.Rivencraft;
+import net.dnorberg.rivencraft.entity.DroppedBookEntity;
+import net.minecraft.core.registries.Registries;
+import net.minecraft.world.entity.EntityType;
+import net.minecraft.world.entity.MobCategory;
+import net.neoforged.bus.api.IEventBus;
+import net.neoforged.neoforge.registries.DeferredHolder;
+import net.neoforged.neoforge.registries.DeferredRegister;
+
+public final class ModEntities {
+    private static final DeferredRegister<EntityType<?>> ENTITIES =
+            DeferredRegister.create(Registries.ENTITY_TYPE, Rivencraft.MOD_ID);
+
+    public static final DeferredHolder<EntityType<?>, EntityType<DroppedBookEntity>> DROPPED_BOOK =
+            ENTITIES.register("dropped_book", () -> EntityType.Builder
+                    .<DroppedBookEntity>of(DroppedBookEntity::new, MobCategory.MISC)
+                    .sized(0.65F, 0.4F)
+                    .clientTrackingRange(10)
+                    .updateInterval(20)
+                    .build(Rivencraft.MOD_ID + ":dropped_book"));
+
+    private ModEntities() {
+    }
+
+    public static void register(IEventBus bus) {
+        ENTITIES.register(bus);
+    }
+}
@@ -14,6 +14,8 @@ public final class ModSounds {
            DeferredRegister.create(Registries.SOUND_EVENT, Rivencraft.MOD_ID);

    public static final DeferredHolder<SoundEvent, SoundEvent> LINK = register("linking.link");
+    public static final DeferredHolder<SoundEvent, SoundEvent> LINK_DISARM = register("linking.link-disarm");
+    public static final DeferredHolder<SoundEvent, SoundEvent> LINK_INTRA = register("linking.link-intra");
    public static final DeferredHolder<SoundEvent, SoundEvent> LINK_FISSURE = register("linking.link-fissure");
    public static final DeferredHolder<SoundEvent, SoundEvent> LINK_PORTAL = register("linking.link-portal");
    public static final DeferredHolder<SoundEvent, SoundEvent> METEOR_ROAR = register("entity.meteor.roar");
@@ -1 +1 @@
-{"variants":{"live_view=false":{"model":"rivencraft:block/crystal_portal"},"live_view=true":{"model":"rivencraft:block/crystal_portal"}}}
+{"variants":{"axis=x,live_view=false":{"model":"rivencraft:block/crystal_portal","y":90},"axis=x,live_view=true":{"model":"rivencraft:block/crystal_portal","y":90},"axis=y,live_view=false":{"model":"rivencraft:block/crystal_portal","x":90},"axis=y,live_view=true":{"model":"rivencraft:block/crystal_portal","x":90},"axis=z,live_view=false":{"model":"rivencraft:block/crystal_portal"},"axis=z,live_view=true":{"model":"rivencraft:block/crystal_portal"}}}
@@ -26,7 +26,7 @@
  "container.rivencraft.book_binder": "Book Binder",
  "block.rivencraft.ink_mixer": "Ink Mixer",
  "block.rivencraft.decay": "Decay",
-  "block.rivencraft.cloud_platform": "Cloud Platform",
+  "block.rivencraft.cloud_platform": "Crystal Platform",
  "container.rivencraft.ink_mixer": "Ink Mixer",
  "screen.rivencraft.ink_mixer.ink": "Ink: %s/%s",
  "screen.rivencraft.ink_mixer.additive_hint": "Click the basin with an additive; right-click adds one.",
@@ -341,6 +341,11 @@
  "jei.rivencraft.writing.copy": "At a Writing Desk, select a stored Page, add paper and ink, then take the copy. The source Page stays.",
  "jei.rivencraft.writing.bind": "At a Book Binder, name the Age and add a cover plus Link Panel. Optional symbol Pages follow the panel.",
  "jei.rivencraft.writing.linking_book": "Craft one Link Panel Page with leather to make an unwritten Linking Book. Open it to name and bind it.",
+  "rivencraft.ponder.crystal_portal.header": "Building a Crystal Portal",
+  "rivencraft.ponder.crystal_portal.text_1": "Build a closed crystal frame with an open center.",
+  "rivencraft.ponder.crystal_portal.text_2": "Attach a Book Receptacle to one crystal, facing outward.",
+  "rivencraft.ponder.crystal_portal.text_3": "Insert a bound Linking or Descriptive Book to activate the portal.",
+  "rivencraft.ponder.crystal_portal.text_4": "Step through the portal. Remove the book to close it.",
  "itemGroup.rivencraft": "Rivencraft",
  "itemGroup.rivencraft.pages.link": "Rivencraft Link Pages",
  "itemGroup.rivencraft.pages.terrain": "Rivencraft Terrain Pages",
@@ -364,5 +369,21 @@
  "symbol.rivencraft.corrupted.medium": "Corrupted Page",
  "symbol.rivencraft.corrupted.medium.description": "The writing shifts beyond comprehension.",
  "symbol.rivencraft.corrupted.small": "Corrupted Page",
-  "symbol.rivencraft.corrupted.small.description": "The writing shifts beyond comprehension."
+  "symbol.rivencraft.corrupted.small.description": "The writing shifts beyond comprehension.",
+  "advancement.rivencraft.root.title": "The Ending Has Not Yet Been Written",
+  "advancement.rivencraft.root.description": "Begin the Art of writing and linking Ages.",
+  "advancement.rivencraft.page.title": "A Strange Page",
+  "advancement.rivencraft.page.description": "Find a Page marked with the language of Ages.",
+  "advancement.rivencraft.linking_book.title": "A Way Back",
+  "advancement.rivencraft.linking_book.description": "Obtain a Linking Book and remember where you came from.",
+  "advancement.rivencraft.link_panel.title": "D'ni Ink",
+  "advancement.rivencraft.link_panel.description": "Create a Link Panel at the Ink Mixer.",
+  "advancement.rivencraft.copy_page.title": "The Art of Writing",
+  "advancement.rivencraft.copy_page.description": "Copy a Page at the Writing Desk.",
+  "advancement.rivencraft.bind_age.title": "A Book of Ages",
+  "advancement.rivencraft.bind_age.description": "Bind a completed Descriptive Book.",
+  "advancement.rivencraft.enter_age.title": "The Journey Begins",
+  "advancement.rivencraft.enter_age.description": "Safely link into an Age you have written.",
+  "advancement.rivencraft.open_portal.title": "A Window Between Ages",
+  "advancement.rivencraft.open_portal.description": "Activate a Crystal Portal with a bound book."
 }
@@ -39,6 +39,28 @@
        "down": {"texture":"#press","uv":[8.5,0,10,7]}
      }
    },
+    {
+      "from": [6, 10, 1], "to": [7, 14, 15],
+      "faces": {
+        "north": {"texture":"#press","uv":[7,13,7.5,15]},
+        "east": {"texture":"#press","uv":[7.5,13,14.5,15]},
+        "south": {"texture":"#press","uv":[14.5,13,15,15]},
+        "west": {"texture":"#press","uv":[0,13,7,15]},
+        "up": {"texture":"#press","uv":[0,6,0.5,13]},
+        "down": {"texture":"#press","uv":[0.5,6,1,13]}
+      }
+    },
+    {
+      "from": [9, 10, 1], "to": [10, 14, 15],
+      "faces": {
+        "north": {"texture":"#press","uv":[7,13,7.5,15]},
+        "east": {"texture":"#press","uv":[0,13,7,15]},
+        "south": {"texture":"#press","uv":[14.5,13,15,15]},
+        "west": {"texture":"#press","uv":[7.5,13,14.5,15]},
+        "up": {"texture":"#press","uv":[0,6,0.5,13]},
+        "down": {"texture":"#press","uv":[0.5,6,1,13]}
+      }
+    },
    {
      "from": [3, 11, 3], "to": [13, 12, 4],
      "faces": {
@@ -56,6 +78,17 @@
        "up": {"texture":"#press","uv":[0.5,15,5.5,15.5]},
        "down": {"texture":"#press","uv":[5.5,15,10.5,15.5]}
      }
+    },
+    {
+      "from": [7, 10, 4.5], "to": [9, 15, 11.5],
+      "faces": {
+        "north": {"texture":"#press","uv":[4.5,10.5,5.5,13]},
+        "east": {"texture":"#press","uv":[1,10.5,4.5,13]},
+        "south": {"texture":"#press","uv":[9,10,10,13]},
+        "west": {"texture":"#press","uv":[5.5,10.5,9,13]},
+        "up": {"texture":"#press","uv":[4.5,7,5.5,10.5]},
+        "down": {"texture":"#press","uv":[5.5,7,6.5,10.5]}
+      }
    }
  ]
 }
@@ -1 +1 @@
-{"parent":"minecraft:block/cube_all","render_type":"minecraft:translucent","textures":{"all":"rivencraft:block/cloud_platform"}}
+{"parent":"minecraft:block/cube_all","textures":{"all":"rivencraft:block/crystal_block"}}
@@ -1 +1 @@
-{"parent":"minecraft:block/cube_all","textures":{"all":"rivencraft:block/crystal_portal"}}
+{"render_type":"minecraft:translucent","ambientocclusion":false,"textures":{"particle":"rivencraft:block/crystal_portal","portal":"rivencraft:block/crystal_portal"},"elements":[{"from":[0,0,6],"to":[16,16,10],"shade":false,"faces":{"north":{"texture":"#portal"},"south":{"texture":"#portal"}}}]}
@@ -1,23 +1,971 @@
 {
  "parent": "minecraft:block/block",
  "textures": {
-    "particle": "rivencraft:block/ink_mixer_side",
-    "side": "rivencraft:block/ink_mixer_side",
-    "top": "rivencraft:block/ink_mixer_top",
-    "bottom": "rivencraft:block/ink_mixer_bottom"
+    "0": "rivencraft:block/inkwell_base",
+    "1": "rivencraft:block/inkwell_cup",
+    "2": "rivencraft:block/ink",
+    "3": "rivencraft:block/ink_glass",
+    "particle": "rivencraft:block/inkwell_base",
+    "paper": "minecraft:block/white_concrete"
  },
  "elements": [
    {
-      "from": [0, 0, 0],
-      "to": [16, 12, 16],
+      "from": [
+        0,
+        0,
+        0
+      ],
+      "to": [
+        16,
+        9,
+        16
+      ],
      "faces": {
-        "north": { "texture": "#side", "uv": [0, 4, 16, 16] },
-        "east": { "texture": "#side", "uv": [0, 4, 16, 16] },
-        "south": { "texture": "#side", "uv": [0, 4, 16, 16] },
-        "west": { "texture": "#side", "uv": [0, 4, 16, 16] },
-        "up": { "texture": "#top" },
-        "down": { "texture": "#bottom" }
+        "north": {
+          "texture": "#0",
+          "uv": [
+            0,
+            5,
+            4,
+            7
+          ]
+        },
+        "east": {
+          "texture": "#0",
+          "uv": [
+            4,
+            5,
+            8,
+            7
+          ]
+        },
+        "south": {
+          "texture": "#0",
+          "uv": [
+            8,
+            5,
+            12,
+            7
+          ]
+        },
+        "west": {
+          "texture": "#0",
+          "uv": [
+            12,
+            5,
+            16,
+            7
+          ]
+        },
+        "down": {
+          "texture": "#0",
+          "uv": [
+            8,
+            0,
+            12,
+            4
+          ]
+        }
+      }
+    },
+    {
+      "from": [
+        0,
+        9,
+        0
+      ],
+      "to": [
+        16,
+        12,
+        16
+      ],
+      "faces": {
+        "north": {
+          "texture": "#0",
+          "uv": [
+            0,
+            4,
+            4,
+            5
+          ]
+        },
+        "east": {
+          "texture": "#0",
+          "uv": [
+            4,
+            4,
+            8,
+            5
+          ]
+        },
+        "south": {
+          "texture": "#0",
+          "uv": [
+            8,
+            4,
+            12,
+            5
+          ]
+        },
+        "west": {
+          "texture": "#0",
+          "uv": [
+            12,
+            4,
+            16,
+            5
+          ]
+        },
+        "up": {
+          "texture": "#0",
+          "uv": [
+            4,
+            0,
+            8,
+            4
+          ]
+        }
+      }
+    },
+    {
+      "from": [
+        9,
+        12,
+        6
+      ],
+      "to": [
+        13,
+        13,
+        10
+      ],
+      "faces": {
+        "north": {
+          "texture": "#1",
+          "uv": [
+            0,
+            0,
+            4,
+            1
+          ]
+        },
+        "east": {
+          "texture": "#1",
+          "uv": [
+            4,
+            0,
+            8,
+            1
+          ]
+        },
+        "south": {
+          "texture": "#1",
+          "uv": [
+            8,
+            0,
+            12,
+            1
+          ]
+        },
+        "west": {
+          "texture": "#1",
+          "uv": [
+            12,
+            0,
+            16,
+            1
+          ]
+        }
+      }
+    },
+    {
+      "from": [
+        8,
+        13,
+        5
+      ],
+      "to": [
+        14,
+        16,
+        6
+      ],
+      "faces": {
+        "north": {
+          "texture": "#1",
+          "uv": [
+            7,
+            1,
+            13,
+            4
+          ]
+        },
+        "east": {
+          "texture": "#1",
+          "uv": [
+            6,
+            1,
+            7,
+            4
+          ]
+        },
+        "south": {
+          "texture": "#1",
+          "uv": [
+            0,
+            1,
+            6,
+            4
+          ]
+        },
+        "west": {
+          "texture": "#1",
+          "uv": [
+            13,
+            1,
+            14,
+            4
+          ]
+        },
+        "up": {
+          "texture": "#1",
+          "uv": [
+            0,
+            0,
+            6,
+            1
+          ]
+        },
+        "down": {
+          "texture": "#1",
+          "uv": [
+            0,
+            0,
+            6,
+            1
+          ]
+        }
+      }
+    },
+    {
+      "from": [
+        8,
+        13,
+        10
+      ],
+      "to": [
+        14,
+        16,
+        11
+      ],
+      "faces": {
+        "north": {
+          "texture": "#1",
+          "uv": [
+            0,
+            0,
+            6,
+            3
+          ]
+        },
+        "east": {
+          "texture": "#1",
+          "uv": [
+            0,
+            0,
+            1,
+            3
+          ]
+        },
+        "south": {
+          "texture": "#1",
+          "uv": [
+            0,
+            0,
+            6,
+            3
+          ]
+        },
+        "west": {
+          "texture": "#1",
+          "uv": [
+            0,
+            0,
+            1,
+            3
+          ]
+        },
+        "up": {
+          "texture": "#1",
+          "uv": [
+            0,
+            0,
+            6,
+            1
+          ]
+        },
+        "down": {
+          "texture": "#1",
+          "uv": [
+            0,
+            0,
+            6,
+            1
+          ]
+        }
+      }
+    },
+    {
+      "from": [
+        8,
+        13,
+        6
+      ],
+      "to": [
+        9,
+        16,
+        10
+      ],
+      "faces": {
+        "north": {
+          "texture": "#1",
+          "uv": [
+            0,
+            0,
+            1,
+            3
+          ]
+        },
+        "east": {
+          "texture": "#1",
+          "uv": [
+            0,
+            0,
+            4,
+            3
+          ]
+        },
+        "south": {
+          "texture": "#1",
+          "uv": [
+            0,
+            0,
+            1,
+            3
+          ]
+        },
+        "west": {
+          "texture": "#1",
+          "uv": [
+            0,
+            0,
+            4,
+            3
+          ]
+        },
+        "up": {
+          "texture": "#1",
+          "uv": [
+            0,
+            0,
+            1,
+            4
+          ]
+        },
+        "down": {
+          "texture": "#1",
+          "uv": [
+            0,
+            0,
+            1,
+            4
+          ]
+        }
+      }
+    },
+    {
+      "from": [
+        13,
+        13,
+        6
+      ],
+      "to": [
+        14,
+        16,
+        10
+      ],
+      "faces": {
+        "north": {
+          "texture": "#1",
+          "uv": [
+            0,
+            0,
+            1,
+            3
+          ]
+        },
+        "east": {
+          "texture": "#1",
+          "uv": [
+            0,
+            0,
+            4,
+            3
+          ]
+        },
+        "south": {
+          "texture": "#1",
+          "uv": [
+            0,
+            0,
+            1,
+            3
+          ]
+        },
+        "west": {
+          "texture": "#1",
+          "uv": [
+            0,
+            0,
+            4,
+            3
+          ]
+        },
+        "up": {
+          "texture": "#1",
+          "uv": [
+            0,
+            0,
+            1,
+            4
+          ]
+        },
+        "down": {
+          "texture": "#1",
+          "uv": [
+            0,
+            0,
+            1,
+            4
+          ]
+        }
+      }
+    },
+    {
+      "from": [
+        9,
+        14,
+        6
+      ],
+      "to": [
+        13,
+        15,
+        10
+      ],
+      "faces": {
+        "up": {
+          "texture": "#2",
+          "uv": [
+            0,
+            0,
+            4,
+            3
+          ]
+        }
+      }
+    },
+    {
+      "from": [
+        7,
+        12,
+        2
+      ],
+      "to": [
+        9,
+        14,
+        4
+      ],
+      "rotation": {
+        "origin": [
+          8,
+          8,
+          8
+        ],
+        "axis": "y",
+        "angle": 22.5
+      },
+      "faces": {
+        "north": {
+          "texture": "#3",
+          "uv": [
+            0,
+            0,
+            2,
+            2
+          ]
+        },
+        "east": {
+          "texture": "#3",
+          "uv": [
+            2,
+            0,
+            4,
+            2
+          ]
+        },
+        "south": {
+          "texture": "#3",
+          "uv": [
+            4,
+            0,
+            6,
+            2
+          ]
+        },
+        "west": {
+          "texture": "#3",
+          "uv": [
+            6,
+            0,
+            8,
+            2
+          ]
+        },
+        "up": {
+          "texture": "#3",
+          "uv": [
+            0,
+            2,
+            2,
+            4
+          ]
+        },
+        "down": {
+          "texture": "#3",
+          "uv": [
+            0,
+            0,
+            2,
+            2
+          ]
+        }
+      }
+    },
+    {
+      "from": [
+        1,
+        12,
+        6
+      ],
+      "to": [
+        3,
+        14,
+        8
+      ],
+      "rotation": {
+        "origin": [
+          8,
+          8,
+          8
+        ],
+        "axis": "y",
+        "angle": -22.5
+      },
+      "faces": {
+        "north": {
+          "texture": "#3",
+          "uv": [
+            0,
+            0,
+            2,
+            2
+          ]
+        },
+        "east": {
+          "texture": "#3",
+          "uv": [
+            2,
+            0,
+            4,
+            2
+          ]
+        },
+        "south": {
+          "texture": "#3",
+          "uv": [
+            4,
+            0,
+            6,
+            2
+          ]
+        },
+        "west": {
+          "texture": "#3",
+          "uv": [
+            6,
+            0,
+            8,
+            2
+          ]
+        },
+        "up": {
+          "texture": "#3",
+          "uv": [
+            0,
+            2,
+            2,
+            4
+          ]
+        },
+        "down": {
+          "texture": "#3",
+          "uv": [
+            0,
+            0,
+            2,
+            2
+          ]
+        }
+      }
+    },
+    {
+      "from": [
+        7.5,
+        14,
+        2.5
+      ],
+      "to": [
+        8.5,
+        15,
+        3.5
+      ],
+      "rotation": {
+        "origin": [
+          8,
+          8,
+          8
+        ],
+        "axis": "y",
+        "angle": 22.5
+      },
+      "faces": {
+        "north": {
+          "texture": "#3",
+          "uv": [
+            0,
+            0,
+            1,
+            1
+          ]
+        },
+        "east": {
+          "texture": "#3",
+          "uv": [
+            2,
+            0,
+            3,
+            1
+          ]
+        },
+        "south": {
+          "texture": "#3",
+          "uv": [
+            4,
+            0,
+            5,
+            1
+          ]
+        },
+        "west": {
+          "texture": "#3",
+          "uv": [
+            6,
+            0,
+            7,
+            1
+          ]
+        },
+        "up": {
+          "texture": "#3",
+          "uv": [
+            0,
+            2,
+            1,
+            3
+          ]
+        },
+        "down": {
+          "texture": "#3",
+          "uv": [
+            0,
+            0,
+            1,
+            1
+          ]
+        }
+      }
+    },
+    {
+      "from": [
+        1.5,
+        14,
+        6.5
+      ],
+      "to": [
+        2.5,
+        15,
+        7.5
+      ],
+      "rotation": {
+        "origin": [
+          8,
+          8,
+          8
+        ],
+        "axis": "y",
+        "angle": -22.5
+      },
+      "faces": {
+        "north": {
+          "texture": "#3",
+          "uv": [
+            0,
+            0,
+            1,
+            1
+          ]
+        },
+        "east": {
+          "texture": "#3",
+          "uv": [
+            2,
+            0,
+            3,
+            1
+          ]
+        },
+        "south": {
+          "texture": "#3",
+          "uv": [
+            4,
+            0,
+            5,
+            1
+          ]
+        },
+        "west": {
+          "texture": "#3",
+          "uv": [
+            6,
+            0,
+            7,
+            1
+          ]
+        },
+        "up": {
+          "texture": "#3",
+          "uv": [
+            0,
+            2,
+            1,
+            3
+          ]
+        },
+        "down": {
+          "texture": "#3",
+          "uv": [
+            0,
+            0,
+            1,
+            1
+          ]
+        }
+      }
+    },
+    {
+      "from": [
+        4,
+        12,
+        5
+      ],
+      "to": [
+        6,
+        14,
+        7
+      ],
+      "rotation": {
+        "origin": [
+          8,
+          8,
+          8
+        ],
+        "axis": "y",
+        "angle": 22.5
+      },
+      "faces": {
+        "north": {
+          "texture": "#3",
+          "uv": [
+            0,
+            0,
+            2,
+            2
+          ]
+        },
+        "east": {
+          "texture": "#3",
+          "uv": [
+            2,
+            0,
+            4,
+            2
+          ]
+        },
+        "south": {
+          "texture": "#3",
+          "uv": [
+            4,
+            0,
+            6,
+            2
+          ]
+        },
+        "west": {
+          "texture": "#3",
+          "uv": [
+            6,
+            0,
+            8,
+            2
+          ]
+        },
+        "up": {
+          "texture": "#3",
+          "uv": [
+            0,
+            2,
+            2,
+            4
+          ]
+        },
+        "down": {
+          "texture": "#3",
+          "uv": [
+            0,
+            0,
+            2,
+            2
+          ]
+        }
+      }
+    },
+    {
+      "from": [
+        4.5,
+        14,
+        5.5
+      ],
+      "to": [
+        5.5,
+        15,
+        6.5
+      ],
+      "rotation": {
+        "origin": [
+          8,
+          8,
+          8
+        ],
+        "axis": "y",
+        "angle": 22.5
+      },
+      "faces": {
+        "north": {
+          "texture": "#3",
+          "uv": [
+            0,
+            0,
+            1,
+            1
+          ]
+        },
+        "east": {
+          "texture": "#3",
+          "uv": [
+            2,
+            0,
+            3,
+            1
+          ]
+        },
+        "south": {
+          "texture": "#3",
+          "uv": [
+            4,
+            0,
+            5,
+            1
+          ]
+        },
+        "west": {
+          "texture": "#3",
+          "uv": [
+            6,
+            0,
+            7,
+            1
+          ]
+        },
+        "up": {
+          "texture": "#3",
+          "uv": [
+            0,
+            2,
+            1,
+            3
+          ]
+        },
+        "down": {
+          "texture": "#3",
+          "uv": [
+            0,
+            0,
+            1,
+            1
+          ]
+        }
+      }
+    },
+    {
+      "from": [
+        1,
+        12.01,
+        2
+      ],
+      "to": [
+        7,
+        12.16,
+        11
+      ],
+      "faces": {
+        "north": {
+          "texture": "#paper"
+        },
+        "east": {
+          "texture": "#paper"
+        },
+        "south": {
+          "texture": "#paper"
+        },
+        "west": {
+          "texture": "#paper"
+        },
+        "up": {
+          "texture": "#paper"
+        },
+        "down": {
+          "texture": "#paper"
+        }
      }
    }
-  ]
+  ],
+  "render_type": "minecraft:cutout"
 }
@@ -7,6 +7,14 @@
      }
    ]
  },
+  "linking.link-disarm": {
+    "category": "player",
+    "sounds": [{"name": "rivencraft:linking/link-disarm"}]
+  },
+  "linking.link-intra": {
+    "category": "player",
+    "sounds": [{"name": "rivencraft:linking/link-intra"}]
+  },
  "linking.link-fissure": {
    "category": "player",
    "sounds": [{"name": "rivencraft:linking/link-fissure"}]
@@ -0,0 +1,19 @@
+{
+  "parent": "rivencraft:progression/link_panel",
+  "display": {
+    "icon": {
+      "id": "rivencraft:descriptive_book"
+    },
+    "title": {
+      "translate": "advancement.rivencraft.bind_age.title"
+    },
+    "description": {
+      "translate": "advancement.rivencraft.bind_age.description"
+    }
+  },
+  "criteria": {
+    "completed": {
+      "trigger": "minecraft:impossible"
+    }
+  }
+}
@@ -0,0 +1,19 @@
+{
+  "parent": "rivencraft:progression/page",
+  "display": {
+    "icon": {
+      "id": "rivencraft:writing_desk"
+    },
+    "title": {
+      "translate": "advancement.rivencraft.copy_page.title"
+    },
+    "description": {
+      "translate": "advancement.rivencraft.copy_page.description"
+    }
+  },
+  "criteria": {
+    "completed": {
+      "trigger": "minecraft:impossible"
+    }
+  }
+}
@@ -0,0 +1,20 @@
+{
+  "parent": "rivencraft:progression/bind_age",
+  "display": {
+    "icon": {
+      "id": "rivencraft:descriptive_book"
+    },
+    "title": {
+      "translate": "advancement.rivencraft.enter_age.title"
+    },
+    "description": {
+      "translate": "advancement.rivencraft.enter_age.description"
+    },
+    "frame": "goal"
+  },
+  "criteria": {
+    "completed": {
+      "trigger": "minecraft:impossible"
+    }
+  }
+}
@@ -0,0 +1,19 @@
+{
+  "parent": "rivencraft:progression/root",
+  "display": {
+    "icon": {
+      "id": "rivencraft:ink_mixer"
+    },
+    "title": {
+      "translate": "advancement.rivencraft.link_panel.title"
+    },
+    "description": {
+      "translate": "advancement.rivencraft.link_panel.description"
+    }
+  },
+  "criteria": {
+    "completed": {
+      "trigger": "minecraft:impossible"
+    }
+  }
+}
@@ -0,0 +1,26 @@
+{
+  "parent": "rivencraft:progression/root",
+  "display": {
+    "icon": {
+      "id": "rivencraft:linking_book"
+    },
+    "title": {
+      "translate": "advancement.rivencraft.linking_book.title"
+    },
+    "description": {
+      "translate": "advancement.rivencraft.linking_book.description"
+    }
+  },
+  "criteria": {
+    "completed": {
+      "trigger": "minecraft:inventory_changed",
+      "conditions": {
+        "items": [
+          {
+            "items": "rivencraft:linking_book"
+          }
+        ]
+      }
+    }
+  }
+}
@@ -0,0 +1,20 @@
+{
+  "parent": "rivencraft:progression/linking_book",
+  "display": {
+    "icon": {
+      "id": "rivencraft:book_receptacle"
+    },
+    "title": {
+      "translate": "advancement.rivencraft.open_portal.title"
+    },
+    "description": {
+      "translate": "advancement.rivencraft.open_portal.description"
+    },
+    "frame": "goal"
+  },
+  "criteria": {
+    "completed": {
+      "trigger": "minecraft:impossible"
+    }
+  }
+}
@@ -0,0 +1,26 @@
+{
+  "parent": "rivencraft:progression/root",
+  "display": {
+    "icon": {
+      "id": "rivencraft:page"
+    },
+    "title": {
+      "translate": "advancement.rivencraft.page.title"
+    },
+    "description": {
+      "translate": "advancement.rivencraft.page.description"
+    }
+  },
+  "criteria": {
+    "completed": {
+      "trigger": "minecraft:inventory_changed",
+      "conditions": {
+        "items": [
+          {
+            "items": "rivencraft:page"
+          }
+        ]
+      }
+    }
+  }
+}
@@ -0,0 +1,21 @@
+{
+  "display": {
+    "icon": {
+      "id": "rivencraft:descriptive_book"
+    },
+    "title": {
+      "translate": "advancement.rivencraft.root.title"
+    },
+    "description": {
+      "translate": "advancement.rivencraft.root.description"
+    },
+    "background": "minecraft:textures/gui/advancements/backgrounds/stone.png",
+    "show_toast": false,
+    "announce_to_chat": false
+  },
+  "criteria": {
+    "completed": {
+      "trigger": "minecraft:tick"
+    }
+  }
+}
@@ -0,0 +1,32 @@
+{
+  "parent": "minecraft:recipes/root",
+  "criteria": {
+    "has_material": {
+      "trigger": "minecraft:inventory_changed",
+      "conditions": {
+        "items": [
+          {
+            "items": "minecraft:iron_ingot"
+          }
+        ]
+      }
+    },
+    "has_the_recipe": {
+      "trigger": "minecraft:recipe_unlocked",
+      "conditions": {
+        "recipe": "rivencraft:book_binder"
+      }
+    }
+  },
+  "requirements": [
+    [
+      "has_material",
+      "has_the_recipe"
+    ]
+  ],
+  "rewards": {
+    "recipes": [
+      "rivencraft:book_binder"
+    ]
+  }
+}
@@ -0,0 +1,15 @@
+{
+  "parent": "minecraft:recipes/root",
+  "criteria": {
+    "has_crystal_block": {
+      "trigger": "minecraft:inventory_changed",
+      "conditions": {"items": [{"items": "rivencraft:crystal_block"}]}
+    },
+    "has_the_recipe": {
+      "trigger": "minecraft:recipe_unlocked",
+      "conditions": {"recipe": "rivencraft:book_receptacle"}
+    }
+  },
+  "requirements": [["has_crystal_block", "has_the_recipe"]],
+  "rewards": {"recipes": ["rivencraft:book_receptacle"]}
+}
@@ -0,0 +1,15 @@
+{
+  "parent": "minecraft:recipes/root",
+  "criteria": {
+    "has_crystal_shard": {
+      "trigger": "minecraft:inventory_changed",
+      "conditions": {"items": [{"items": "rivencraft:crystal_shard"}]}
+    },
+    "has_the_recipe": {
+      "trigger": "minecraft:recipe_unlocked",
+      "conditions": {"recipe": "rivencraft:crystal_block"}
+    }
+  },
+  "requirements": [["has_crystal_shard", "has_the_recipe"]],
+  "rewards": {"recipes": ["rivencraft:crystal_block"]}
+}
@@ -0,0 +1,32 @@
+{
+  "parent": "minecraft:recipes/root",
+  "criteria": {
+    "has_material": {
+      "trigger": "minecraft:inventory_changed",
+      "conditions": {
+        "items": [
+          {
+            "items": "minecraft:glass_bottle"
+          }
+        ]
+      }
+    },
+    "has_the_recipe": {
+      "trigger": "minecraft:recipe_unlocked",
+      "conditions": {
+        "recipe": "rivencraft:ink_mixer"
+      }
+    }
+  },
+  "requirements": [
+    [
+      "has_material",
+      "has_the_recipe"
+    ]
+  ],
+  "rewards": {
+    "recipes": [
+      "rivencraft:ink_mixer"
+    ]
+  }
+}
@@ -0,0 +1,15 @@
+{
+  "parent": "minecraft:recipes/root",
+  "criteria": {
+    "has_black_dye": {
+      "trigger": "minecraft:inventory_changed",
+      "conditions": {"items": [{"items": "minecraft:black_dye"}]}
+    },
+    "has_the_recipe": {
+      "trigger": "minecraft:recipe_unlocked",
+      "conditions": {"recipe": "rivencraft:ink_vial"}
+    }
+  },
+  "requirements": [["has_black_dye", "has_the_recipe"]],
+  "rewards": {"recipes": ["rivencraft:ink_vial"]}
+}
@@ -0,0 +1,32 @@
+{
+  "parent": "minecraft:recipes/root",
+  "criteria": {
+    "has_material": {
+      "trigger": "minecraft:inventory_changed",
+      "conditions": {
+        "items": [
+          {
+            "items": "minecraft:leather"
+          }
+        ]
+      }
+    },
+    "has_the_recipe": {
+      "trigger": "minecraft:recipe_unlocked",
+      "conditions": {
+        "recipe": "rivencraft:notebook"
+      }
+    }
+  },
+  "requirements": [
+    [
+      "has_material",
+      "has_the_recipe"
+    ]
+  ],
+  "rewards": {
+    "recipes": [
+      "rivencraft:notebook"
+    ]
+  }
+}
@@ -0,0 +1,32 @@
+{
+  "parent": "minecraft:recipes/root",
+  "criteria": {
+    "has_material": {
+      "trigger": "minecraft:inventory_changed",
+      "conditions": {
+        "items": [
+          {
+            "items": "minecraft:feather"
+          }
+        ]
+      }
+    },
+    "has_the_recipe": {
+      "trigger": "minecraft:recipe_unlocked",
+      "conditions": {
+        "recipe": "rivencraft:writing_desk"
+      }
+    }
+  },
+  "requirements": [
+    [
+      "has_material",
+      "has_the_recipe"
+    ]
+  ],
+  "rewards": {
+    "recipes": [
+      "rivencraft:writing_desk"
+    ]
+  }
+}
@@ -1 +1,7 @@
-{"type":"minecraft:crafting_shaped","pattern":["CCC","C C","CCC"],"key":{"C":{"item":"rivencraft:crystal_block"}},"result":{"id":"rivencraft:book_receptacle","count":1}}
+{
+  "type": "minecraft:crafting_shaped",
+  "category": "misc",
+  "pattern": ["CCC", "C C", "CCC"],
+  "key": {"C": {"item": "rivencraft:crystal_block"}},
+  "result": {"id": "rivencraft:book_receptacle", "count": 1}
+}
@@ -19,6 +19,9 @@
    "rivencraft:book_binder",
    "rivencraft:ink_mixer",
    "rivencraft:star_fissure",
-    "rivencraft:cloud_platform"
+    "rivencraft:cloud_platform",
+    "rivencraft:crystal_block",
+    "rivencraft:book_receptacle",
+    "rivencraft:crystal_portal"
  ]
 }
Author	SHA1	Message	Date
dnorberg	d0af75239a	Match Legacy handheld book drops with model entity (#85 ) Build / build (push) Canceled after 0s Details	2026-10-19 16:41:07 -04:00
dnorberg	2e5d6e0427	Adopt NeoForge 21.1.264 after compatibility testing Build / build (push) Canceled after 0s Details	2026-10-19 05:37:46 -04:00
dnorberg	54c10cca6c	Default automatic Return Links to disabled and review compatibility Build / build (push) Canceled after 0s Details	2026-10-19 05:21:00 -04:00
dnorberg	c39ebd78ba	Add Milestone 7 progression advancements Build / build (push) Canceled after 0s Details	2026-10-19 04:57:15 -04:00
dnorberg	1ff62e9aaa	Polish Milestone 7 models textures and link effects Build / build (push) Canceled after 0s Details	2026-10-19 04:32:35 -04:00
dnorberg	b154455563	Complete Milestone 7 crafting and portal guide (#79 ) Build / build (push) Canceled after 0s Details	2026-10-19 04:01:03 -04:00
dnorberg	4a87c9fae6	Harden crystal portals across restart and protected travel Build / build (push) Canceled after 0s Details	2026-10-18 23:17:16 -04:00
dnorberg	350d137d9e	Render fallback crystal portals as two-sided surfaces Build / build (push) Canceled after 0s Details	2026-10-18 00:22:56 -04:00