@furystack/shades 13.2.2 → 15.0.0

package/CHANGELOG.md

@@ -1,5 +1,162 @@
 # Changelog
 
+## [15.0.0] - 2026-04-25
+
+### 💥 Breaking Changes
+
+All Shades services are now plain-object factories behind DI tokens. See the [v7 migration guide](../../docs/migrations/v7-functional-di.md) for rationale, recipes, and pitfalls.
+
+- `LocationService`, `RouteMatchService`, `ScreenService`, and `SpatialNavigationService` are now interface + singleton token pairs. No class exports. Factory closures hold state and register `onDispose` teardown (event listeners, `history.pushState`/`replaceState` restoration, etc.).
+- Added `LocationServiceSettings` and `SpatialNavigationSettings` singleton tokens with sensible defaults. `useCustomSearchStateSerializer(injector, serialize, deserialize)` and `configureSpatialNavigation(injector, options)` `bind` the settings and `invalidate` the dependent service. `useCustomSearchStateSerializer` preserves the v6 "must be called before first resolve" contract by throwing if `LocationService` has already been resolved (it patches `history.pushState`/`replaceState` and registers global listeners on construction, so a late rebind would leak the previous instance until injector disposal).
+- `injector.cachedSingletons` is gone (it came from `@furystack/inject`). If you used `cachedSingletons.has(X)` to detect opt-in registration, replace with a nullable scoped token (`Token<T | null, 'scoped'>`, default `null`) bound by the parent component.
+- `hasInjectorReference` is gone. `shade.ts` now inlines an `instanceof Injector` check on `props.injector`.
+- `Constructable` import moved from `@furystack/inject` to `@furystack/core`. This package now has a direct `@furystack/core` dependency.
+- `shade.ts` keeps its bare `new Injector()` fallback for components rendered outside an initialized DI context — this is documented and intentional. Apps should still go through `initializeShadeRoot`.
+
+## [14.0.0] - 2026-04-22
+
+### 💥 Breaking Changes
+
+### Removed the legacy flat router, `RouteLink`, and `LinkToRoute`
+
+The long-deprecated single-level `Router` component, its supporting `Route` / `RouterProps` / `RouterState` types, and the legacy `RouteLink` / `LinkToRoute` navigation components have been removed. They were superseded by the nested router stack (`NestedRouter`, `NestedRouteLink`, `createNestedRouteLink`, `nestedNavigate`, etc.) and marked `@deprecated` for several releases.
+
+**Removed exports:**
+
+- `Router`, `RouterProps`, `RouterState`, `Route`
+- `RouteLink`, `RouteLinkProps`
+- `LinkToRoute`, `LinkToRouteProps`
+
+**Impact:** Any module still importing `Router`, `RouteLink`, or `LinkToRoute` from `@furystack/shades` will fail to resolve.
+
+**Migration:** Replace flat routers with `NestedRouter` + `defineNestedRoutes`, and swap `RouteLink` / `LinkToRoute` for `NestedRouteLink` (or the route-tree-aware `createNestedRouteLink<typeof routes>()` factory). See the `NestedRouter` section in the package README for the migration recipe.
+
+### `NestedRouteLink` and `nestedNavigate` now accept a `path` prop / object argument
+
+`NestedRouteLink` now uses `path` instead of `href`, matching the route-definition vocabulary used by `Breadcrumb` and the new navigation helpers. `nestedNavigate` / `createNestedNavigate` switched from positional arguments to an options object so that the new `query` and `hash` fields can be passed alongside `path` / `params` without a growing parameter list.
+
+**Before:**
+
+```typescript
+<NestedRouteLink href="/users/:id" params={{ id: '1' }}>User</NestedRouteLink>
+
+nestedNavigate(injector, '/users/:id', { id: '1' })
+```
+
+**After:**
+
+```typescript
+<NestedRouteLink path="/users/:id" params={{ id: '1' }}>User</NestedRouteLink>
+
+nestedNavigate(injector, { path: '/users/:id', params: { id: '1' } })
+```
+
+**Impact:** Every call site of `NestedRouteLink`, `nestedNavigate`, `createNestedRouteLink` and `createNestedNavigate` must be updated. Wrappers that forward `NestedRouteLinkProps` (for example `AppBarLink` in `@furystack/shades-common-components`) also switched to `path`.
+
+**Migration:** Rename `href` → `path` on every `NestedRouteLink` call site, and rewrite `nestedNavigate(injector, path, params?)` as `nestedNavigate(injector, { path, params })`.
+
+### `NestedRoute` gained two optional generic parameters
+
+`NestedRoute<TMatchResult>` is now `NestedRoute<TMatchResult, TQuery, THash>`. Existing single-generic usages keep working through the defaults, but the `component` opts are now always called with `query` and `hash` fields (populated with `null` / `undefined` when the route declares no schema). `MatchChainEntry` likewise carries `query: unknown` and `hash: string | undefined` fields.
+
+**Impact:** Test fixtures that construct `MatchChainEntry` literals by hand must supply `query` and `hash`. Components that destructure `component` opts by name are unaffected.
+
+**Migration:** Add `query: null, hash: undefined` to any hand-rolled `MatchChainEntry` literal (typically in tests).
+
+### ✨ Features
+
+### Route-level `hash` and `query` schemas
+
+`NestedRoute` can now declare a readonly tuple of allowed hash literals and a query-string validator. Both flow through the new `createNestedRouteLink` / `createNestedNavigate` / `createNestedHooks` helpers to constrain call sites at compile time and surface typed values to the route's `component` opts at render time.
+
+**Usage:**
+
+```typescript
+const routes = defineNestedRoutes({
+  '/users/:id': {
+    hash: ['profile', 'settings'] as const,
+    query: (raw): { page: number } | null =>
+      typeof raw.page === 'number' ? { page: raw.page } : null,
+    component: ({ match, query, hash }) => <UserPage match={match} query={query} hash={hash} />,
+  },
+})
+
+const AppLink = createNestedRouteLink<typeof routes>()
+const appNavigate = createNestedNavigate<typeof routes>()
+
+<AppLink path="/users/:id" params={{ id: '1' }} query={{ page: 2 }} hash="profile">User</AppLink>
+appNavigate(injector, { path: '/users/:id', params: { id: '1' }, hash: 'settings' })
+```
+
+- The router matches on path only — an invalid query / hash never prevents navigation. Components receive `query: null` or `hash: undefined` when the URL does not satisfy the declared schema.
+- Query serialization uses the existing `@furystack/rest` encoder, so any JSON-serializable shape round-trips without a schema library dependency.
+
+### `defineNestedRoutes` helper
+
+`defineNestedRoutes(...)` is an identity helper that preserves the exact inferred literal type of a route tree while still applying a structural `Record<string, NestedRoute<...>>` constraint. Using a plain `satisfies` assertion with the historical bound `NestedRoute<any>` collapsed per-route generics to their defaults, which defeated the downstream extractors used by `createNestedRouteLink` / `createNestedNavigate` / `createNestedHooks`. Declaring route trees through `defineNestedRoutes` keeps the literal shape intact so each route's declared query validator return type and hash literal tuple remain recoverable.
+
+```typescript
+export const appRoutes = defineNestedRoutes({
+  '/tabs': { hash: ['a', 'b'] as const, component: () => <div /> },
+})
+```
+
+### `createNestedHooks` factory
+
+`createNestedHooks(routes)` returns `{ getTypedQuery, getTypedHash }`, synchronous read helpers that look up the route declared at a given path and narrow the current URL's query / hash against its schema. The route tree is captured at factory time, so call sites only pass `(injector, path)` and the type-level narrowing is inferred from the tree. Intended for non-component consumers (services, side effects) that need a typed snapshot without subscribing through the router.
+
+```typescript
+const { getTypedQuery, getTypedHash } = createNestedHooks(routes)
+const query = getTypedQuery(injector, '/users/:id') // typed | null
+const hash = getTypedHash(injector, '/users/:id') // typed | undefined
+```
+
+### `buildNestedNavigateUrl` utility
+
+Exposed the URL-composition helper used internally by `nestedNavigate` and `NestedRouteLink` so callers can produce a compiled URL (path + query + hash) without triggering navigation.
+
+### Strongly-typed `extractNavTree` / `NavTreeNode<TRoutes>`
+
+`extractNavTree` is now generic over the route tree it is called with, and returns `NavTreeNode<TRoutes>[]` instead of the previous loosely-typed `NavTreeNode[]`. On each node `pattern` is narrowed to `keyof TRoutes & string` and `fullPath` is narrowed to `ExtractRoutePaths<TRoutes> & string`, so the result feeds directly into `createNestedRouteLink` / `createNestedNavigate` / `createNestedReplace` / `createAppBarLink` without an `as` cast at the call site. Consumers that still reference `NavTreeNode` without a type argument keep compiling via a widened default parameter, preserving backward compatibility.
+
+```typescript
+import { extractNavTree, type NavTreeNode } from '@furystack/shades'
+
+const tree = extractNavTree(appRoutes)
+// tree[0].fullPath is 'ExtractRoutePaths<typeof appRoutes>', not `string`.
+
+const AppLink = createNestedRouteLink<typeof appRoutes>()
+tree.map((node) => <AppLink path={node.fullPath}>{node.meta?.title}</AppLink>)
+
+// Widened default is unchanged
+const loose: NavTreeNode = { pattern: '/anything', fullPath: '/anything' }
+```
+
+### `nestedReplace` / `createNestedReplace`
+
+Symmetric counterparts to `nestedNavigate` / `createNestedNavigate` that call `history.replaceState` (via `LocationService.replace`) instead of `pushState`. Use this for SPA redirects — auth guards, canonicalization — where the intermediate URL should not be recoverable with the browser's Back button. Accepts the exact same object-argument shape and inherits the full type-safe narrowing of `path` / `params` / `query` / `hash` against the route tree.
+
+```typescript
+const appReplace = createNestedReplace<typeof appRoutes>()
+
+// Unauthenticated visitor → send to /login without polluting history
+appReplace(injector, { path: '/login' })
+```
+
+### ♻️ Refactoring
+
+- The nested router now subscribes to query-string and hash changes in addition to path changes, re-rendering the matched chain without firing `onLeave` / `onVisit` lifecycle hooks when only the URL's search or hash segment changes.
+- Path / query / hash observable bursts from a single `navigate` are now coalesced onto one microtask, so one logical navigation triggers one `updateUrl` run (the `versionRef` guard is retained as a race-safety net).
+- `findDivergenceIndex` keeps its path-only semantics; a separate `hasQueryOrHashChanged` helper drives re-render decisions when the matched chain stays stable but its query / hash differ. Query values are compared with a key-order-independent shallow equality helper instead of `JSON.stringify`.
+- `enrichMatchChain` short-circuits when no chain entry declares `query` or `hash`, returning the input array reference to avoid a per-navigation allocation on the common path-only case.
+- New low-level exports surfaced for advanced routing integrations: `enrichMatchChain`, `hasQueryOrHashChanged`, and the supporting types `QueryValidator`, `HashLiterals`, `ExtractRouteQuery`, `ExtractRouteHash`, `RouteAt`, `TypedParamsArg`, `TypedQueryArg`, `TypedHashArg`, and `TreeAwareNestedRouteLinkProps`.
+
+### 🧪 Tests
+
+- Added type-level and runtime coverage for the new `query` / `hash` paths on `createNestedNavigate`, `createNestedRouteLink`, and the router's match-chain enrichment.
+- Added a `buildNestedNavigateUrl` suite covering params, query and hash composition.
+- Added `expectTypeOf` assertions for the new generic `extractNavTree` output: `pattern` / `fullPath` narrow to the declared route keys and composed path union for flat and nested typed trees, and the widened `NavTreeNode` default keeps compiling for ad-hoc consumers.
+
 ## [13.2.2] - 2026-04-17
 
 ### ⬆️ Dependencies

package/esm/component-factory.spec.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"component-factory.spec.d.ts","sourceRoot":"","sources":["../src/component-factory.spec.tsx"],"names":[],"mappings":"AAEA,OAAO,UAAU,CAAA"}
+{"version":3,"file":"component-factory.spec.d.ts","sourceRoot":"","sources":["../src/component-factory.spec.tsx"],"names":[],"mappings":"AAGA,OAAO,UAAU,CAAA"}

package/esm/component-factory.spec.js

@@ -1,4 +1,4 @@
-import { Injector } from '@furystack/inject';
+import { createInjector } from '@furystack/inject';
 import { describe, expect, it, vi } from 'vitest';
 import './jsx.js';
 import { createComponent } from './shade-component.js';
@@ -59,7 +59,7 @@ describe('Shades Component Factory', () => {
                 render: ({ props }) => createComponent("div", null, props.foo),
             });
             const component = (createComponent("div", null,
-                createComponent(Example, { foo: "example", injector: new Injector() })));
+                createComponent(Example, { foo: "example", injector: createInjector() })));
             const shade = component.firstElementChild;
             shade.updateComponent();
             await flushUpdates();

package/esm/component-factory.spec.js.map

@@ -1 +1 @@
-{"version":3,"file":"component-factory.spec.js","sourceRoot":"","sources":["../src/component-factory.spec.tsx"],"names":[],"mappings":"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"}
+{"version":3,"file":"component-factory.spec.js","sourceRoot":"","sources":["../src/component-factory.spec.tsx"],"names":[],"mappings":"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"}

package/esm/components/define-nested-routes.d.ts

@@ -0,0 +1,27 @@
+import type { NestedRoute } from './nested-router.js';
+/**
+ * Identity helper that preserves the exact inferred literal type of a nested
+ * route tree while still applying a structural `Record<string, NestedRoute<...>>`
+ * constraint for compile-time validation.
+ *
+ * Using a plain `satisfies Record<string, NestedRoute<any>>` assertion collapses
+ * the per-route `query` / `hash` generics to their defaults, which defeats the
+ * type-safe navigation helpers (`createNestedRouteLink`, `createNestedNavigate`,
+ * `createNestedHooks`). Declaring route trees through this helper keeps the
+ * literal shape intact so downstream extractors can recover each route's
+ * declared query validator return type and hash literal tuple.
+ *
+ * @example
+ * ```typescript
+ * const routes = defineNestedRoutes({
+ *   '/users/:id': {
+ *     component: ({ match, query, hash }) => ...,
+ *     hash: ['profile', 'settings'] as const,
+ *     query: (raw): { page: number } | null =>
+ *       typeof raw.page === 'number' ? { page: raw.page } : null,
+ *   },
+ * })
+ * ```
+ */
+export declare const defineNestedRoutes: <T extends Record<string, NestedRoute<any, any, any>>>(routes: T) => T;
+//# sourceMappingURL=define-nested-routes.d.ts.map

package/esm/components/define-nested-routes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"define-nested-routes.d.ts","sourceRoot":"","sources":["../../src/components/define-nested-routes.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAA;AAErD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,eAAO,MAAM,kBAAkB,GAAI,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC,EAAE,QAAQ,CAAC,KAAG,CAAW,CAAA"}

package/esm/components/define-nested-routes.js

@@ -0,0 +1,26 @@
+/**
+ * Identity helper that preserves the exact inferred literal type of a nested
+ * route tree while still applying a structural `Record<string, NestedRoute<...>>`
+ * constraint for compile-time validation.
+ *
+ * Using a plain `satisfies Record<string, NestedRoute<any>>` assertion collapses
+ * the per-route `query` / `hash` generics to their defaults, which defeats the
+ * type-safe navigation helpers (`createNestedRouteLink`, `createNestedNavigate`,
+ * `createNestedHooks`). Declaring route trees through this helper keeps the
+ * literal shape intact so downstream extractors can recover each route's
+ * declared query validator return type and hash literal tuple.
+ *
+ * @example
+ * ```typescript
+ * const routes = defineNestedRoutes({
+ *   '/users/:id': {
+ *     component: ({ match, query, hash }) => ...,
+ *     hash: ['profile', 'settings'] as const,
+ *     query: (raw): { page: number } | null =>
+ *       typeof raw.page === 'number' ? { page: raw.page } : null,
+ *   },
+ * })
+ * ```
+ */
+export const defineNestedRoutes = (routes) => routes;
+//# sourceMappingURL=define-nested-routes.js.map

package/esm/components/define-nested-routes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"define-nested-routes.js","sourceRoot":"","sources":["../../src/components/define-nested-routes.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAuD,MAAS,EAAK,EAAE,CAAC,MAAM,CAAA"}

package/esm/components/define-nested-routes.spec.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=define-nested-routes.spec.d.ts.map

package/esm/components/define-nested-routes.spec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"define-nested-routes.spec.d.ts","sourceRoot":"","sources":["../../src/components/define-nested-routes.spec.ts"],"names":[],"mappings":""}

package/esm/components/define-nested-routes.spec.js

@@ -0,0 +1,81 @@
+import { describe, expect, expectTypeOf, it } from 'vitest';
+import { defineNestedRoutes } from './define-nested-routes.js';
+const makeComponent = () => null;
+describe('defineNestedRoutes', () => {
+    it('Should return the same object reference at runtime', () => {
+        const input = {
+            '/tabs': {
+                component: () => makeComponent(),
+                hash: ['a', 'b'],
+            },
+        };
+        const result = defineNestedRoutes(input);
+        expect(result).toBe(input);
+    });
+    it('Should accept values that satisfy Record<string, NestedRoute<...>>', () => {
+        const routes = defineNestedRoutes({
+            '/bare': { component: () => makeComponent() },
+            '/tabs': {
+                component: () => makeComponent(),
+                hash: ['a', 'b'],
+                query: (raw) => (typeof raw.page === 'number' ? { page: raw.page } : null),
+            },
+        });
+        expect(Object.keys(routes)).toEqual(['/bare', '/tabs']);
+    });
+    describe('Type preservation', () => {
+        it('Should preserve `hash` as a readonly tuple of literal values', () => {
+            const routes = defineNestedRoutes({
+                '/tabs': {
+                    component: () => makeComponent(),
+                    hash: ['overview', 'details'],
+                },
+            });
+            expectTypeOf(routes['/tabs'].hash).toEqualTypeOf();
+        });
+        it('Should preserve the declared return type of a `query` validator', () => {
+            const routes = defineNestedRoutes({
+                '/list': {
+                    component: () => makeComponent(),
+                    query: (raw) => (typeof raw.page === 'number' ? { page: raw.page } : null),
+                },
+            });
+            expectTypeOf().toEqualTypeOf();
+        });
+        it('Should preserve nested children literals', () => {
+            const routes = defineNestedRoutes({
+                '/navigation': {
+                    component: () => makeComponent(),
+                    children: {
+                        '/tabs': {
+                            component: () => makeComponent(),
+                            hash: ['a'],
+                        },
+                    },
+                },
+            });
+            expectTypeOf().toEqualTypeOf();
+        });
+        it('Should reject values that do not satisfy the NestedRoute constraint', () => {
+            // @ts-expect-error -- `component` is required on every route entry
+            defineNestedRoutes({ '/invalid': { hash: ['a'] } });
+        });
+    });
+    describe('Satisfies-collapse regression coverage', () => {
+        it('Should keep literal shape intact (unlike a bare `satisfies` assertion)', () => {
+            // A plain `satisfies` on `Record<string, NestedRoute<any>>` would widen
+            // the per-route `hash` to `readonly any[]` and drop the literal tuple.
+            // `defineNestedRoutes` must preserve the narrow tuple so downstream
+            // type extractors (`ExtractRouteHash`, `RouteAt`) can recover it.
+            const routes = defineNestedRoutes({
+                '/tabs': {
+                    component: () => makeComponent(),
+                    hash: ['overview'],
+                },
+            });
+            expectTypeOf().not.toEqualTypeOf();
+            expectTypeOf().toEqualTypeOf();
+        });
+    });
+});
+//# sourceMappingURL=define-nested-routes.spec.js.map

package/esm/components/define-nested-routes.spec.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"define-nested-routes.spec.js","sourceRoot":"","sources":["../../src/components/define-nested-routes.spec.ts"],"names":[],"mappings":"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"}

package/esm/components/index.d.ts

@@ -1,9 +1,9 @@
+export * from './define-nested-routes.js';
 export * from './lazy-load.js';
-export * from './link-to-route.js';
+export * from './nested-hooks.js';
 export * from './nested-navigate.js';
+export * from './nested-replace.js';
 export * from './nested-route-link.js';
 export * from './nested-route-types.js';
 export * from './nested-router.js';
-export * from './route-link.js';
-export * from './router.js';
 //# sourceMappingURL=index.d.ts.map

package/esm/components/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/components/index.ts"],"names":[],"mappings":"AAAA,cAAc,gBAAgB,CAAA;AAC9B,cAAc,oBAAoB,CAAA;AAClC,cAAc,sBAAsB,CAAA;AACpC,cAAc,wBAAwB,CAAA;AACtC,cAAc,yBAAyB,CAAA;AACvC,cAAc,oBAAoB,CAAA;AAClC,cAAc,iBAAiB,CAAA;AAC/B,cAAc,aAAa,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/components/index.ts"],"names":[],"mappings":"AAAA,cAAc,2BAA2B,CAAA;AACzC,cAAc,gBAAgB,CAAA;AAC9B,cAAc,mBAAmB,CAAA;AACjC,cAAc,sBAAsB,CAAA;AACpC,cAAc,qBAAqB,CAAA;AACnC,cAAc,wBAAwB,CAAA;AACtC,cAAc,yBAAyB,CAAA;AACvC,cAAc,oBAAoB,CAAA"}

package/esm/components/index.js

@@ -1,9 +1,9 @@
+export * from './define-nested-routes.js';
 export * from './lazy-load.js';
-export * from './link-to-route.js';
+export * from './nested-hooks.js';
 export * from './nested-navigate.js';
+export * from './nested-replace.js';
 export * from './nested-route-link.js';
 export * from './nested-route-types.js';
 export * from './nested-router.js';
-export * from './route-link.js';
-export * from './router.js';
 //# sourceMappingURL=index.js.map

package/esm/components/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/components/index.ts"],"names":[],"mappings":"AAAA,cAAc,gBAAgB,CAAA;AAC9B,cAAc,oBAAoB,CAAA;AAClC,cAAc,sBAAsB,CAAA;AACpC,cAAc,wBAAwB,CAAA;AACtC,cAAc,yBAAyB,CAAA;AACvC,cAAc,oBAAoB,CAAA;AAClC,cAAc,iBAAiB,CAAA;AAC/B,cAAc,aAAa,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/components/index.ts"],"names":[],"mappings":"AAAA,cAAc,2BAA2B,CAAA;AACzC,cAAc,gBAAgB,CAAA;AAC9B,cAAc,mBAAmB,CAAA;AACjC,cAAc,sBAAsB,CAAA;AACpC,cAAc,qBAAqB,CAAA;AACnC,cAAc,wBAAwB,CAAA;AACtC,cAAc,yBAAyB,CAAA;AACvC,cAAc,oBAAoB,CAAA"}

package/esm/components/nested-hooks.d.ts

@@ -0,0 +1,62 @@
+import type { Injector } from '@furystack/inject';
+import type { ExtractRouteHash, ExtractRouteQuery, ExtractRoutePaths, RouteAt } from './nested-route-types.js';
+import type { NestedRoute } from './nested-router.js';
+/**
+ * A pair of synchronous read helpers bound to a specific route tree. Use the
+ * factory {@link createNestedHooks} to produce one.
+ */
+export type NestedHooks<TRoutes extends Record<string, NestedRoute<any, any, any>>> = {
+    /**
+     * Reads and validates the current URL query string against the declared
+     * validator of the route at `path`. Returns the typed query value, or
+     * `null` when the route has no validator or the current URL's query does
+     * not satisfy it.
+     *
+     * This is a synchronous snapshot — for reactive use, subscribe to
+     * `locationService.onDeserializedLocationSearchChanged` and call this read
+     * on each change.
+     */
+    getTypedQuery: <TPath extends ExtractRoutePaths<TRoutes>>(injector: Injector, path: TPath) => ExtractRouteQuery<RouteAt<TRoutes, TPath>> | null;
+    /**
+     * Reads the current URL hash and narrows it against the declared literal
+     * tuple of the route at `path`. Returns the hash when it matches one of
+     * the route's declared literals, or `undefined` otherwise.
+     *
+     * This is a synchronous snapshot — for reactive use, subscribe to
+     * `locationService.onLocationHashChanged` and call this read on each change.
+     */
+    getTypedHash: <TPath extends ExtractRoutePaths<TRoutes>>(injector: Injector, path: TPath) => ExtractRouteHash<RouteAt<TRoutes, TPath>> | undefined;
+};
+/**
+ * Walks a route tree and returns the route value declared at the given path,
+ * matching each URL pattern segment-by-segment. The root `/` pattern is
+ * transparent: its children are searched with the full path.
+ *
+ * Exported for unit testing only — consumers should go through
+ * {@link createNestedHooks}.
+ *
+ * @internal
+ */
+export declare const walkRoute: (routes: Record<string, NestedRoute<any, any, any>>, path: string) => NestedRoute<any, any, any> | undefined;
+/**
+ * Creates a pair of type-safe synchronous read helpers (`getTypedQuery`,
+ * `getTypedHash`) bound to a specific route tree. The returned functions
+ * validate the current URL's query and hash against the route declared at
+ * the given path, returning typed values or `null`/`undefined` on mismatch.
+ *
+ * The concrete route tree is captured at factory time, so call sites only
+ * pass `(injector, path)`; the type-level narrowing is derived from the
+ * inferred tree generic.
+ *
+ * @typeParam TRoutes - The route tree type (inferred from the `routes` argument)
+ *
+ * @example
+ * ```typescript
+ * const { getTypedQuery, getTypedHash } = createNestedHooks(appRoutes)
+ *
+ * const query = getTypedQuery(injector, '/users') // typed
+ * const hash = getTypedHash(injector, '/users')   // typed
+ * ```
+ */
+export declare const createNestedHooks: <TRoutes extends Record<string, NestedRoute<any, any, any>>>(routes: TRoutes) => NestedHooks<TRoutes>;
+//# sourceMappingURL=nested-hooks.d.ts.map

package/esm/components/nested-hooks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"nested-hooks.d.ts","sourceRoot":"","sources":["../../src/components/nested-hooks.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAA;AAEjD,OAAO,KAAK,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,OAAO,EAAE,MAAM,yBAAyB,CAAA;AAC9G,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAA;AAErD;;;GAGG;AACH,MAAM,MAAM,WAAW,CAAC,OAAO,SAAS,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC,IAAI;IACpF;;;;;;;;;OASG;IACH,aAAa,EAAE,CAAC,KAAK,SAAS,iBAAiB,CAAC,OAAO,CAAC,EACtD,QAAQ,EAAE,QAAQ,EAClB,IAAI,EAAE,KAAK,KACR,iBAAiB,CAAC,OAAO,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC,GAAG,IAAI,CAAA;IACtD;;;;;;;OAOG;IACH,YAAY,EAAE,CAAC,KAAK,SAAS,iBAAiB,CAAC,OAAO,CAAC,EACrD,QAAQ,EAAE,QAAQ,EAClB,IAAI,EAAE,KAAK,KACR,gBAAgB,CAAC,OAAO,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC,GAAG,SAAS,CAAA;CAC3D,CAAA;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,SAAS,GACpB,QAAQ,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC,EAClD,MAAM,MAAM,KACX,WAAW,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,GAAG,SAe/B,CAAA;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,iBAAiB,GAAI,OAAO,SAAS,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC,EAC1F,QAAQ,OAAO,KACd,WAAW,CAAC,OAAO,CAkBrB,CAAA"}

package/esm/components/nested-hooks.js

@@ -0,0 +1,73 @@
+import { LocationService } from '../services/location-service.js';
+/**
+ * Walks a route tree and returns the route value declared at the given path,
+ * matching each URL pattern segment-by-segment. The root `/` pattern is
+ * transparent: its children are searched with the full path.
+ *
+ * Exported for unit testing only — consumers should go through
+ * {@link createNestedHooks}.
+ *
+ * @internal
+ */
+export const walkRoute = (routes, path) => {
+    for (const [pattern, route] of Object.entries(routes)) {
+        if (pattern === path)
+            return route;
+        if (pattern === '/' && route.children) {
+            const nested = walkRoute(route.children, path);
+            if (nested)
+                return nested;
+        }
+        else if (route.children && path.startsWith(pattern)) {
+            const rest = path.slice(pattern.length);
+            if (rest.startsWith('/') || rest === '') {
+                const nested = walkRoute(route.children, rest || '/');
+                if (nested)
+                    return nested;
+            }
+        }
+    }
+    return undefined;
+};
+/**
+ * Creates a pair of type-safe synchronous read helpers (`getTypedQuery`,
+ * `getTypedHash`) bound to a specific route tree. The returned functions
+ * validate the current URL's query and hash against the route declared at
+ * the given path, returning typed values or `null`/`undefined` on mismatch.
+ *
+ * The concrete route tree is captured at factory time, so call sites only
+ * pass `(injector, path)`; the type-level narrowing is derived from the
+ * inferred tree generic.
+ *
+ * @typeParam TRoutes - The route tree type (inferred from the `routes` argument)
+ *
+ * @example
+ * ```typescript
+ * const { getTypedQuery, getTypedHash } = createNestedHooks(appRoutes)
+ *
+ * const query = getTypedQuery(injector, '/users') // typed
+ * const hash = getTypedHash(injector, '/users')   // typed
+ * ```
+ */
+export const createNestedHooks = (routes) => {
+    return {
+        getTypedQuery: (injector, path) => {
+            const route = walkRoute(routes, path);
+            if (!route?.query)
+                return null;
+            const locationService = injector.get(LocationService);
+            const deserialized = locationService.onDeserializedLocationSearchChanged.getValue();
+            return route.query(deserialized);
+        },
+        getTypedHash: (injector, path) => {
+            const route = walkRoute(routes, path);
+            const declaredHash = route?.hash;
+            if (!declaredHash)
+                return undefined;
+            const locationService = injector.get(LocationService);
+            const currentHash = locationService.onLocationHashChanged.getValue();
+            return declaredHash.includes(currentHash) ? currentHash : undefined;
+        },
+    };
+};
+//# sourceMappingURL=nested-hooks.js.map

package/esm/components/nested-hooks.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"nested-hooks.js","sourceRoot":"","sources":["../../src/components/nested-hooks.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,eAAe,EAAE,MAAM,iCAAiC,CAAA;AAqCjE;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,SAAS,GAAG,CACvB,MAAkD,EAClD,IAAY,EAC4B,EAAE;IAC1C,KAAK,MAAM,CAAC,OAAO,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;QACtD,IAAI,OAAO,KAAK,IAAI;YAAE,OAAO,KAAK,CAAA;QAClC,IAAI,OAAO,KAAK,GAAG,IAAI,KAAK,CAAC,QAAQ,EAAE,CAAC;YACtC,MAAM,MAAM,GAAG,SAAS,CAAC,KAAK,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAA;YAC9C,IAAI,MAAM;gBAAE,OAAO,MAAM,CAAA;QAC3B,CAAC;aAAM,IAAI,KAAK,CAAC,QAAQ,IAAI,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC,EAAE,CAAC;YACtD,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,CAAA;YACvC,IAAI,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,IAAI,KAAK,EAAE,EAAE,CAAC;gBACxC,MAAM,MAAM,GAAG,SAAS,CAAC,KAAK,CAAC,QAAQ,EAAE,IAAI,IAAI,GAAG,CAAC,CAAA;gBACrD,IAAI,MAAM;oBAAE,OAAO,MAAM,CAAA;YAC3B,CAAC;QACH,CAAC;IACH,CAAC;IACD,OAAO,SAAS,CAAA;AAClB,CAAC,CAAA;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAC/B,MAAe,EACO,EAAE;IACxB,OAAO;QACL,aAAa,EAAE,CAAC,QAAQ,EAAE,IAAI,EAAE,EAAE;YAChC,MAAM,KAAK,GAAG,SAAS,CAAC,MAAM,EAAE,IAAI,CAAC,CAAA;YACrC,IAAI,CAAC,KAAK,EAAE,KAAK;gBAAE,OAAO,IAAI,CAAA;YAC9B,MAAM,eAAe,GAAG,QAAQ,CAAC,GAAG,CAAC,eAAe,CAAC,CAAA;YACrD,MAAM,YAAY,GAAG,eAAe,CAAC,mCAAmC,CAAC,QAAQ,EAAE,CAAA;YACnF,OAAO,KAAK,CAAC,KAAK,CAAC,YAAY,CAAU,CAAA;QAC3C,CAAC;QACD,YAAY,EAAE,CAAC,QAAQ,EAAE,IAAI,EAAE,EAAE;YAC/B,MAAM,KAAK,GAAG,SAAS,CAAC,MAAM,EAAE,IAAI,CAAC,CAAA;YACrC,MAAM,YAAY,GAAG,KAAK,EAAE,IAAqC,CAAA;YACjE,IAAI,CAAC,YAAY;gBAAE,OAAO,SAAS,CAAA;YACnC,MAAM,eAAe,GAAG,QAAQ,CAAC,GAAG,CAAC,eAAe,CAAC,CAAA;YACrD,MAAM,WAAW,GAAG,eAAe,CAAC,qBAAqB,CAAC,QAAQ,EAAE,CAAA;YACpE,OAAO,YAAY,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAC,CAAC,CAAE,WAAqB,CAAC,CAAC,CAAC,SAAS,CAAA;QAChF,CAAC;KACF,CAAA;AACH,CAAC,CAAA"}

package/esm/components/nested-hooks.spec.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=nested-hooks.spec.d.ts.map

package/esm/components/nested-hooks.spec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"nested-hooks.spec.d.ts","sourceRoot":"","sources":["../../src/components/nested-hooks.spec.ts"],"names":[],"mappings":""}