@bgub/fig-tanstack-router 0.0.0-tegami-trusted-publish-setup → 0.1.0-alpha.2

package/CHANGELOG.md

@@ -0,0 +1,183 @@
+## @bgub/fig-tanstack-router@0.1.0-alpha.1
+
+### Add the TanStack Router adapter for Fig
+
+`@bgub/fig-tanstack-router` now supplies code-route creation, a Fig router
+provider and outlet, router hooks, native anchor links, route preloading, and a
+private reactive-store bridge for `@tanstack/router-core` 1.171.15.
+
+### Prioritize render-blocking document assets
+
+Full-document rendering now emits parser- and security-sensitive metadata,
+connection hints, critical font and image preloads, and stylesheets before
+ordinary metadata and lower-priority JavaScript hints. TanStack Router matches
+also register authored links and manifest stylesheets before their generated
+module preloads, so render-blocking CSS begins loading earlier without changing
+stylesheet order.
+
+### Remove `useLoaderData`; enforce void loaders for data-backed routers
+
+The adapter no longer exposes `useLoaderData` (standalone, route-bound, or via
+`getRouteApi`): the Fig data store is the single route-data cache, so loader
+values are read with `readData` against the same resource the loader ensured.
+`useLoaderDeps` remains — deps are loader orchestration, not a cache.
+
+In dev builds, a match that commits with `loaderData` set while
+`router.context.data` is configured now throws a diagnostic naming the route.
+Derive navigation-scoped values from `useLoaderDeps`, search params, or
+`beforeLoad`-returned route context. Routers created without `context.data`
+keep Router Core's native loader semantics untouched.
+
+### Build generated TanStack Start file routes with Fig
+
+`@bgub/fig-tanstack-router` now implements generated file routes, lazy route
+records, lazy components, and lazy loader functions. TanStack Start builds and
+reloads those routes in development through its existing generator and code
+splitter.
+
+`@bgub/fig-tanstack-start` now exposes Start configuration and middleware
+factories. Its demo covers request-isolated middleware context, server and
+client redirects, generated error and not-found routes, split chunks, SSR,
+hydration, and server-function mutations.
+
+### Add canonical bound route APIs
+
+Fig routes and `getRouteApi` now provide bound match, params, search,
+loader-deps, loader-data, context, navigation, link, and not-found helpers. The
+adapter also adds active-match selection, reactive route matching,
+`MatchRoute`, and declarative `Navigate` APIs.
+
+### Expand TanStack Router hook and link parity
+
+Router selectors now honor structural sharing, including the router-wide
+default, and support selected locations plus loose or optional match reads.
+Links gain composable active and inactive props and render-function children
+with active and transitioning state. `linkOptions` and `createRouteMask` add
+zero-wrapper helpers for reusable, type-checked navigation options. A
+published compatibility matrix now distinguishes the guaranteed Start surface
+from compatibility, deferred, and deliberately omitted APIs.
+
+### Complete Fig-native data and navigation patterns
+
+TanStack Start routes can now preload Payload data and return immediately,
+letting Fig Suspense stream the result and its asset resources without copying
+values into Router loader data. Initial Payload responses registered after the
+document shell starts are embedded before hydration, preventing a duplicate
+client request.
+
+The Router adapter adds modern object-only `useBlocker` and reactive
+`useCanGoBack` hooks, makes the concrete Router and RouteApi constructors
+internal, and rejects unsupported proximity preloading in `LinkProps`.
+Fig's structural `ViewTransition` remains the sole document-transition owner,
+even when a TanStack navigation carries its `viewTransition` option.
+
+### Make data resources the router's default external cache
+
+Put `root.data` in router context, return `ensureRouteData` from loaders, and
+read the same resource with `readData` in components. Data-backed routers now
+default `defaultPreloadStaleTime` to `0`, the loader helper resolves to `void`
+so the value is not duplicated in `loaderData`, and route reset invalidates
+attributed Fig data errors before re-running the router. The adapter also
+renders Router Core's global not-found state through the root outlet.
+
+### Complete route match rendering semantics
+
+Route matches now honor pending delay and minimum duration, route and default
+remount dependencies, explicit Suspense wrapping, client-only and data-only SSR
+policies, redirects, and router-level error reporting. Scroll restoration is
+installed idempotently and emits its Start SSR bootstrap once.
+
+### Keep outgoing route hooks valid through unmount
+
+Route-scoped hooks now retain their mounted match while navigation replaces the
+active match list. Outgoing routes can subscribe to router state without
+throwing during browser back navigation and clearing the rendered page.
+
+### Settle Router navigation through Fig transitions
+
+`RouterProvider` now merges partial options and route context before the first
+loader runs. Browser navigation uses Fig transitions, publishes Router's load,
+mount, resolved, and rendered lifecycle events in order, ignores superseded
+navigation completions, and keeps `isTransitioning` accurate while an
+asynchronous navigation settles.
+
+Hydration skips duplicate initial loads, canonical validated locations replace
+the browser URL, and provider unmounts release history and transition bindings.
+
+### Give each matched route ownership of its Fig assets
+
+Route stylesheets, preload hints, preconnects, font preloads, and async scripts
+now enter Fig's shared asset registry at the matched subtree. This gives Start
+streaming, client navigation, and Payload assets one deduplicating ownership
+model while title, meta, inline styles, JSON-LD, and synchronous scripts retain
+their declared document positions.
+
+Manifest `assetCrossOrigin` configuration now belongs to `createRouter`
+options, where it is available before the root match renders.
+
+### Define the Start-first Router support contract
+
+The Router adapter now documents generated TanStack Start file routes as its
+primary interface, distinguishes supported code-created routes from deferred
+or deliberately omitted adapter conveniences, and clarifies when route data
+belongs in Fig data resources versus Router `loaderData`. The package also
+declares itself side-effect-free and guards the production Start-oriented
+surface with a bundle-size limit.
+
+### Preserve framework-managed asset placement
+
+Framework adapters can now keep externally managed head and body tags in their
+declared positions without exposing a DOM prop. TanStack Router uses this for
+route-managed links, styles, and scripts while continuing to map title and meta
+entries through Fig asset resources. Full-document hydration now ignores the
+doctype and one shared marker identifies every server-owned node without a
+client fiber. Declarative asset lists also gain a client commit lifecycle, so
+route titles and metadata update during navigation.
+
+### Add Payload routes to the TanStack Start adapter
+
+`@bgub/fig-tanstack-start/payload` now exposes `payloadResource`, which compiles
+an inline render callback into a private server function and Fig-owned route
+data resource. Applications supply the cache key and component tree without
+authoring transport plumbing. The shared declaration can stay in one
+`.payload.tsx` module; its render callback and render-only imports are omitted
+from the browser build. The initial SSR response is embedded into the document
+and adopted without refetching; client navigation and refresh use the same
+resource request path. Payload data rows
+hydrate the shared store, asset resources are retained on their owning server
+segments or inserted through the browser registry, and client references retain
+their resolver-defined identity. `decodePayloadStream` and `payloadDataLoader`
+now expose `retainAssets` for server document renderers that need this delivery
+path.
+
+`@bgub/fig-tanstack-start/server` exposes the lower-level
+`renderPayloadResponse` used by the generated TanStack server function; it
+defaults its render abort signal to the incoming request, so a disconnected
+client cancels the Payload render. Shell
+HTML streams while outlined Suspense holes settle, and the completed initial
+responses are embedded before TanStack starts full-document hydration. The Vite
+adapter also publishes assets imported only by server modules into the client
+build output. Fig Router links also consume TanStack's `viewTransition`
+navigation option without forwarding it as an invalid attribute to the rendered
+anchor, and derive active state from the resolved route instead of an in-flight
+location.
+
+### Add the TanStack Start runtime adapter
+
+`createDataStore` now creates a root-neutral Fig store that route loaders can
+populate before a renderer exists. Server and client renderers adopt that exact
+store, preserving one cache while attaching their lifecycle and scheduling.
+
+The new TanStack Start runtime uses the store for route loading, server
+rendering, Fig-owned document serialization, client deserialization, and
+hydration. Route-managed head and script output maps through the Router adapter,
+including Fig asset resources. The end-to-end contract verifies no initial
+client refetch and exactly one reload after invalidation.
+
+## @bgub/fig-tanstack-router@0.1.0-alpha.0 (alpha)
+
+### Initial alpha release
+
+First public alpha release of the TanStack Router adapter for Fig.
+
+# Changelog

package/COMPATIBILITY.md

@@ -0,0 +1,65 @@
+# TanStack Router compatibility
+
+`@bgub/fig-tanstack-router` targets the APIs used by generated TanStack Start
+applications. It is not intended to reproduce every convenience or deprecated
+alias from another framework adapter.
+
+The conformance target is `@tanstack/router-core@1.171.15`. The owning
+[concept document](https://github.com/bgub/fig/blob/main/docs/concepts/tanstack-router.md)
+defines the detailed contracts and rationale; this page is the quick
+compatibility reference.
+
+## Support levels
+
+- **Guaranteed** — part of the adapter's supported Start-first interface and
+  covered by its conformance tests.
+- **Compatibility** — supported, but not the recommended authoring path for a
+  new TanStack Start application.
+- **Deferred** — useful framework-adapter convenience that may be added later.
+- **Omitted** — intentionally replaced by a Fig primitive or excluded from the
+  adapter's contract.
+
+## Compatibility matrix
+
+| Area                         | Level         | Support                                                                                                                                                  |
+| ---------------------------- | ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Generated routes             | Guaranteed    | `createFileRoute`, `createLazyFileRoute`, generated-tree mutation and type registration, `lazyRouteComponent`, and `lazyFn`                              |
+| Code-created routes          | Compatibility | `createRootRoute`, `createRootRouteWithContext`, `createRoute`, and `addChildren`; generated file routes remain recommended                              |
+| Router setup                 | Guaranteed    | `createRouter`, `RouterProvider`, route context, router option updates, browser/memory/hash history, and hydration-aware initial loading                 |
+| Route APIs                   | Guaranteed    | Route-bound hooks, `Link`, `notFound`, and `getRouteApi`                                                                                                 |
+| State and match hooks        | Guaranteed    | Router state, location, matches, match testing, match values, params, search, loader data/deps, route context, and navigation                            |
+| Hook options                 | Guaranteed    | Selectors, structural sharing, router-wide default structural sharing, `strict: false`, and optional match/params/search reads with `shouldThrow: false` |
+| Navigation                   | Guaranteed    | Imperative and declarative navigation, redirects, route masks, navigation blocking, back-history state, and Router Core lifecycle events                 |
+| Links                        | Guaranteed    | Native anchors, active/inactive props, render-function children, per-link transition state, disabled links, and native click semantics                   |
+| Link preloading              | Guaranteed    | Intent, render, and viewport preloading                                                                                                                  |
+| Proximity preloading         | Deferred      | `preloadIntentProximity` is rejected by `LinkProps` rather than silently ignored                                                                         |
+| Pending and errors           | Guaranteed    | Pending timing, minimum pending duration, Suspense boundaries, remount dependencies, route errors, reset, and not-found handling                         |
+| Start SSR                    | Guaranteed    | Route-level `ssr` policies, hydration, head output, scripts, nonce propagation, and the Start data snapshot                                              |
+| Asset resources              | Guaranteed    | Matched-route stylesheets, preloads, module preloads, preconnects, font preloads, and external async scripts                                             |
+| Data resources               | Guaranteed    | `ensureRouteData` and Start context integration for Fig-owned caching, hydration, invalidation, and streaming                                            |
+| Scroll restoration           | Guaranteed    | Router-level document scroll restoration and its Start SSR bootstrap                                                                                     |
+| Element scroll restoration   | Deferred      | `useElementScrollRestoration` is not exported                                                                                                            |
+| Parent/child match selectors | Deferred      | `useParentMatches` and `useChildMatches` are not exported; use `useMatches({ select })` when practical                                                   |
+| Custom link construction     | Deferred      | `useLinkProps` and `createLink` are not exported; use the native `Link` interface                                                                        |
+| View transitions             | Guaranteed    | Fig `<ViewTransition>` boundaries own structural animation; Router Core's document-level wrapper is disabled to prevent nesting                          |
+| Activity keep-alive          | Omitted       | Navigation transitions preserve the visible tree while loading, but resolved navigation replaces it instead of retaining inactive routes                 |
+| Deprecated APIs              | Omitted       | Deprecated blocker overloads, compatibility classes, and aliases are not part of the adapter interface                                                   |
+
+## Fig-owned equivalents
+
+Some framework-adapter components would duplicate existing Fig behavior, so
+they are deliberately not exported:
+
+| TanStack adapter convenience   | Fig contract                                                                                       |
+| ------------------------------ | -------------------------------------------------------------------------------------------------- |
+| `Await`                        | `readPromise` inside `Suspense`                                                                    |
+| `CatchBoundary`                | Fig `ErrorBoundary` plus route error/reset integration                                             |
+| `ClientOnly`                   | The adapter's internal hydration gate for route SSR policies                                       |
+| `ScrollRestoration`            | Automatic router-level setup through `createRouter` or `RouterProvider`                            |
+| Activity-based inactive routes | No equivalent yet; this requires an explicit keep-alive state, effect, and data-ownership contract |
+
+## Version upgrades
+
+Upgrading the Router Core pin is a conformance change. Generated-route,
+navigation, SSR, data, asset, and document tests must pass against the new
+version before the supported target moves.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) Ben Gubler
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,6 +1,289 @@
-# Placeholder package
-  
-  This empty package was published by [Tegami](https://tegami.fuma-nama.dev) to configure npm trusted publishing.
-  
-  The real package contents will be published via CI with OIDC.
-  
+# @bgub/fig-tanstack-router
+
+The Fig framework adapter for TanStack Router. Route matching, loaders,
+navigation, and history come from `@tanstack/router-core`; this package adds
+the Fig components, hooks, native links, asset mapping, and reactive store
+bridge used by TanStack Start.
+
+Generated file routes are the recommended interface. Code-created route trees
+remain supported for standalone use, but they are not the design center.
+
+## Installation
+
+```bash
+pnpm add @bgub/fig-tanstack-router @bgub/fig @bgub/fig-dom @tanstack/router-core
+```
+
+For TanStack Start, also install `@bgub/fig-tanstack-start` and use its Vite
+plugin and default entries. See the
+[`@bgub/fig-tanstack-start` guide](../fig-tanstack-start/README.md) for the
+complete build and hydration setup.
+
+## Recommended: generated file routes
+
+TanStack Start generates `routeTree.gen.ts` from the files under `src/routes`.
+Create one router and one root-neutral Fig data store around that generated
+tree:
+
+```tsx
+// src/router.tsx
+import { createStartDataContext } from "@bgub/fig-tanstack-start";
+import { createRouter } from "@bgub/fig-tanstack-router";
+import { routeTree } from "./routeTree.gen.ts";
+
+export function getRouter() {
+  return createRouter({
+    ...createStartDataContext(),
+    isServer: typeof document === "undefined",
+    routeTree,
+  });
+}
+
+export type AppRouter = ReturnType<typeof getRouter>;
+
+declare module "@tanstack/router-core" {
+  interface Register {
+    router: AppRouter;
+  }
+}
+```
+
+A route file exports the generated route's configuration and receives bound,
+fully typed hooks from that route:
+
+```tsx
+// src/routes/users.$id.tsx
+import { on } from "@bgub/fig-dom";
+import { createFileRoute } from "@tanstack/solid-router";
+
+export const Route = createFileRoute("/users/$id")({
+  validateSearch: (search): { preview?: boolean } => ({
+    preview: search.preview === true,
+  }),
+  loaderDeps: ({ search }) => ({ preview: search.preview === true }),
+  component: User,
+});
+
+function User() {
+  const { id } = Route.useParams();
+  const { preview } = Route.useLoaderDeps();
+  const navigate = Route.useNavigate();
+
+  return (
+    <article>
+      <Route.Link to="/">Home</Route.Link>
+      <button mix={on("click", () => navigate({ to: "/" }))} type="button">
+        Done
+      </button>
+      <p>{preview ? `Previewing ${id}` : `User ${id}`}</p>
+    </article>
+  );
+}
+```
+
+`@tanstack/solid-router` is currently a compiler-only compatibility ID. The
+Start plugin maps it directly to this package; no Solid Router adapter runtime
+is installed or bundled. TypeScript needs the equivalent path mapping:
+
+```json
+{
+  "compilerOptions": {
+    "paths": {
+      "@tanstack/solid-router": ["./node_modules/@bgub/fig-tanstack-router"]
+    }
+  }
+}
+```
+
+The root route normally renders Router-managed document state and Start's Fig
+data snapshot before the bootstrap scripts:
+
+```tsx
+import { StartScripts, type StartDataContext } from "@bgub/fig-tanstack-start";
+import {
+  createRootRouteWithContext,
+  HeadContent,
+  Outlet,
+} from "@bgub/fig-tanstack-router";
+
+export const Route = createRootRouteWithContext<StartDataContext>()({
+  component: Document,
+});
+
+function Document() {
+  return (
+    <html lang="en">
+      <head>
+        <HeadContent />
+      </head>
+      <body>
+        <Outlet />
+        <StartScripts />
+      </body>
+    </html>
+  );
+}
+```
+
+Route stylesheets, preload hints, preconnects, font preloads, and async scripts
+are translated into Fig asset resources owned by the matched route. Title,
+meta, inline styles, JSON-LD, and synchronous scripts retain their document
+position. Configure manifest cross-origin behavior on the router so it is
+available before the root document renders:
+
+```tsx
+const router = createRouter({
+  assetCrossOrigin: { script: "anonymous", stylesheet: "use-credentials" },
+  routeTree,
+});
+```
+
+`getRouteApi(routeId)` provides a route-bound interface outside the route's
+own module. `useMatches` reads or selects the active match list;
+`useMatchRoute` and `MatchRoute` test locations reactively; `Navigate`
+performs declarative post-commit navigation. Selector hooks accept
+`structuralSharing`, falling back to the router's `defaultStructuralSharing`;
+location hooks accept selectors, loose hooks accept `strict: false`, and
+match, params, and search reads can return `undefined` with
+`shouldThrow: false`.
+
+## Provider and navigation lifecycle
+
+`RouterProvider` can merge partial router options and route context into an
+existing router. Initial loaders see these values on their first run, and
+later provider renders preserve context fields they do not replace:
+
+```tsx
+<RouterProvider context={{ session }} defaultPreload="intent" router={router} />
+```
+
+Browser navigation runs in a Fig transition, keeping the previously resolved
+match tree visible until loading settles. Router lifecycle subscriptions fire
+in commit order: `onLoad`, `onBeforeRouteMount`, `onResolved`, then
+`onRendered`. The provider skips a duplicate initial load during hydration,
+normalizes validated locations in browser history, and cleans up its history
+and transition bindings on unmount. A superseded navigation cannot publish a
+late resolved state.
+
+Fig structural `<ViewTransition>` boundaries own route animations. The adapter
+suppresses Router Core's document wrapper, so a `viewTransition` navigation
+option cannot create a second nested browser transition.
+
+Ordinary route changes do not use `Activity`: the previous tree is replaced
+after the transition. Retaining inactive route trees would require a separate
+keep-alive contract for their state, effects, and data ownership.
+
+## Navigation blocking
+
+`useBlocker` supports TanStack's modern object contract without its deprecated
+positional overloads. Set `withResolver: true` to render explicit proceed/reset
+controls; `useCanGoBack` reacts to the current history index:
+
+```tsx
+const blocker = useBlocker({
+  shouldBlockFn: () => formIsDirty,
+  withResolver: true,
+});
+const canGoBack = useCanGoBack();
+
+return blocker.status === "blocked" ? (
+  <nav>
+    <button mix={on("click", blocker.proceed)}>Discard and leave</button>
+    <button mix={on("click", blocker.reset)}>Stay</button>
+  </nav>
+) : (
+  <button disabled={!canGoBack} mix={on("click", () => history.back())}>
+    Back
+  </button>
+);
+```
+
+## Route data: delegate keyed values to Fig
+
+Fig data resources are the external cache for keyed route data — TanStack's
+["pass all loader events to an external cache"](https://tanstack.com/router/latest/docs/guide/data-loading#passing-all-loader-events-to-an-external-cache)
+pattern. Router Core decides _when_ loaders run; the Fig store owns value
+identity, deduplication, freshness, hydration, errors, and render-time reads.
+
+`createStartDataContext()` places the Fig data handle at
+`router.context.data`. A blocking route loader calls `ensureRouteData`, while
+the component reads the same entry with `readData`:
+
+```tsx
+import { dataResource, readData } from "@bgub/fig";
+import { ensureRouteData } from "@bgub/fig-tanstack-router";
+import { createFileRoute } from "@tanstack/solid-router";
+
+const userResource = dataResource({
+  key: (id: string) => ["user", id],
+  load: async (id, { signal }) => fetchUser(id, signal),
+});
+
+export const Route = createFileRoute("/users/$id")({
+  loader: ({ context, params }) =>
+    ensureRouteData(context, userResource, params.id),
+  component: User,
+});
+
+function User() {
+  const { id } = Route.useParams();
+  const user = readData(userResource, id);
+  return <h1>{user.name}</h1>;
+}
+```
+
+`ensureRouteData` deliberately resolves to `void`, so Router Core does not
+retain a second copy in `loaderData`. For non-blocking streaming, call
+`context.data.preloadData(resource, ...args)` and return; the component's
+`readData` suspends through Fig until the entry settles. Returning `void` lets
+the route commit its Suspense fallback independently and keeps resource values
+out of Router dehydration.
+
+Loaders return `void`, and the adapter exposes no `useLoaderData`: a loader
+value would be a second cache with a second wire format (Router Core retains
+it per match; TanStack Start dehydrates it through its own transport). In dev
+builds, a match that commits with `loaderData` set while `router.context.data`
+is configured throws a diagnostic naming the route. Derive navigation-scoped
+values from `useLoaderDeps`, search params, or `beforeLoad`-returned route
+context; use a data resource when a value is keyed, shared, hydrated,
+independently invalidated, refreshed, or streamed. Routers created without
+`context.data` keep Router Core's native loader semantics untouched.
+
+## Support policy
+
+See [TanStack Router compatibility](./COMPATIBILITY.md) for the feature-level
+matrix and Fig equivalents for intentionally omitted adapter conveniences.
+
+| Tier                 | Contract                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
+| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Guaranteed           | Generated file and lazy routes; typed route APIs and structural-sharing selectors; Router creation/provider; native links with active/inactive props and render-function children; navigation blocking and back-history state; loaders, redirects, route masks, not-found and route errors; pending timing and remount dependencies; route-level Start SSR policies/hydration; scroll restoration; head and script output; search/history helpers; Fig data-resource delegation. |
+| Compatibility        | `createRootRoute` and `createRoute` for code-created route trees. These use the same Router Core machinery but are not the recommended Start authoring path.                                                                                                                                                                                                                                                                                                                     |
+| Deferred             | `useElementScrollRestoration`, parent/child match selectors, custom-link construction through `useLinkProps` or `createLink`, and proximity preloading.                                                                                                                                                                                                                                                                                                                          |
+| Deliberately omitted | Additional deprecated compatibility classes and aliases; public `Await`, `ClientOnly`, `CatchBoundary`, and `ScrollRestoration` clones; Activity-based keep-alive routing; `useLoaderData` (the Fig data store is the single route-data cache — read with `readData`). Fig primitives or internal adapter behavior cover these concerns.                                                                                                                                         |
+
+The adapter is pinned and tested against `@tanstack/router-core@1.171.15`.
+Upgrades are conformance changes: generated-route, navigation, SSR, data, and
+document tests must pass against the new version before the pin moves.
+
+## Native link contract
+
+`Link` renders a native anchor. It intercepts only unmodified primary clicks;
+downloads, external URLs, modifier keys, and non-`_self` targets retain native
+browser behavior. Disabled links omit `href` and expose `aria-disabled`.
+Preloading supports `intent`, `render`, and `viewport`, and active links expose
+`aria-current="page"` plus `data-status="active"`. `activeProps` and
+`inactiveProps` compose native anchor state, while render-function children
+receive `isActive` and `isTransitioning`. `linkOptions` and `createRouteMask`
+provide reusable typed options without runtime wrappers. Unsupported
+`preloadIntentProximity` is rejected by `LinkProps` rather than silently ignored.
+
+## Code-created route trees
+
+Standalone applications may still assemble a tree with `createRootRoute`,
+`createRoute`, and `route.addChildren`. This compatibility surface remains
+tested because it is useful for small routers and focused adapter tests. New
+TanStack Start applications should use generated file routes so the generator
+can provide route typing and automatic code splitting.
+
+Construct routers and standalone route APIs with `createRouter` and
+`getRouteApi`; their concrete classes are adapter internals.