docs: add Scroll Spy page + cross-link across hash, scroll-restoration, 6 adapters (#575) NEW Scroll-Spy.md — flagship page (~350 lines) symmetric with Scroll-Restoration.md and View-Transitions.md: * Why not a plugin (DOM-agnostic core, IntersectionObserver = DOM) * Opt-in syntax for all 5 web adapters + Angular DI * Options table (selector / rootMargin / scrollContainer) + hardcoded internals (threshold, debounce, cooldown) * Behavior matrix per event (user scroll, Link hash click, F5, stale hash, same-hash skip, self-emit guard) * Anti-flicker architecture deep-dive (isTransitioning + coolingDown + selfEmitting; scrollend Baseline 2026; 500ms fallback timeout) * Plugin compatibility (browser/navigation full; hash/memory/no-URL warn-once + NOOP) * Self-healing on init for stale hashes (/page#nonexistent) * Filtering hash-only transitions idiom (RFC §13 user-land filter pattern + pipeline cost table) * Three recipes (Custom IO alongside spy, Per-route config, TOC sidebar in ~30 LOC) * 8 edge cases / known limitations * Comparison table with Link hash and Scroll-Restoration anchor scrolling UPDATED Hash.md — expanded "Comparison: Hash Features" into a 3-column table (Link hash / anchorScrolling / createScrollSpy) + new "Filtering Hash-only Transitions" section documenting the user-land filter that applies to all three sources of hashChanged: true (clicks, popstate, spy emits). Lists which pipeline phases fire on hash-only transitions (subscribe yes, onStay/onNavigate yes, guards no, onLeave/onEnter no). UPDATED Scroll-Restoration.md — added scroll-spy emit row to the "Behaviour change under browser-plugin" matrix (replace: true → skip, no magnetic snap) + cross-link in See Also. Foundation #648 closure now applies to spy emits. UPDATED RouterProvider.md — added scrollSpy row to the props table + full subsection between scrollRestoration and viewTransitions (options table, per-framework code, plugin compatibility note). UPDATED 6 adapter integration pages (React, Preact, Solid, Vue, Svelte, Angular) — scrollSpy mention in the Components table + per- framework code block with reactivity notes specific to that adapter (React/Preact useEffect with primitive deps, Solid dedicated onMount block, Vue watchToggleableUtility now four utilities, Svelte $effect + $derived + untrack, Angular bootstrap-time snapshot via provideEnvironmentInitializer + installScrollSpy). UPDATED Navigation-Plugin.md — expanded "Router-driven mutations re- enter the navigate handler" edge case to document the event.intercept({ scroll: "manual" }) override that closes the scroll-spy + slow user scroll viewport-jump bug. Cross-links to Hash, Scroll-Restoration, and Scroll-Spy in See Also. UPDATED Home.md — added Scroll Spy bullet alongside Scroll Restoration in the concept overview. UPDATED Ink-Integration.md — added scrollSpy row to the "feature unavailable in terminal" table (symmetric with scrollRestoration: DOM-only, no terminal equivalent). UPDATED recipes.md — added companion blockquote in Scroll Restoration section pointing to Scroll Spy for the opposite direction (scroll → URL) with TOC sidebar pattern hint. UPDATED _Sidebar.md — added Scroll Spy link in DOM Utilities section (alphabetically between Scroll Restoration and View Transitions). Closes destination-404 gap: README/CLAUDE/IMPLEMENTATION_NOTES across 17 files in the main monorepo already link to wiki/Scroll-Spy. UPDATED Link.md — retargeted link-hash example URL to its new location in hash-examples/ subgroup (aligns with PR #695 commit chore(react): move link-hash + scroll-restoration into hash-examples). Total: 1 new flagship page + 15 cross-linked updates. Companion to real-router monorepo PR #695 — scroll-spy implementation, examples, docs, and adapter wiring. Refs greydragon888/real-router#575

greydragon888 committed Jun 2, 2026

docs(navigation-plugin): same-URL guard + PLUGIN_SYNC_INFO sentinel (#580) Replace the SyncingFlag / wrapNavigationBrowserWithSyncing / isSyncingFromRouter bullet in Edge Cases with the new identity-based mechanism (PLUGIN_SYNC_INFO on event.info), and add a separate bullet documenting the same-URL guard behavioural consequence: same-URL transitions no longer fire navigate events; consumers branching on those for state-only changes must use router.subscribe instead. Includes the WKWebView cross-document reload context that motivated the fix and the URL canonical-equivalence rule (scheme://host ≡ scheme://host/).

greydragon888 committed May 18, 2026

docs: hash fragment support — new Hash page + cross-references (#532) Wiki side of #532 stage 4. New `Hash.md` is the public design + API reference; existing pages get cross-references and table widening. - Hash.md (new, ~270 lines): Overview, Architecture (state.context.url namespace, mutual exclusivity), API surface (tri-state opts.hash, buildUrl, replaceHistoryState, hashChanged signal), per-framework <Link hash> snippets, Tab UI walkthrough, Cross-Path preserve, F5 lazy hash read, browser-driven hash-only nav, hash-aware active state & stabilizeState, hash-plugin limitation, scroll-restoration comparison - Link.md: hash row in props table + Hash Fragment Navigation section with all 6 frameworks - State.md: built-in context namespaces table — `url` row alongside navigation/browser/memory/etc. - browser-plugin.md / Navigation-Plugin.md: state.context.url subsection, extension table widening, mutual exclusivity note - hash-plugin.md: limitations bullet (warn-once, structural incompatibility) - Scroll-Restoration.md: anchorScrolling reads from state.context.url.hash with DOM fallback; new "Hash Source Resolution" subsection - _Sidebar.md: Hash link under Concepts

greydragon888 committed Apr 29, 2026

docs: update Navigation-Plugin for #524 (forceDeactivate default, RouterError sync) Aligns wiki with plugin changes introduced in #524: - Configuration Options table: `forceDeactivate` default flipped from `true` to `false`. Added migration note for apps that relied on the old bypass. Configuration example updated to reflect the new contract. - "CANNOT_DEACTIVATE auto-rollback" edge-case rewritten as "CANNOT_DEACTIVATE / RouterError URL sync" — explains the new syncUrlToRouterState path: on any RouterError the plugin calls browser.navigate(url, {history:"replace"}) to the current router state, keeping URL and state consistent in a single visible transition. Explains why manual sync is used instead of Navigation API's native rollback on intercept rejection (headless/cross-origin reliability). - "Error recovery" entry updated to reflect the shared syncUrlToRouterState helper now used by both paths (RouterError and non-RouterError). From navigation-plugin review (.claude/review-2026-04-23.md, HIGH #1 + #2).

greydragon888 committed Apr 23, 2026

docs: add Desktop Integration guide (#496) - Desktop-Integration.md: plugin × runtime compatibility matrix (10 OS rows × 4 plugins), Electron custom protocol (app://) and file:// + hash fallback setup, Tauri v2 setup with Navigation API caveat and WebKit OS matrix, plugin selection decision tree, three troubleshooting scenarios, links to 5 runnable examples. - _Sidebar.md: +1 link in integration guides group (Ink + Desktop are both non-browser runtime guides). - Navigation-Plugin.md: new Desktop compatibility section explaining the WebView OS matrix + fail-fast factory behavior on unsupported WebKit.

greydragon888 committed Apr 22, 2026

Sync docs with #483 — strict-mode unified behavior - RouterOptions.md: allowNotFound section rewritten to describe the unified contract across start() / popstate / Navigation API events, with the userland migration snippet. Cross-Field Constraints section updated — the dead-end case `{ allowNotFound: false, defaultRoute: "" }` is resolved because defaultRoute is no longer consulted as an implicit fallback. - browser-plugin.md / Navigation-Plugin.md / hash-plugin.md: Edge Cases section updated with the new strict-mode semantics (emit $$error → URL rollback → router state unchanged). - migration-guide.md: new "Strict Mode no longer silently redirects" section with the userland migration snippet. Files also contain pre-existing in-progress edits to unrelated sections.

greydragon888 committed Apr 20, 2026

docs: add State Context (state.context.*) across all plugin pages Updated State.md, plugin-architecture.md, Navigation-Plugin.md, ssr-data-plugin.md, browser-plugin.md, memory-plugin.md, persistent-params-plugin.md, ssr.md with claim-based API documentation.

greydragon888 committed Apr 11, 2026