Guide

[CHANGELOG] Version 1.5.1 (NeoForge)

Sort Order, Backgrounds, Chat Commands, Item Binding, Gating & Full-Text Search

🔧 Hotfix:

• Dedicated Server Crash — Version 1.5.0 crashed on dedicated servers during startup (Attempted to load class net/minecraft/client/gui/screens/Screen for invalid dist DEDICATED_SERVER). Client-only UI code was referenced directly inside the gating packet handler, and the loader's dist-scanner rejected it on the server side. The code has been moved into a separate @OnlyIn(Dist.CLIENT) class. Single-player and LAN were unaffected.

🛠️ Changes:

• Book Sort Order — New optional index field in book.json. Books are sorted by this value (lower = earlier). Books without index fall to the end, sorted by namespace. Modpack authors can now control the order of books in the selector.
• Custom Chapter Backgrounds — Themes can now define a chapterBackground block with either a solid color (adjustable alpha) or an image. Images can come from a local file, a server-side file, or a direct URL (downloaded and cached automatically). The background covers the whole chapter area and replaces the default blur overlay.
• Wildcard Item Binding — @bind:modid:* binds every item of a mod namespace to a chapter in one line. Ideal for modpack guides with hundreds of items. Safety limit of 4096 items per wildcard.
• Tag-Based Item Binding — @bind_tag:forge:stone binds every item carrying the given tag. Works across mods automatically: forge:stone catches stone from vanilla and from any installed mod. Tag and wildcard entries can be mixed in the same chapter.
• /guide list — Lists available books with their index, namespace, dev marker and display name. Click a line to insert /guide open <namespace> into chat; hover for details (ID, default chapter).
• /guide list server — Server-side list of books that will be distributed to players. Shows index, namespace, dev marker, display name and hover info (ID, dev flag, disk path).
• /guide open <namespace> — Opens a book by namespace directly from chat. Supports tab-completion over visible books.
• Book Gating (unlock_tag) — Books can be hidden behind a per-player tag. Add unlock_tag to book.json, then grant or revoke it with /guide unlock <tag> / /guide lock <tag>. New /guide unlocks lists your tags. Syncs on login and after every change; works with KubeJS, FTB Quests and advancements.
• Full-Text Search Overlay — The sidebar search now scans chapter content, not just titles. Typing a query opens an overlay panel with snippets around every match, grouped by chapter. The sidebar also keeps chapters that only match by content. Click a snippet to open the chapter, scroll to the matched line, and highlight the query in-place.
• In-Chapter Search (Ctrl+F) — Browser-style find panel opens with Ctrl+F at the bottom of the chapter area. Every match is highlighted (active one in a different color); the ↑ / ↓ buttons or Enter / Shift+Enter jump between matches, with a live N / M counter. Esc closes the panel; a second Esc exits the book. Sidebar search and the Ctrl+F panel work independently and route keyboard focus correctly between each other.
• Themeable Search Highlight — Two new theme colors: searchHighlightColor (all matches) and searchHighlightCurrentColor (active match). Built-in palettes ship with tuned defaults per theme (standard, blood, cyber_tech, forest, honey, matrix, sakura).
• Spoiler-Aware Search — While a search query is active, spoilers containing a match are auto-expanded; spoilers without a match stay collapsed. Chapter height is recomputed on every keystroke so the scrollbar stays accurate.
• Localized Search Panel & Projection Tooltip — Ctrl+F panel placeholder, ↑ / ↓ / ✕ button tooltips, overlay footer, and the Projection button tooltip are now localized (EN / RU).

🐛 Fixes:

• Crash on Invalid Book Folder Names — Folders inside config/guide/books/ with characters not allowed in a Minecraft namespace (for example, guide — copy created by the OS) no longer crash the game. They are skipped with a warning in the log instead.
• Unified Image Loader — Minecraft 1.21+ rejects any image that is not a strict PNG in NativeImage.read. All guide image loading (chapter backgrounds, book icons, control icons, @image: tags, theme palette) now goes through a universal reader that accepts PNG, JPEG, BMP and GIF (first frame). JPEG backgrounds and icons no longer fail with "Bad PNG Signature".
• Theme Selector Shake Fix — Chapter background no longer shakes along with the UI when the shake effect triggers. Only buttons and title animate; the background stays static, eliminating see-through gaps at screen edges.
• Collapsed Spoiler Chapter Height — Chapter height now ignores content of collapsed spoilers, eliminating large empty gaps at the end of chapters with heavy spoiler content (JSON examples, code blocks).
• End-of-Chapter Text Clipping — Scroll offset is clamped to the recomputed max scroll on every redraw, so the last lines of a chapter are no longer cut off — especially when toggling spoilers or opening Ctrl+F mid-chapter.
• Scroll Jump on Sidebar Search — Typing in the sidebar search box no longer resets the chapter scroll position to the top.
• Search Field Focus Routing — Keyboard focus between the sidebar search box and the Ctrl+F panel is now routed through Screen.setFocused, so clicking one reliably transfers focus and text input goes to the right field.
• Wrapped Links Stay Clickable — Links that wrap onto a new line (typically at high GUI Scale) now register one clickable region per wrapped segment instead of losing interactivity on the wrapped line.
• Bold-Aware Search Highlight — Highlight boxes for search matches now account for the extra width of bold (§l) glyphs, so matches on mixed-style lines are underlined pixel-perfectly.
• Copy Toast Overlap with Search Panel — The "Copied" toast is now centered above the Ctrl+F panel instead of overlapping it.
• Video Height Accounting — Video blocks contribute their declared width (from @video: parameters) to chapter height, so text below a video is no longer clipped.
• Search Overlay at High GUI Scale — The full-text overlay now scales its width to the available content area (never overlaps the sidebar), clamps snippets to panel width with ellipsis on both sides, truncates the footer counter, and no longer leaks the chapter tooltip or top-row tooltips through the panel.