Macro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — @-linked together with shared AI memory.
TypeScript agentaiai-agentsall-in-onecrmcrm-systememaillinearmcpmessagingnotesnotionofficerustslackslack-alternativestartupstartup-toolstypescriptworkspace
feat(web): type nested split route declarations (#6748)
dev-rbbef34ef023b4
diff --git a/apps/web/src/components/app/split-layout/split-router/app-routes.ts b/apps/web/src/components/app/split-layout/split-router/app-routes.tsindex 98c4adc3c5..07f40830e4 100644--- a/apps/web/src/components/app/split-layout/split-router/app-routes.ts+++ b/apps/web/src/components/app/split-layout/split-router/app-routes.ts@@ -47,7 +47,7 @@ const agentsSplitRoutes = ['agents', 'coders', 'agent-chats'].map((section) =>aliases: section === 'agent-chats' ? ['agent-chats/:id'] : undefined,params: z.object({ id: z.string() }),component: lazyView((views) => views.AgentsRouteView),- remountKey: ({ id }: Record<string, unknown>) => String(id),+ remountKey: ({ id }) => id,claim: ({ id }) => ({namespace: section === 'agent-chats' ? 'chat' : 'agent',id,diff --git a/apps/web/src/components/app/split-layout/tests/layoutManager.test.ts b/apps/web/src/components/app/split-layout/tests/layoutManager.test.tsindex 2011eb5ea1..694a00e1b3 100644--- a/apps/web/src/components/app/split-layout/tests/layoutManager.test.ts+++ b/apps/web/src/components/app/split-layout/tests/layoutManager.test.ts@@ -1,5 +1,8 @@import { agentsRouteId } from '@app/features/agents-view/core/route';-import { driveSplitRoute } from '@app/features/drive-view/primitives/drive-route';+import {+ driveDestination,+ driveSplitRoute,+} from '@app/features/drive-view/primitives/drive-route';import {getListNavigationSource,listNavigationSourceId,@@ -855,6 +858,24 @@ describe('layoutManager', () => {id: 'drive-tab',params: { tab: 'shared' },});+ router.navigate(+ second.id,+ driveDestination(+ { kind: 'folder', id: 'another-folder' },+ { type: 'md', id: 'nested-document' }+ )+ );+ expect(router.route(second.id)?.matches).toEqual([+ { id: 'drive', params: {} },+ {+ id: 'drive-folder',+ params: { view: 'folder', folderId: 'another-folder' },+ },+ {+ id: 'drive-folder-document',+ params: { documentType: 'md', documentId: 'nested-document' },+ },+ ]);expect(router.route(first.id)).toEqual(firstRoute);expect(manager.splits()).toHaveLength(2);router.dispose();diff --git a/apps/web/src/features/drive-view/primitives/drive-route.ts b/apps/web/src/features/drive-view/primitives/drive-route.tsindex 2ff74d79a8..dc4584d81e 100644--- a/apps/web/src/features/drive-view/primitives/drive-route.ts+++ b/apps/web/src/features/drive-view/primitives/drive-route.ts@@ -2,7 +2,11 @@ import {deserializeFacetSelection,normalizeFacetSelection,} from '@app/features/soup/filters/facets/selection';-import { defineRoute, routeParams } from '@app/lib/split-router/routes';+import {+ defineRoute,+ defineRoutes,+ routeParams,+} from '@app/lib/split-router/routes';import {type CreateSearchParamsOptions,isSafeName,@@ -10,6 +14,7 @@ import {type SplitRouteNavigationTarget,type SplitRouteParams,type SplitRouterEntry,+ type SplitRouteUnion,takeLast,} from '@app/split-router';import { URL_PARAMS as MARKDOWN_URL_PARAMS } from '@block-md/constants';@@ -83,30 +88,35 @@ const tabRoute = defineRoute({children: [tabDocument],});-export const driveSplitRoute = defineRoute({- id: 'drive',- path: 'drive',- aliases: ['drive/owned', 'drive/tab/owned'],- params: z.object({}),- // Drive lists are independent workspaces, not singleton content. Only the- // document children claim content; returning to a list must stay in its pane.- search: ['drive'],- externalSearch: (entry: Readonly<SplitRouterEntry>) => {- const type = routeParams<DriveRouteParams>(- entry.location.route- ).documentType;- if (- type === 'md' ||- type === 'task' ||- type === 'snippet' ||- type === 'skill'- ) {- return Object.values(MARKDOWN_URL_PARAMS);- }- return type === 'pdf' ? Object.values(PDF_URL_PARAMS) : [];- },- children: [folderRoute, tabRoute, rootDocument],+const driveRoutes = defineRoutes({+ definitions: [+ defineRoute({+ id: 'drive',+ path: 'drive',+ aliases: ['drive/owned', 'drive/tab/owned'],+ params: z.object({}),+ // Drive lists are independent workspaces, not singleton content. Only the+ // document children claim content; returning to a list must stay in its pane.+ search: ['drive'],+ externalSearch: (entry: Readonly<SplitRouterEntry>) => {+ const type = routeParams<DriveRouteParams>(+ entry.location.route+ ).documentType;+ if (+ type === 'md' ||+ type === 'task' ||+ type === 'snippet' ||+ type === 'skill'+ ) {+ return Object.values(MARKDOWN_URL_PARAMS);+ }+ return type === 'pdf' ? Object.values(PDF_URL_PARAMS) : [];+ },+ children: [folderRoute, tabRoute, rootDocument],+ }),+ ],});+export const driveSplitRoute = driveRoutes.definitions[0];export function driveLocationFromParams(params: DriveRouteParams@@ -124,12 +134,7 @@ export function driveDocumentFromParams(}type DriveDestination = SplitRouteNavigationTarget<- | typeof driveSplitRoute- | typeof folderRoute- | typeof tabRoute- | typeof rootDocument- | typeof folderDocument- | typeof tabDocument+ SplitRouteUnion<typeof driveRoutes>>;/** One typed destination builder for list and detail navigation. */@@ -137,6 +142,7 @@ export function driveDestination(location: DriveLocation,document?: DriveDocumentRoute): DriveDestination {+ const [folder, tab, rootDetail] = driveSplitRoute.children;const detail = document && {documentId: document.id,documentType: document.type,@@ -147,17 +153,17 @@ export function driveDestination(folderId: location.id ?? undefined,};return detail- ? { route: folderDocument, params: { ...params, ...detail } }- : { route: folderRoute, params };+ ? { route: folder.children[0], params: { ...params, ...detail } }+ : { route: folder, params };}if (location.tab !== 'owned') {const params = { tab: location.tab };return detail- ? { route: tabDocument, params: { ...params, ...detail } }- : { route: tabRoute, params };+ ? { route: tab.children[0], params: { ...params, ...detail } }+ : { route: tab, params };}return detail- ? { route: rootDocument, params: detail }+ ? { route: rootDetail, params: detail }: { route: driveSplitRoute, params: {} };}diff --git a/apps/web/src/lib/split-router/README.md b/apps/web/src/lib/split-router/README.mdindex 136d36247a..12f4293145 100644--- a/apps/web/src/lib/split-router/README.md+++ b/apps/web/src/lib/split-router/README.md@@ -9,9 +9,12 @@ stay outside this library.- Supply one static `SplitRoutes` declaration tree, or an explicit`SplitRoutesManifest`. A router compiles its own manifest once and exposes it as`router.routes`; there is no global runtime cache.-- `defineRoute()` preserves literal IDs and synchronous Standard Schema param- types. Use route-object destinations and `useRouteParams(route)` for typed- navigation and reads.+- `defineRoute()` infers node-local callback and synchronous Standard Schema+ output types, including `remountKey`. `defineRoutes()` preserves the static+ tree and adds ancestor types to references taken from that tree.+- `useRouteParams(route)` reads only that node's params. `useParams(route)` reads+ the merged branch through that node; `useParams()` still reads the entire+ active branch.- Matching follows declaration order, trying canonical patterns before aliases.Schema and child failures backtrack. Formatting always uses canonical paths.- Every accepted location has a nonempty, structurally valid match branch.@@ -20,6 +23,62 @@ stay outside this library.- Nested outlets preserve component identity while their match remains stable.Use `remountKey` for intentional resets.+## Typed nested routes++```ts+const routes = defineRoutes({+ definitions: [defineRoute({+ id: 'folder',+ path: 'drive/folder/:folderId',+ params: z.object({ folderId: z.string() }),+ children: [defineRoute({+ id: 'document',+ path: 'document/:documentId',+ params: z.object({ documentId: z.string() }),+ remountKey: ({ documentId }) => documentId,+ })],+ })],+});+const folder = routes.definitions[0];+const document = folder.children[0];++navigate({+ route: document,+ params: { folderId: 'folder-1', documentId: 'document-1' },+});+const branch = useParams(document); // folderId + documentId+const local = useRouteParams(document); // documentId only+```++`defineRoutes` returns the same objects: it does not clone, mutate, compile, or+cache the tree. Its ancestry metadata exists only in TypeScript. Take references+from its returned tree to get inherited types; previously declared child variables+retain their original local-only types. Use `defineRoute` at nodes with callbacks+so their schema outputs provide contextual parameter types.++Tree-bound destinations require the complete branch params, including when opening+another pane. Standalone `defineRoute` references remain local-only and may inherit+matching ancestor values from the current pane. Explicit destination params override+those inherited values before each node's serializer runs. Serializers can therefore+receive additional branch fields; serialize the fields owned by that node. Transformed+outputs such as `Date` still require `serializeParams` and are not revalidated as inputs.++`InferSplitRouteParams` is node-local; `InferSplitRouteBranchParams` describes merged+reads; `InferSplitRouteNavigationParams` describes the flat destination bag.+`SplitRouteUnion<typeof routes>` collects references throughout a tree for destination+builders. `SplitRouteNavigationTarget<A | B>` keeps each route paired with its params.++Prefer distinct parameter names across ancestors and descendants, especially when+using claims, which receive the final merged bag. Reads honor child shadowing and+retain parent values when optional child fields are absent. Flat destinations must+satisfy every node's parameter types; incompatible shadows are rejected. Use path+navigation when repeated names need different values at different levels.++Without a schema, literal paths infer strings, optional strings, and `string[]` for+catch-all parameters. Reads include differently named alias params; destinations use+the canonical path's params. Renamed aliases need a schema or serializer that maps+those fields back to canonical names. Widened `string` paths retain untyped params.+## Search and history- Raw query values are `Record<string, string[]>`; repeated values retain order.diff --git a/apps/web/src/lib/split-router/index.ts b/apps/web/src/lib/split-router/index.tsindex 141ec24564..dc954a4f4e 100644--- a/apps/web/src/lib/split-router/index.ts+++ b/apps/web/src/lib/split-router/index.ts@@ -26,6 +26,7 @@ export {createRoutesManifest,decodeRoute,defineRoute,+ defineRoutes,encodeRoute,filterRouteSearch,getExternalSearchKeys,@@ -64,6 +65,9 @@ export {} from './solid';export type {BrowserHistoryIntent,+ DefinedSplitRoutes,+ InferSplitRouteBranchParams,+ InferSplitRouteNavigationParams,InferSplitRouteParams,SerializedSearchParams,SplitLocation,@@ -97,6 +101,7 @@ export type {SplitRouterSettledChange,SplitRouteState,SplitRoutes,+ SplitRouteUnion,SplitSearchState,SplitSearchUpdate,SplitSearchUpdateOptions,diff --git a/apps/web/src/lib/split-router/navigation.ts b/apps/web/src/lib/split-router/navigation.tsindex 31745cf8c3..ea07b7ad29 100644--- a/apps/web/src/lib/split-router/navigation.ts+++ b/apps/web/src/lib/split-router/navigation.ts@@ -45,8 +45,9 @@ function resolveRouteTarget(return {id: definition.id,- params:- index === branch.length - 1 ? { ...params, ...targetParams } : params,+ // Explicit branch params override inherited values at every level before+ // each node serializes its own schema output into path segments.+ params: { ...params, ...targetParams },};});diff --git a/apps/web/src/lib/split-router/routes.ts b/apps/web/src/lib/split-router/routes.tsindex ce1bb622ef..ab5ca18e55 100644--- a/apps/web/src/lib/split-router/routes.ts+++ b/apps/web/src/lib/split-router/routes.ts@@ -2,6 +2,8 @@ import type { StandardSchemaV1 } from '@standard-schema/spec';import { compileRoutePattern, type RoutePattern } from './path';import { assertSafeSearchName } from './search';import type {+ DefinedSplitRoutes,+ InferSplitRouteParams,SplitRouteClaim,SplitRouteDefinition,SplitRouteMatch,@@ -25,41 +27,67 @@ type SplitRouteDefinitionConstraint = {serializeParams?: unknown;claim?: unknown;search?: readonly string[] | '*';- externalSearch?: readonly string[] | ((entry: never) => readonly string[]);- remountKey?: (params: never) => string | number | undefined;+ externalSearch?: SplitRouteDefinition['externalSearch'];+ remountKey?: unknown;+};++type RouteParamCallbacks<TParams> = {+ serializeParams?: (params: TParams) => SplitRouteRawParams;+ claim?: (params: TParams) => SplitRouteClaim | undefined;+ remountKey?: (params: TParams) => string | number | undefined;};export function defineRoute<const TParamsSchema extends StandardSchemaV1,const TDefinition extends SplitRouteDefinitionConstraint,+>(+ definition: TDefinition & { params: TParamsSchema } & RouteParamCallbacks<+ StandardSchemaV1.InferOutput<TParamsSchema>+ >+): TDefinition & { params: TParamsSchema } & RouteParamCallbacks<+ StandardSchemaV1.InferOutput<TParamsSchema>+ >;+export function defineRoute<+ const TPath extends string,+ const TAliases extends readonly string[] | undefined,+ const TDefinition extends SplitRouteDefinitionConstraint,>(definition: TDefinition & {- params: TParamsSchema;- serializeParams?: (- params: StandardSchemaV1.InferOutput<TParamsSchema>- ) => SplitRouteRawParams;- claim?: (- params: StandardSchemaV1.InferOutput<TParamsSchema>- ) => SplitRouteClaim | undefined;- }-): TDefinition & {- params: TParamsSchema;- serializeParams?: (- params: StandardSchemaV1.InferOutput<TParamsSchema>- ) => SplitRouteRawParams;- claim?: (- params: StandardSchemaV1.InferOutput<TParamsSchema>- ) => SplitRouteClaim | undefined;-};+ path: TPath;+ aliases: TAliases;+ params?: undefined;+ } & RouteParamCallbacks<+ InferSplitRouteParams<{ path: TPath; aliases: TAliases }>+ >+): TDefinition & { path: TPath; aliases: TAliases };export function defineRoute<+ const TPath extends string,const TDefinition extends SplitRouteDefinitionConstraint,->(definition: TDefinition & { params?: undefined }): TDefinition;+>(+ definition: TDefinition & {+ path: TPath;+ aliases?: undefined;+ params?: undefined;+ } & RouteParamCallbacks<InferSplitRouteParams<{ path: TPath }>>+): TDefinition & { path: TPath };export function defineRoute(definition: SplitRouteDefinitionConstraint): SplitRouteDefinitionConstraint {return definition;}+/** Preserve the declaration tree and infer ancestry without constructing runtime state. */+export function defineRoutes<+ const TRoutes extends Omit<SplitRoutes, 'definitions'> & {+ definitions: readonly SplitRouteDefinitionConstraint[];+ },+>(+ routes: TRoutes &+ (NoInfer<TRoutes> extends SplitRoutes ? unknown : SplitRoutes)+): DefinedSplitRoutes<TRoutes> {+ return routes as DefinedSplitRoutes<TRoutes>;+}+export type RouteParamsCodec = {parse(params: SplitRouteRawParams): SplitRouteParams | undefined;serialize(params: SplitRouteParams): SplitRouteParams;diff --git a/apps/web/src/lib/split-router/solid.tsx b/apps/web/src/lib/split-router/solid.tsxindex 784229f788..06c8712642 100644--- a/apps/web/src/lib/split-router/solid.tsx+++ b/apps/web/src/lib/split-router/solid.tsx@@ -18,6 +18,7 @@ import {type SplitRoutesManifest,} from './routes';import type {+ InferSplitRouteBranchParams,InferSplitRouteParams,SplitNavigate,SplitNavigateOptions,@@ -140,12 +141,23 @@ export function useSplitHistory() {return () => router.history(splitId());}-export function useParams<T extends SplitRouteParams = SplitRouteParams>(): T {+export function useParams<const TRoute extends { id: string }>(+ route: TRoute+): InferSplitRouteBranchParams<TRoute>;+export function useParams<T extends SplitRouteParams = SplitRouteParams>(): T;+export function useParams(through?: { id: string }): SplitRouteParams {const router = useSplitRouterState<unknown>();const splitId = useSplitRouterScope<unknown>();- const params = createMemo(() => routeParams(router.route(splitId())));+ const params = createMemo(() => {+ const route = router.route(splitId());+ if (!through || !route) return routeParams(route);+ const index = route.matches.findIndex((match) => match.id === through.id);+ if (index < 0) return {};+ const [first, ...rest] = route.matches;+ return routeParams({ matches: [first, ...rest.slice(0, index)] });+ });- return reactiveRecord(params) as T;+ return reactiveRecord(params);}export function useRouteParams<const TRoute extends { id: string }>(diff --git a/apps/web/src/lib/split-router/tests/navigation.test.ts b/apps/web/src/lib/split-router/tests/navigation.test.tsindex 35422f890f..a46022a6ef 100644--- a/apps/web/src/lib/split-router/tests/navigation.test.ts+++ b/apps/web/src/lib/split-router/tests/navigation.test.ts@@ -5,9 +5,15 @@ import {createRoutesManifest,decodeRoute,defineRoute,+ defineRoutes,routeParams,} from '../routes';-import type { SplitNavigate, SplitRouterEntry } from '../types';+import type {+ SplitNavigate,+ SplitRouteNavigationTarget,+ SplitRouterEntry,+ SplitRouteUnion,+} from '../types';const workspaceDetailRoute = defineRoute({id: 'workspace-detail',@@ -35,9 +41,10 @@ const workspaceRoute = defineRoute({children: [workspaceFolderRoute, workspacePageRoute],});-const routes = createRoutesManifest({- definitions: [workspaceRoute],-});+const tree = defineRoutes({ definitions: [workspaceRoute] });+const routes = createRoutesManifest(tree);+const boundDetail = tree.definitions[0].children[0].children[0];+const boundPage = tree.definitions[0].children[1];function entry(path: string[]): SplitRouterEntry {return decodeRoute(routes, path)!;@@ -50,6 +57,22 @@ function assertTypedRouteTargets(navigate: SplitNavigate<string>) {});navigate({ route: workspaceRoute });navigate({ route: workspacePageRoute, params: { page: 2 } });+ navigate({+ route: boundDetail,+ params: { folderId: 'folder', documentId: 'doc' },+ });+ // @ts-expect-error A tree-bound destination requires its ancestor params too.+ navigate({ route: boundDetail, params: { documentId: 'doc' } });+ // @ts-expect-error Ancestor fields keep their schema output types.+ navigate({ route: boundDetail, params: { folderId: 4, documentId: 'doc' } });+ // @ts-expect-error A route union cannot pair one route with another route's params.+ const mismatched: SplitRouteNavigationTarget<+ typeof boundDetail | typeof boundPage+ > = { route: boundPage, params: { folderId: 'folder', documentId: 'doc' } };+ void mismatched;+ const destination: SplitRouteNavigationTarget<SplitRouteUnion<typeof tree>> =+ { route: boundDetail, params: { folderId: 'folder', documentId: 'doc' } };+ navigate(destination);// @ts-expect-error navigation uses the schema output typenavigate({ route: workspacePageRoute, params: { page: '2' } });// @ts-expect-error documentId is required by the route schema@@ -79,6 +102,59 @@ describe('split route navigation', () => {]);});+ it.each([['workspace'], ['workspace', 'folder', 'old-folder']])(+ 'uses explicit ancestor params from %j',+ (...path) => {+ const current = entry(path);+ const next = resolveNavigation(routes, current, undefined, {+ route: boundDetail,+ params: { folderId: 'new-folder', documentId: 'document-1' },+ });+ expect(next?.location.route.matches).toEqual([+ { id: 'workspace', params: {} },+ { id: 'workspace-folder', params: { folderId: 'new-folder' } },+ { id: 'workspace-detail', params: { documentId: 'document-1' } },+ ]);+ }+ );++ it('serializes transformed ancestor outputs without validating them as inputs', () => {+ const dated = defineRoutes({+ definitions: [+ defineRoute({+ id: 'day',+ path: 'day/:date',+ params: z.object({+ date: z.string().transform((date) => new Date(date)),+ }),+ serializeParams: ({ date }) => ({+ date: date.toISOString().slice(0, 10),+ }),+ children: [+ defineRoute({+ id: 'day-item',+ path: 'item/:id',+ params: z.object({ id: z.string() }),+ }),+ ],+ }),+ ],+ });+ const manifest = createRoutesManifest({+ definitions: [...tree.definitions, ...dated.definitions],+ });+ const current = decodeRoute(manifest, ['workspace'])!;+ const date = new Date('2026-01-02T00:00:00Z');+ const next = resolveNavigation(manifest, current, undefined, {+ route: dated.definitions[0].children[0],+ params: { date, id: 'one' },+ });+ expect(next?.location.route.matches).toEqual([+ { id: 'day', params: { date } },+ { id: 'day-item', params: { id: 'one' } },+ ]);+ });+it('appends explicit child-relative paths to the current route', () => {const current = entry(['workspace', 'folder', 'folder-1']);const next = resolveNavigation(diff --git a/apps/web/src/lib/split-router/tests/routes.test.ts b/apps/web/src/lib/split-router/tests/routes.test.tsindex afca13c46c..233859416a 100644--- a/apps/web/src/lib/split-router/tests/routes.test.ts+++ b/apps/web/src/lib/split-router/tests/routes.test.ts@@ -4,6 +4,7 @@ import {createRoutesManifest,decodeRoute,defineRoute,+ defineRoutes,encodeRoute,findRouteBranch,getExternalSearchKeys,@@ -12,7 +13,12 @@ import {validateRouteParams,validateSplitRoutes,} from '../routes';-import type { InferSplitRouteParams } from '../types';+import type {+ InferSplitRouteBranchParams,+ InferSplitRouteNavigationParams,+ InferSplitRouteParams,+ SplitRoutes,+} from '../types';const documentClaim = ({ documentId }: { documentId: string }) => ({namespace: 'document',@@ -23,6 +29,7 @@ const driveRoute = defineRoute({id: 'drive',path: 'drive',aliases: ['files'],+ params: z.object({}),search: ['drive'],externalSearch: ['action'],children: [@@ -67,6 +74,7 @@ describe('split route parameter schemas', () => {id: 'issue',path: 'issue/:issueId',params: z.object({ issueId: z.coerce.number().int().positive() }),+ remountKey: ({ issueId }) => issueId.toFixed(0),});it('coerces URL strings to typed runtime values', () => {@@ -99,6 +107,193 @@ describe('split route parameter schemas', () => {});});+function assertInvalidRouteDeclarations() {+ // @ts-expect-error Invalid callbacks are rejected by the declaration boundary.+ defineRoutes({ definitions: [{ id: 'bad', path: 'bad', claim: 42 }] });+ defineRoutes({+ // @ts-expect-error Route parameter schemas must produce objects.+ definitions: [defineRoute({ id: 'bad', path: 'bad', params: z.string() })],+ });+}++describe('typed route trees', () => {+ it('checks declaration contracts without widening node inference', () => {+ expectTypeOf(assertInvalidRouteDeclarations).toBeFunction();+ });+ it('preserves declaration and schema identity while typing descendant ancestry', () => {+ const declarations = {+ definitions: [driveRoute] as const,+ globalSearch: ['referral_code'] as const,+ };+ const tree = defineRoutes(declarations);+ const detail = tree.definitions[0].children[0].children[0];+ expect(tree).toBe(declarations);+ expect(tree.definitions[0]).toBe(driveRoute);+ expect(detail).toBe(driveRoute.children[0].children[0]);+ expect(detail.params).toBe(driveRoute.children[0].children[0].params);+ expect(createRoutesManifest(tree).byId.get(detail.id)?.definition).toBe(+ detail+ );+ expectTypeOf(tree).toExtend<SplitRoutes>();+ expectTypeOf<InferSplitRouteParams<typeof driveRoute>>().toEqualTypeOf<+ z.output<typeof driveRoute.params>+ >();+ expectTypeOf(detail.id).toEqualTypeOf<'drive-folder-detail'>();+ expectTypeOf<InferSplitRouteParams<typeof detail>>().toEqualTypeOf<{+ documentId: string;+ }>();+ expectTypeOf<InferSplitRouteBranchParams<typeof detail>>().toEqualTypeOf<{+ folderId: string;+ documentId: string;+ }>();+ });++ it('rebinds ancestry when an existing reference is composed into another tree', () => {+ const tree = defineRoutes({ definitions: [driveRoute] });+ const detail = tree.definitions[0].children[0].children[0];+ const rebound = defineRoutes({ definitions: [detail] });+ const root = rebound.definitions[0];+ expect(root).toBe(detail);+ expectTypeOf<InferSplitRouteBranchParams<typeof root>>().toEqualTypeOf<{+ documentId: string;+ }>();+ expectTypeOf<InferSplitRouteNavigationParams<typeof root>>().toEqualTypeOf<{+ documentId: string;+ }>();+ const widened: SplitRoutes = tree;+ const redefined = defineRoutes(widened);+ expectTypeOf(redefined.definitions[0]?.children).toEqualTypeOf<+ SplitRoutes['definitions'][number]['children']+ >();+ });++ it('infers schema-less path params, including optional and catch-all fields', () => {+ const raw = defineRoute({+ id: 'raw',+ path: 'raw/:id/:tab?/*rest',+ remountKey: ({ id, tab, rest }) => `${id}:${tab ?? ''}:${rest.join('/')}`,+ });+ expectTypeOf<InferSplitRouteParams<typeof raw>>().toEqualTypeOf<{+ id: string;+ tab?: string;+ rest: string[];+ }>();+ expect(raw.remountKey({ id: 'one', rest: ['a', 'b'] })).toBe('one::a/b');+ expectTypeOf<InferSplitRouteParams<{ id: 'bare' }>>().toEqualTypeOf<+ Record<string, unknown>+ >();+ });++ it('types differently named alias reads separately from canonical destinations', () => {+ const route = defineRoute({+ id: 'alias',+ path: 'item/:id',+ aliases: ['old/:legacyId'],+ serializeParams: (params) => ({+ id: 'id' in params ? params.id : params.legacyId,+ }),+ remountKey: (params) => ('id' in params ? params.id : params.legacyId),+ });+ expectTypeOf<InferSplitRouteParams<typeof route>>().toEqualTypeOf<+ { id: string } | { legacyId: string }+ >();+ expectTypeOf<+ InferSplitRouteNavigationParams<typeof route>+ >().toEqualTypeOf<{ id: string }>();+ const manifest = createRoutesManifest(+ defineRoutes({ definitions: [route] })+ );+ const entry = decodeRoute(manifest, ['old', 'one'])!;+ expect(routeParams(entry.location.route)).toEqual({ legacyId: 'one' });+ expect(encodeRoute(manifest, entry)).toEqual(['item', 'one']);+ });++ it('retains optional ancestor fields and transformed schema outputs', () => {+ const tree = defineRoutes({+ definitions: [+ defineRoute({+ id: 'parent',+ path: 'parent/:workspace?',+ params: z.object({ workspace: z.string().optional() }),+ children: [+ defineRoute({+ id: 'child',+ path: ':page',+ params: z.object({ page: z.coerce.number() }),+ }),+ ],+ }),+ ],+ });+ const child = tree.definitions[0].children[0];+ expectTypeOf<InferSplitRouteBranchParams<typeof child>>().toEqualTypeOf<{+ workspace?: string;+ page: number;+ }>();+ expectTypeOf<+ InferSplitRouteNavigationParams<typeof child>+ >().toEqualTypeOf<{ workspace?: string; page: number }>();+ });++ it('retains required parent values when optional child fields are absent', () => {+ const tree = defineRoutes({+ definitions: [+ defineRoute({+ id: 'parent',+ path: ':id',+ params: z.object({ id: z.string() }),+ children: [+ defineRoute({+ id: 'child',+ path: 'child/:id?',+ params: z.object({ id: z.coerce.number().optional() }),+ }),+ ],+ }),+ ],+ });+ const child = tree.definitions[0].children[0];+ expectTypeOf<InferSplitRouteBranchParams<typeof child>>().toEqualTypeOf<{+ id: string | number | undefined;+ }>();+ const manifest = createRoutesManifest(tree);+ expect(+ routeParams(decodeRoute(manifest, ['parent', 'child'])?.location.route)+ ).toEqual({ id: 'parent' });+ expect(+ routeParams(+ decodeRoute(manifest, ['parent', 'child', '2'])?.location.route+ )+ ).toEqual({ id: 2 });+ });++ it('models shadowed reads but rejects incompatible flat navigation params', () => {+ const tree = defineRoutes({+ definitions: [+ defineRoute({+ id: 'parent',+ path: ':id',+ params: z.object({ id: z.string() }),+ children: [+ defineRoute({+ id: 'child',+ path: ':id',+ params: z.object({ id: z.coerce.number() }),+ }),+ ],+ }),+ ],+ });+ const child = tree.definitions[0].children[0];+ expectTypeOf<InferSplitRouteBranchParams<typeof child>>().toEqualTypeOf<{+ id: number;+ }>();+ expectTypeOf<+ InferSplitRouteNavigationParams<typeof child>+ >().toEqualTypeOf<{ id: never }>();+ });+});+describe('split route operations', () => {it('finds a route with its ancestors in manifest order', () => {const branch = findRouteBranch(routes, 'drive-folder-detail');diff --git a/apps/web/src/lib/split-router/tests/solid.test.tsx b/apps/web/src/lib/split-router/tests/solid.test.tsxindex 9a09252757..aa99e207ac 100644--- a/apps/web/src/lib/split-router/tests/solid.test.tsx+++ b/apps/web/src/lib/split-router/tests/solid.test.tsx@@ -1,13 +1,13 @@import { cleanup, render } from '@solidjs/testing-library';import { type Accessor, onCleanup } from 'solid-js';-import { afterEach, describe, expect, it, vi } from 'vitest';+import { afterEach, describe, expect, expectTypeOf, it, vi } from 'vitest';import { z } from 'zod';import {createSearchParams,type SetSearchParams,} from '../create-search-params';import { createMemorySplitRouterLocation } from '../integrations/memory';-import { defineRoute } from '../routes';+import { defineRoute, defineRoutes } from '../routes';import {SplitRouter,useCanGo,@@ -104,6 +104,64 @@ afterEach(() => {});describe('Solid split router hooks', () => {+ it('reads typed branch params only through the referenced node and stays reactive', () => {+ const tree = defineRoutes({+ definitions: [+ defineRoute({+ id: 'workspace',+ path: 'workspace/:workspaceId/:id',+ params: z.object({ workspaceId: z.string(), id: z.string() }),+ children: [+ defineRoute({+ id: 'count',+ path: 'count/:id',+ params: z.object({ id: z.coerce.number() }),+ }),+ ],+ }),+ ],+ });+ const parent = tree.definitions[0];+ const child = parent.children[0];+ function ParamsView() {+ const parentParams = useParams(parent);+ const childParams = useParams(child);+ const localParams = useRouteParams(child);+ const missing = useParams(+ defineRoute({ id: 'absent', path: 'absent/:id' })+ );+ expectTypeOf(parentParams).toEqualTypeOf<{+ workspaceId: string;+ id: string;+ }>();+ expectTypeOf(childParams).toEqualTypeOf<{+ workspaceId: string;+ id: number;+ }>();+ expectTypeOf(localParams).toEqualTypeOf<{ id: number }>();+ return (+ <div>{`${parentParams.workspaceId}:${parentParams.id}:${childParams.id}:${localParams.id}:${JSON.stringify(missing)}`}</div>+ );+ }+ const location = createMemorySplitRouterLocation(+ '/workspace/a/parent-a/count/2'+ );+ const result = render(() => (+ <SplitRouter.Root+ layout={createLayout()}+ routes={tree}+ location={location}+ >+ <SplitRouter.Scope splitId="split">+ <ParamsView />+ </SplitRouter.Scope>+ </SplitRouter.Root>+ ));+ expect(result.getByText('a:parent-a:2:2:{}')).toBeTruthy();+ location.set('/workspace/b/parent-b/count/3');+ expect(result.getByText('b:parent-b:3:3:{}')).toBeTruthy();+ });+it('renders the outlet fallback for a missing split without a route-less entry', () => {const layout = createLayout();const view = render(() => (diff --git a/apps/web/src/lib/split-router/types.ts b/apps/web/src/lib/split-router/types.tsindex b918f40b28..320a9e3b2b 100644--- a/apps/web/src/lib/split-router/types.ts+++ b/apps/web/src/lib/split-router/types.ts@@ -73,13 +73,15 @@ type SplitRouteReference = {};type SplitRouteTargetParams<TRoute extends SplitRouteReference> =- {} extends InferSplitRouteParams<TRoute>- ? { params?: InferSplitRouteParams<TRoute> }- : { params: InferSplitRouteParams<TRoute> };+ {} extends InferSplitRouteNavigationParams<TRoute>+ ? { params?: InferSplitRouteNavigationParams<TRoute> }+ : { params: InferSplitRouteNavigationParams<TRoute> };export type SplitRouteNavigationTarget<TRoute extends SplitRouteReference = SplitRouteReference,-> = { route: TRoute } & SplitRouteTargetParams<TRoute>;+> = TRoute extends unknown+ ? { route: TRoute } & SplitRouteTargetParams<NoInfer<TRoute>>+ : never;export type SplitParentNavigationTarget = {parent: true;@@ -161,14 +163,170 @@ export type SplitRouteDefinition<externalSearch?:| readonly string[]| ((entry: Readonly<SplitRouterEntry>) => readonly string[]);- remountKey?: (params: SplitRouteParams) => string | number | undefined;+ remountKey?: SplitRouteParamCallback<+ StandardSchemaV1.InferOutput<TParamsSchema>,+ string | number | undefined+ >;};+type PathSegmentParams<TSegment extends string> =+ TSegment extends `:${infer TName}?`+ ? { [K in TName]?: string }+ : TSegment extends `:${infer TName}`+ ? { [K in TName]: string }+ : TSegment extends `*${infer TName}`+ ? { [K in TName]: string[] }+ : {};++type PathParams<TPath extends string> = TPath extends unknown+ ? string extends TPath+ ? SplitRouteParams+ : TPath extends `${infer TSegment}/${infer TRest}`+ ? PathSegmentParams<TSegment> & PathParams<TRest>+ : PathSegmentParams<TPath>+ : never;++type Simplify<T> = { [K in keyof T]: T[K] };+type RequiredParamKeys<T> = {+ [K in keyof T]-?: {} extends Pick<T, K> ? never : K;+}[keyof T];+type MergedParam<+ TParent,+ TLocal,+ K extends PropertyKey,+> = K extends keyof TLocal+ ? {} extends Pick<TLocal, K>+ ? K extends keyof TParent+ ? TParent[K] | TLocal[K]+ : TLocal[K]+ : TLocal[K]+ : K extends keyof TParent+ ? TParent[K]+ : never;++// Object.assign retains the parent value when an optional child field is absent.+type MergeRouteParams<TParent, TLocal> = TParent extends unknown+ ? TLocal extends unknown+ ? Simplify<+ {+ [K in+ | RequiredParamKeys<TParent>+ | RequiredParamKeys<TLocal>]: MergedParam<TParent, TLocal, K>;+ } & {+ [K in Exclude<+ keyof TParent | keyof TLocal,+ RequiredParamKeys<TParent> | RequiredParamKeys<TLocal>+ >]?: MergedParam<TParent, TLocal, K>;+ }+ >+ : never+ : never;++/** The schema output (or raw path params) owned by this node alone. */export type InferSplitRouteParams<TRoute> = TRoute extends {params: infer TSchema extends StandardSchemaV1;}? StandardSchemaV1.InferOutput<TSchema>- : SplitRouteParams;+ : TRoute extends { path: infer TPath extends string }+ ? MergeRouteParams<+ {},+ PathParams<+ | TPath+ | (TRoute extends { aliases: infer TAliases }+ ? Extract<TAliases, readonly string[]>[number]+ : never)+ >+ >+ : SplitRouteParams;++type LocalNavigationParams<TRoute> = TRoute extends { params: StandardSchemaV1 }+ ? InferSplitRouteParams<TRoute>+ : TRoute extends { path: infer TPath extends string }+ ? MergeRouteParams<{}, PathParams<TPath>>+ : SplitRouteParams;++// Type-only ancestry. defineRoutes never adds properties to the supplied objects.+declare const branchParams: unique symbol;++/** Params accumulated through this node, with child fields overriding ancestors. */+export type InferSplitRouteBranchParams<TRoute> = TRoute extends {+ readonly [branchParams]: { read: infer TParams };+}+ ? TParams+ : InferSplitRouteParams<TRoute>;++/** A flat destination bag must satisfy every ancestor's serializer. */+export type InferSplitRouteNavigationParams<TRoute> = TRoute extends {+ readonly [branchParams]: { navigate: infer TParams };+}+ ? TParams+ : LocalNavigationParams<TRoute>;++// Empty object schemas can infer an index signature of never. It must not+// prohibit the fields supplied by other nodes in the same branch.+type BranchParams<TParams> =+ TParams extends Record<string, never>+ ? {+ [K in keyof TParams as string extends K+ ? never+ : number extends K+ ? never+ : K]: TParams[K];+ }+ : TParams;++type DefinedRoute<TRoute, TParent, TParentNavigation> = TRoute extends unknown+ ? Omit<TRoute, 'children' | typeof branchParams> & {+ readonly [branchParams]: {+ read: MergeRouteParams<+ TParent,+ BranchParams<InferSplitRouteParams<TRoute>>+ >;+ navigate: MergeRouteParams<+ {},+ TParentNavigation & BranchParams<LocalNavigationParams<TRoute>>+ >;+ };+ } & (TRoute extends { children: infer TChildren extends readonly unknown[] }+ ? {+ readonly children: DefinedRouteList<+ TChildren,+ MergeRouteParams<+ TParent,+ BranchParams<InferSplitRouteParams<TRoute>>+ >,+ TParentNavigation & BranchParams<LocalNavigationParams<TRoute>>+ >;+ }+ : Pick<TRoute, Extract<keyof TRoute, 'children'>>)+ : never;++type DefinedRouteList<+ TDefinitions extends readonly unknown[],+ TParent,+ TParentNavigation,+> = {+ [K in keyof TDefinitions]: DefinedRoute<+ TDefinitions[K],+ TParent,+ TParentNavigation+ >;+};++/** The original static tree, with ancestry available on references from that tree. */+export type DefinedSplitRoutes<+ TRoutes extends { definitions: readonly unknown[] },+> = Omit<TRoutes, 'definitions'> & {+ readonly definitions: DefinedRouteList<TRoutes['definitions'], {}, {}>;+};++type RouteUnion<TRoute> = TRoute extends { children: readonly (infer TChild)[] }+ ? TRoute | RouteUnion<TChild>+ : TRoute;++export type SplitRouteUnion<TRoutes extends SplitRoutes> = RouteUnion<+ TRoutes['definitions'][number]+>;export type UnmatchedSplitPathContext = {segments: string[];@@ -181,11 +339,11 @@ export type UnmatchedSplitPathHandler = (/** Static route declarations. Do not mutate them during a router's lifetime. */export type SplitRoutes<TComponent = unknown> = {- definitions: SplitRouteDefinition<TComponent>[];- unmatchedPathHandlers?: UnmatchedSplitPathHandler[];+ definitions: readonly SplitRouteDefinition<TComponent>[];+ unmatchedPathHandlers?: readonly UnmatchedSplitPathHandler[];defaultEntry?: () => SplitRouterEntry;- globalSearch?: string[];- basePath?: string | string[];+ globalSearch?: readonly string[];+ basePath?: string | readonly string[];};export type SplitRouterLayoutEntry<TSplitId> = SplitRouterEntry & {@@ -247,8 +405,8 @@ export type SplitRouterOptions<TSplitId> = {};export type SplitNavigate<TSplitId> = {- <const TRoute extends SplitRouteReference>(- to: SplitRouteNavigationTarget<TRoute>,+ <const TTarget extends { route: SplitRouteReference }>(+ to: TTarget & SplitRouteNavigationTarget<NoInfer<TTarget['route']>>,options?: SplitNavigateOptions<TSplitId>): void;(to: SplitNonRouteNavigateTo, options?: SplitNavigateOptions<TSplitId>): void;@@ -262,9 +420,9 @@ export interface SplitRouter<TSplitId> {splitId: TSplitId,namespace: string): SerializedSearchParams | undefined;- navigate<const TRoute extends SplitRouteReference>(+ navigate<const TTarget extends { route: SplitRouteReference }>(splitId: TSplitId,- to: SplitRouteNavigationTarget<TRoute>,+ to: TTarget & SplitRouteNavigationTarget<NoInfer<TTarget['route']>>,options?: SplitNavigateOptions<TSplitId>): void;navigate(