docs(RouterOptions): note negative zero "-0" stays a string under numberFormat auto (#898)

greydragon888 committed Jun 21, 2026

docs: routes.update patches custom route fields (#797) Document custom-field patching on getRoutesApi().update — merge semantics, hot-swap examples (lifecycle/preload/searchSchema), lazy pickup, and the custom-field-only TREE_CHANGED-silent rule.

greydragon888 committed Jun 21, 2026

docs(createRouter): note logger is process-global, last-write-wins (#790) - Expand the Side Effects bullet: process-global singleton, last createRouter wins, SSR caveat, options not mutated; link to RouterOptions

greydragon888 committed Jun 21, 2026

docs: remove dead logger cross-field diagnostic (#789) - Drop the unreachable "callbackIgnoresLevel without callback" row from the RouterOptions cross-field table + note that logger config is validated by core at construction, not by the validation plugin - Trim the dead logger clause from validation-plugin's Options row

greydragon888 committed Jun 21, 2026

docs(RouterOptions): document warnListeners limit (#752)

greydragon888 committed Jun 20, 2026

docs(canNavigateTo): document missing-param returns false, not throw (#725)

greydragon888 committed Jun 20, 2026

docs(RouterOptions): note logger is a process-global singleton (#724)

greydragon888 committed Jun 20, 2026

docs(areStatesEqual): note URL-param cache invalidation on tree mutations (#723)

greydragon888 committed Jun 20, 2026

docs(leave): clarify subscribeLeave signal aborts only on cancellation (#722)

greydragon888 committed Jun 20, 2026

docs(rx): fix RouterEvent + document RxObservable, subscribe contract, types - RouterEvent union was missing TRANSITION_LEAVE_APPROVE, which events$ actually emits (LEAVE_APPROVED phase) -- add the variant and a note - add an RxObservable<T> class section: constructor, subscribe() contract (observer or bare next; returns Subscription { unsubscribe, closed }), ObservableOptions (signal / replay), and package-wide error/terminal semantics (non-terminal error, console.error fallback, teardown exactly once) - add a Types section covering the 8 public exports - note debounceTime throws RangeError on negative/NaN/non-finite duration

greydragon888 committed Jun 19, 2026

docs(rx): note non-terminal error divergence from TC39/RxJS (#775) Soften "TC39 Observable-compliant" to "TC39-style" and document that error() is non-terminal — the subscription stays open, values keep flowing, and only complete()/unsubscribe() are terminal.

greydragon888 committed Jun 19, 2026

docs(rx): note async iterator terminal-batch delivery (#774) Document that the final value emitted right before completion is still delivered, and a synchronous error is propagated to the for-await loop.

greydragon888 committed Jun 19, 2026

docs(rx): note state$ replay ordering vs sync navigation (#771) Document that a synchronous navigation right after subscribe suppresses the deferred replay, so subscribers never receive the stale pre-navigation state out of chronological order.

greydragon888 committed Jun 19, 2026

docs: factory-pool last-wins caveat for URL plugins (#758) Document that a factory reused across concurrently-live routers tracks popstate/navigate only in the last-started router (browser-plugin, hash-plugin, navigation-plugin). For concurrent routers, use one factory each.

greydragon888 committed Jun 19, 2026

docs(memory-plugin): short-circuit back/forward emits no transition event (#808) Correct the #508 gotcha: a same-path short-circuit rewrites context.memory in place for synchronous reads, but emits no TRANSITION_SUCCESS — router.subscribe listeners and framework adapters are not notified (previously claimed they "receive the same signal").

greydragon888 committed Jun 19, 2026

docs(memory-plugin): note same-tick back()+navigate() records a fresh push (#807)

greydragon888 committed Jun 19, 2026

docs: clarify start() keeps committed state on post-commit interceptor reject (#763) - start.md: a start-interceptor rejection after commit no longer un-starts the router; corrected "router remains not started" and added a matching guarantee - ssr-data-plugin.md / rsc-server-plugin.md: a loader throwing on the start() path leaves the router started (isActive() stays true); only the start() promise rejects, on SSR the per-request router is discarded

greydragon888 committed Jun 19, 2026

docs: fix navigateToState signature + TRANSITION_ERR misconception across pages Completeness sweep after the navigateToState.md correction — more pages carried the same two stale claims: - navigate.md + matchPath.md: examples showed the removed 3-arg navigateToState(state, fromState, opts); corrected to (state, opts). matchPath.md passed router.getState() as the middle arg, which the prior regex sweep missed because the nested () defeated the pattern. - navigation-lifecycle.md: error table + prose claimed a thrown guard yields TRANSITION_ERR exposed via error.getField('originalError'). A thrown/rejected guard actually rejects with its phase code (CANNOT_ACTIVATE / CANNOT_DEACTIVATE); message is on error.message, cause on error.cause. Dropped the bogus row, reworded the guard rows. - error-codes.md: TRANSITION_ERR "When thrown" listed guard/lifecycle causes and a fabricated originalError field. Reframed as a reserved code the navigation pipeline does not emit; example now matches CANNOT_ACTIVATE and reads error.cause. Verified against core: errorCodes.TRANSITION_ERR is never thrown anywhere in src; guard throws route through rethrowAsRouterError -> setCode(CANNOT_*).

greydragon888 committed Jun 19, 2026

docs(navigateToState): fix async-error table — guard throws map to CANNOT_*, not TRANSITION_ERR A thrown/rejected guard surfaces under its phase code (CANNOT_ACTIVATE / CANNOT_DEACTIVATE) via rethrowAsRouterError → setCode, with the thrown error's message/cause preserved. errorCodes.TRANSITION_ERR is reserved and never produced by the navigation pipeline, so drop the misleading row and note that guard failures do not emit a separate TRANSITION_ERR.

greydragon888 committed Jun 19, 2026

docs(navigateToState): correct signature to (state, options?) — drop nonexistent fromState arg The page documented a stale 3-arg form `navigateToState(toState, fromState, opts)`. The real plugin API is `navigateToState(state, options?)` (core-types api.ts): the router derives the previous state internally from `router.getState()`, so there is no `fromState` parameter. Fix the signature, parameter table, sync-error table, pipeline diagram, all examples, and the migration snippet accordingly.

greydragon888 committed Jun 19, 2026

docs(navigation): note guard-block log suppression on fire-and-forget (#721) CANNOT_ACTIVATE / CANNOT_DEACTIVATE are now suppressed by the fire-and-forget safety net, so a guard-blocked navigateToDefault()/start() no longer emits a spurious "Unexpected navigation error" log. Update the fire-and-forget guarantees on navigateToDefault.md and start.md accordingly.

greydragon888 committed Jun 18, 2026

docs(navigateToDefault): document fire-and-forget safety guarantee (#721) Add a Guarantees bullet noting that calling navigateToDefault() without await internally suppresses expected rejections (ROUTE_NOT_FOUND for an unset/empty defaultRoute, plus SAME_STATES / TRANSITION_CANCELLED / ROUTER_NOT_STARTED), matching navigate(). Reflects the core fix for #721.

greydragon888 committed Jun 18, 2026

docs(Route): a marker must be named — bare ':'/'*' rejected at registration (#858)

greydragon888 committed Jun 18, 2026

docs(RouterOptions): empty-true false decodes to boolean (#743)

greydragon888 committed Jun 17, 2026

docs(RouterOptions): numberFormat auto now coerces negatives (#742)

greydragon888 committed Jun 17, 2026

docs(getTree): drop removed staticPath field from RouteTree shape `RouteTree.staticPath` was removed as a dead cache (route-tree #748); the tree returned by `getTree()` no longer carries it.

greydragon888 committed Jun 17, 2026

docs(getTree): document paramMeta freeze and constraintPatterns Map exception Clarify that the deeply-frozen tree now includes the nested paramMeta object and its urlParams/queryParams/spatParams arrays, and note that constraintPatterns is a ReadonlyMap (compile-time only, not runtime-frozen). Aligns with route-tree #747.

greydragon888 committed Jun 17, 2026

Add Routes Mutation Event (subscribeChanges) page New page documenting getRoutesApi(router).subscribeChanges(): overview, payload union, use cases (DevTools, microfrontend, plugin cache invalidation), guarantees, and the shallow-immutability / read-only caveat. Linked from _Sidebar, addRoute, extendRouter, and plugin-architecture.

greydragon888 committed Jun 8, 2026

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: duplicate-registration contract for subscribe / subscribeLeave / addEventListener (#662) Add explicit "Duplicate Registration — Independent" section to subscribe.md and leave.md, with cross-link to addEventListener.md's new "Strict Contract" callout. Documents the asymmetry that has been implicit since the start: end-user subscribe / subscribeLeave silently accept duplicates (UI bindings legitimately re-register); plugin-author addEventListener throws on same-reference duplicate. leave.md also gains a "Payload Immutability" note matching the `Object.freeze` landed in core (#662). Mirrors the JSDoc in `EventBusNamespace.subscribe` / `.subscribeLeave` / `.addEventListener`.

greydragon888 committed May 23, 2026