Release 26.3.0.1 with live Reborn views and random page policies

docs/DUAL_VERSION_RELEASE.md

@@ -0,0 +1,53 @@
+# Dual-version release workflow
+
+Maintain Minecraft 1.21.1 and 26.3 independently. The 1.21.1 line retains Dynamic
+Dimensions AR Edition and Bad Packets. The 26.3 line uses its first-party backend.
+Do not widen either artifact's Minecraft dependency range or import saves between
+the tracks.
+
+## Version identity
+
+From 26.3.0.1 onward, prefix the Minecraft version and append the milestone/release
+slice and iteration: Minecraft.release-slice.iteration. Example:
+`26.3.0.1` -> `rivencraft-26.3.0.1.jar`, Gitea tag `V26.3.0.1`.
+An explicitly selected prerelease uses a suffix such as `-beta.1`.
+The existing 1.21.1 release keeps its published version until its next code update;
+then use the corresponding `1.21.1.<slice>.<iteration>` convention.
+
+The user authorized regular release status for 26.3.0.1. Release-channel status
+does not close unfinished parity or multiplayer issues automatically.
+
+## Build and publish
+
+For 26.3, update `ports/mc263/gradle.properties`, then run
+`./gradlew -p ports/mc263 build --console=plain` with Java 25 available.
+Use the exact built/player-validated artifact; naming/metadata-only changes do
+not change generation or save behavior.
+
+Write release notes, audit the guide/wiki/project description, commit and push
+the changes, then create and push the matching annotated tag. Preview the
+`scripts/publish_mod_sites.py release` command with the JAR, changelog, version,
+display name, Minecraft version, Java version and channel; add `--publish` to
+upload to Gitea, Modrinth and CurseForge. Tokens stay in the system keyring.
+Verify published metadata and downloaded artifact hashes. CurseForge approval
+may remain pending after a successful upload.
+
+The publisher accepts legacy Minecraft-prefixed archive filenames and beta tags
+for already numbered historical uploads; new releases use the identity above.
+
+## Validation gates and issue audit
+
+Run appropriate builds and targeted server checks for changed behavior. The user
+performs visual/gameplay validation. Keep temporary test fixtures out of shipped
+JARs; use new worlds and remove them regardless of pass/fail. Stop test processes.
+If generation stalls, hand the test to the user.
+
+Before closing a port umbrella issue, compare its acceptance criteria and comments
+to actual evidence. Current expanded-catalog two-client create/travel/reconnect/
+restart/stale-ack regression remains in #100. #103 retains dual-line release
+automation/regression completion and #104 retains the full parity gate.
+Shared issues need both versions resolved before closure.
+
+For each release, document tested optional versions and no-optional fallbacks,
+match client/server JARs, preserve the independent 1.21.1 support line, update wiki
+and platform descriptions, and keep known bugs linked in the release notes.

docs/MINECRAFT_26_3_PORT.md

@@ -10,18 +10,18 @@ tracks issues #97–#103 under parent #96.
 
 ## Published status — 2026-11-11
 
-[1.0.1.136-beta.1](../ports/mc263/RELEASE_NOTES_1.0.1.136-beta.1.md) collects
-player-validated .130–.136: Link Modifier seed editing and operator retirement,
-creation rollback, and optional JEI, TerraBlender/BOP, Serene Seasons/GlitchCore
-and Ruins. Both Minecraft builds pass. The latest production client log records
-all these optional integrations loaded together. Issue #99's remaining creation
-rollback requirement is complete. #100 still requires the current dedicated
-two-client/normal-book matrix; #102 retains the live-renderer/alternative review;
-#103/#104 and parent #96 remain open. Shared dual-version follow-ups remain open
-where one or both implementations are pending. The versioning change requested
-in #103's comment remains part of that next release-workflow task; this release
-retains the version already built and player-tested. Entries below are historical
-engineering records and may describe limitations addressed in later slices.
+[26.3.0.1](../ports/mc263/RELEASE_NOTES_26.3.0.1.md) collects the player-validated
+.137–.142 slices: random-page eligibility, random-Age glyph descriptions, optional
+portal-engine dimension synchronization, and Reborn live book/crystal portal views.
+It is published on the regular release channel at the user's request, using the
+new Minecraft-prefixed version scheme. Minecraft 1.21.1 remains unchanged.
+
+#102's optional-integration audit/port is complete; the Static Sky/Reborn rendering
+bug is tracked separately in #116. #100 still requires the current expanded-catalog
+dedicated two-client matrix. #103/#104 and parent #96 retain the remaining workflow
+and parity gates. Full parity is not implied by the release channel. Shared
+follow-ups stay open where one or both implementations are pending. Earlier
+entries are historical records and may describe limitations resolved later.
 
 ## Version boundary
 
@@ -102,8 +102,8 @@ range of the 1.21.1 JAR. The official [26.3 release notes](https://www.minecraft
 [NeoForge 26.3 Maven metadata](https://maven.neoforged.net/releases/net/neoforged/neoforge/maven-metadata.xml),
 [NeoForge Java 25 setting](https://github.com/neoforged/NeoForge/blob/26.3.x/gradle.properties),
 and [NeoForge migration primers](https://docs.neoforged.net/primer/docs/)
-are the version sources. NeoForge 26.3.0.99 is the newest listed stable build
-at the time of this check.
+are the version sources. NeoForge 26.3.0.99 is the validated target for this release; the availability
+of newer NeoForge builds does not imply they have been validated.
 
 ## Dependency availability
 
@@ -121,7 +121,8 @@ Rivencraft. Recheck immediately before choosing versions for a port build.
 | [Biomes O' Plenty](https://modrinth.com/mod/biomes-o-plenty) | Optional TerraBlender test addon | Yes | Test modded biome registration and decoration. |
 | [Ruins (Structure Spawning System)](https://www.curseforge.com/minecraft/mc-mods/ruins-structure-spawning-system) | Optional authored ruins integration | Yes | Port and verify its generation hooks. |
 | [Create](https://modrinth.com/mod/create) / bundled Ponder | Optional scene renderer | No advertised 26.3 version | Use Rivencraft's existing legacy-animation preview fallback for this target until a compatible release exists. |
-| [Immersive Portals for (Neo)Forge](https://modrinth.com/mod/immersive-portals-neoforge) | Optional live views and portal teleport integration | No advertised 26.3 version | Use the fallback portal surface and normal Rivencraft linking. Do not claim live destination views on 26.3. |
+| [Immersive Portal / Seamless Portals](https://www.curseforge.com/minecraft/mc-mods/immersive-portal/files/9218525) | Optional live views and portal integration | Latest file 9218525: displayed 10.0.0, internal 1.0.0 | Runtime-Age/native packet checks passed; live rendering still pending. Old file 8937394 has an upstream startup failure. |
+| [Immersive Portals Reborn](https://www.curseforge.com/minecraft/mc-mods/immersive-portals-reborn-unofficial-fork/files/9435354) | Alternative optional portal engine | NeoForge 7.0.12 for 26.3; later 7.0.18 is Fabric | .141–.142 port live book/crystal views; player, dedicated/client and restart checks passed. Static Sky bug: #116. Use one fork per instance. |
 
 Ecliptic Seasons publishes 26.3, but Rivencraft's Ecliptic integration was
 deferred and is not a replacement for the current Serene integration.
@@ -2871,3 +2872,232 @@ filtering, both dimension gates, spawn-event veto, and a real Tiki Head placemen
 retained the counts. Temporary fixtures and test worlds were removed; test servers
 were stopped. Client glyph/GUI checks and natural spawning while exploring an Age
 remain player validation. No commit, push, or publication; #102 remains open.
+
+
+### Random Page eligibility and library discovery — 1.0.1.137-beta.1
+
+The player passed .136 and authorized its publication. This slice adapts 1.21.1's
+RandomPagePolicy and random_pages allowlist/blocklist. Short paths (sky/static)
+and fully namespaced Page IDs are accepted; blocklist wins, and allowlist entries
+restrict only their own categories. Biome controllers are a separate category
+from individual biomes. Creative/JEI availability and manual book authoring are
+not filtered.
+
+Normal Link-Panel-only book creation takes one immutable policy snapshot and
+passes it through terrain, biome distribution/Page completion, environment,
+celestial kinds, material features/materials, optional formations and structures.
+Seasons use the same snapshot before their saved policy is committed. Resolved
+choices are already frozen in Age index/season data, so reload/reseed never reads
+the current lists to reselect an old Age. Authored and partly authored books use
+the existing unrestricted completion behavior, matching the 1.21.1 boundary.
+
+Required empty categories use Standard terrain, Native distribution, Normal
+lighting/weather, inherited Overworld sky, or No Seasons. Optional features or
+materials with no candidates are omitted, not filled with a forbidden random
+Page. Non-Native biome distributions preserve their required minimum using the
+terrain's preferred/native fallback pool; necessary fallback biomes can therefore
+bypass a filter. Native noise biomes come from the preset, not biome Page selection,
+and remain unfiltered just as in 1.21.1. Void still has its required Void biome.
+Cave weather/season safety overrides remain unchanged. Original unrestricted
+terrain/distribution seed choices are unchanged; filtered ranks are recalculated
+using the shared Legacy rank chooser instead of a duplicate weighted routine.
+
+Newly placed direct library Pages apply the current policy in both LEGACY and
+AGE_ONLY modes. Existing inventory contents are not rewritten. The Legacy library
+pool now includes exact Ruins templates and semantic bundled pages rather than
+reusing the Sealed Notebook's narrower pool. Sealed Notebook opening retains its
+1.21.1 pool behavior; this setting does not retroactively edit unopened/old loot.
+No policy filtering is applied to JEI or creative portfolios.
+
+Build passed. A disposable no-optional dedicated server passed 766 creation/policy
+checks over 48 seeds and six restart checks: normal book binding, manual blocked
+Page authoring, immutable saved settings under a changed policy, unload/reload,
+required category/biome fallbacks, optional empty pools, material eligibility,
+Native distinction, season policies without requiring Serene classes, library
+filtering and unchanged Creative entries. The later rank revision added default
+seed-compatibility and minimum-biome checks. These are temporary fixtures, not
+new permanent game tests. Worlds and fixtures removed, servers stopped, production
+JAR rebuilt. Player config/GUI/world validation remains pending. No commit, push
+or publication.
+
+
+### Random-Age book glyph prose — 1.0.1.138-beta.1
+
+The player passed the .137 eligibility slice. Ported 1.21.1's first-page random-Age
+glyph description: the Age name and author remain ordinary text on the left,
+followed by layered Legacy word glyphs and real base-25 numerals for terrain,
+distribution, lighting, weather and the first celestial cycle's period/angle/phase.
+Authored books keep their existing name/author front page and single-symbol middle
+pages; no writing notes or instability scores are introduced. The right-side
+animated link panel and its click-to-travel behavior are unchanged.
+
+The existing symbolcomponents.png atlas and deterministic word mappings are reused
+directly with tinted GUI_TEXTURED blits; no generated art or per-frame dynamic
+textures are added. A common prose layout helper handles Unicode word boundaries,
+numeric width and wrapping. Writing Desk tab numerals now use the same rendering
+routine, retaining their existing size/position/color.
+
+Public terrain/distribution/lighting/weather metadata is sent in the Age catalog,
+with celestial data reused from its existing saved-cycle map. These are actual
+loaded Age settings rather than a reroll from the book ID or current config.
+Metadata excludes seeds, instability scores and providers. It does not load an
+unavailable destination merely to display a book. Full catalog replacement removes
+unloaded/retired entries; logout clears description/cycle caches. Older books with
+no authored symbol component use the random-description path. Existing Age/save
+formats remain readable. Catalog network protocol is now 11 (previously 10):
+client and server must use matching builds.
+
+Build passed; disposable no-optional dedicated-server checks passed catalog
+serialization, immutable snapshots, actual saved setting capture, cache
+replacement/clear, real restart, unload/reload and retirement. Pure layout checks
+covered Legacy word splitting, Unicode, wrapping, base-25 width and oversized
+numeric fallback. Test worlds and fixtures removed, server stopped and production
+JAR rebuilt. Visual glyph layering, book/lectern appearance and actual client
+catalog receipt remain player validation. No commit, push or publication.
+
+
+
+### Renamed Immersive Portals dimension bridge — 1.0.1.139-beta.1
+
+The player passed .138. Confirmed the user's correction: the 26.3 Immersive Portal
+implementation uses the Seamless Portals name/mod ID, retaining qouteall rendering,
+chunk-loading and dimension APIs. Added an optional shared dimension-ID adapter
+before Rivencraft catalog publication/acknowledgement. It synchronizes integer
+IDs and native type/sea-level metadata without delegating Age ownership. Failed
+synchronization blocks acknowledgement/travel rather than making a successfully
+committed Age appear to have failed binding. Startup, unload/reload, reseed and
+retirement are covered. Live book/crystal rendering remains later work.
+
+The installed working build passed 35 server creation/catalog checks plus 13 after
+restart. Normal book binding, native metadata, API ID roundtrips, two Ages,
+lifecycle changes and failed-creation nonpublication were checked. No-optional
+startup passed. Real client travel remains pending; Prism files were not changed.
+
+Correction to the initial artifact audit: old CurseForge file 8937394 fails during
+its own constructor on .99 with missing DataPackRegistryEvent$NewRegistry; this is
+NOT the latest release. The latest file is 9218525, displayed as 10.0.0 while its
+filename/internal metadata still say 1.0.0. Its SHA-256 exactly matches the user's
+installed working file:
+5d2bfc2a811a6526e3f6722c521d97e5de2869a6ead1c681323c3c472e4367a0.
+The compile dependency is corrected to 9218525 in .140. The earlier broad claim
+that the current published build cannot start was wrong and is superseded here.
+
+NeoForge audit on 2026-11-11: official Maven metadata lists .102 as latest in the
+26.3 line. Its universal JAR still lacks the old NewRegistry class, so upgrading
+cannot fix that OLD portal artifact. Current target remains validated .99; a
+separate .102 build/client/server check is recommended. No release authorized.
+
+
+### Immersive Portals Reborn comparison and shared bridge — 1.0.1.140-beta.1
+
+The user suggested Reborn. Verified the NeoForge 26.3 release is 7.0.12, file
+9435354 in CurseForge project 1721833. The newer 7.0.18 is Fabric. The Reborn JAR
+registers immersive_portals_reborn plus its legacy core aliases and retains the
+qouteall GUI rendering/portal/chunk/dimension APIs. It starts on NeoForge .99
+without Cloth Config or other optional mods in the test environment.
+
+Generalized the optional bridge to recognize either Reborn or Seamless. Both
+share DimensionIntId.onServerDimensionChanged and the createFromServer packet
+factory. Seamless's createPacket returns a vanilla Packet; Reborn's returns a
+CustomPacketPayload. The adapter now wraps createFromServer in the vanilla
+clientbound payload packet, preserving each fork's native two-/three-tag wire
+format. No cross-fork packet schema is invented and neither dependency is bundled.
+The compat probe recognizes both. A development run may select
+-PwithImmersivePortalsReborn or -PwithSeamlessPortals; requesting both is rejected
+because the forks share classes/mixins. The normal build remains optional-free.
+
+Reborn passed 32 creation/catalog checks and 15 after restart: real book-binding
+entry point, two runtime Ages, ID/type metadata, native wire roundtrip, per-player
+packet preparation, unload/reload, reseed, retirement isolation and persistence.
+Seamless latest file 9218525 passed the same 32 lifecycle/packet and 15 restart checks against the shared adapter.
+These are server/packet checks, not evidence of renderer quality or real client
+packet receipt. Reborn is a viable next client-test target; no performance
+superiority is claimed. Live snapshots, chunk leases/audio isolation, and live
+crystal surfaces still need porting. Player files were not modified. Temporary
+worlds/fixtures removed; no commit, push or publication.
+
+
+### Reborn live book previews — 1.0.1.141-beta.1
+
+Linking and Descriptive Book front panels now use Immersive Portals Reborn's
+live GUI-world renderer when Reborn is installed on both sides. This carries
+forward the 1.21.1 camera orbit (11-block radius, five blocks above the focus),
+destination sky/fog, chunk streaming and remote-audio isolation. Server destination
+resolution uses the actual held book or a nearby loaded stand's matching book;
+the client cannot request arbitrary destination coordinates.
+
+A unique session ID prevents stale replies or close packets from replacing or
+releasing another book's preview. One per-player eight-chunk-radius loader streams
+the view asynchronously, renews while the book stays open, and expires if its
+heartbeat is lost. Closing, logout, death/source invalidation, dimension changes,
+and shutdown release the lease. Destination resolution for Descriptive Books
+uses the same footing/platform rules as book travel.
+
+The rendering integration uses 26.3 GPU texture views with the deferred GUI.
+Reborn may resize its target before extraction records the texture view; clearing
+is deferred to its render hook, and the normal GUI draws the image beneath the
+Legacy panel cutout. The target uses the main framebuffer's depth/stencil format.
+The player camera is restored after remote rendering, and remote preview-world
+sounds are suppressed without muting the player's world.
+
+Set `[book_previews] reborn_live_views = false` in the local configuration to use
+animated panels. Missing Reborn or unavailable terrain also retains the animated
+fallback. Seamless's dimension-ID bridge remains available, but this live GUI
+implementation is activated only for Reborn. Live crystal portal surfaces and
+preview exploration controls remain separate port work.
+
+Validation: production build passed. An isolated real NeoForge 26.3.0.99
+dedicated-server/client run with Reborn 7.0.12 displayed the remote live Linking
+Book view; screenshot inspected for the panel cutout, upright image and actual
+terrain. The client completed without a renderer exception and logout left no
+preview chunk leases. The user also reported that the books displayed live views
+perfectly. All temporary worlds/client directories and fixture sources were
+removed, and the distributable was rebuilt without test classes.
+
+Startup warnings in this isolated run included Reborn's four deprecated
+`logoFile` metadata entries; these are upstream branding metadata warnings.
+The Linux narrator also lacks `libflite`, unrelated to the book renderer.
+
+
+### Reborn live crystal portals — 1.0.1.142-beta.1
+
+Crystal portals now create optional native Reborn render-only surfaces. Each
+coplanar opening is one masked mesh on each side, including irregular outlines;
+the destination image does not repeat once per portal block. Mesh planes sit
+inside the portal block thickness so the crystal frame remains in front. Once
+native surfaces are established, LIVE_VIEW hides only the animated portal model.
+The blocks and their receptacle owner pointers stay intact.
+
+Live views share destination resolution with portal book travel. Linking Books
+use their written facing, while Descriptive Books preserve the approaching
+entity's facing as their travel path does. The reference camera is anchored to
+standing eye height above the opening's floor, rather than to its vertical center.
+This prevents taller frames from shifting the preview's arrival height. Relative
+links resolve using the opening's center as the view reference; the actual
+entity's departure position is still used for travel.
+
+Native surfaces cannot teleport entities, accept remote interaction or perform
+cross-portal collision. Existing Rivencraft collision/queue and book rules remain
+authoritative, including catalog readiness, Disarm, momentum and arrival safety.
+Reborn handles visible-destination streaming through its normal portal system.
+
+Geometry/destination tags allow maintenance to reuse matching entities and replace
+stale ones. Activation establishes views immediately; normal receptacle maintenance
+restores them after restart. Book removal, frame shutdown, missing destinations
+and disabling the integration remove the native surfaces. Without Reborn the
+animated surface and ordinary travel continue to work. The server setting is
+[book_previews] reborn_crystal_live_views, default true.
+
+Validation on NeoForge 26.3.0.99 / Reborn 7.0.12: 68 server checks passed, covering
+all three plane axes, both sides, one mesh per opening, eye-position and facing
+transforms, entity reuse, fallback toggling and book removal. Five additional
+restart checks passed. An isolated real client/dedicated server rendered the live
+opening, then crossed into the correct Age through normal Rivencraft travel.
+Screenshots before/after were inspected; the user also reported success.
+
+An initial render test mistakenly bound its synthetic Linking Book at Y=1 inside
+the flat world's solid layers. The view correctly displayed underground terrain
+and the collision check refused travel. The corrected fixture bound to the actual
+surface (Y=4) and passed. No production spawn-height workaround was added for an
+invalid synthetic book. All temporary fixtures and test worlds were removed, and
+the distributable was rebuilt without test classes.