feat(router): prototype declarative multi-container routing

[Huxpro]

Summary

• add sparkling-history, a TanStack RouterHistory-compatible MPA history that keeps in-container navigation local and forwards cross-container navigation to sparkling-navigation
• add sparkling-router, which owns the serializable multi-container manifest and resolves hard vs. soft navigation while continuing to use the official TanStack React binding
• add sparkling-router-plugin, with TypeScript-AST-based scanners for both TanStack file routes and Next-style app directories, emitting the same neutral manifest schema
• add a ReactLynx TanStack Router demo that combines the official route generator with generated per-container Rspeedy entries
• document the prototype findings, tradeoffs, and the remaining native stack-protocol gate

Findings

1. @tanstack/router-core contains the reusable routing machinery, but does not expose complete framework-neutral createRouter / createRoute factories. For ReactLynx, using the official @tanstack/react-router binding over a Sparkling history adapter is lower risk than maintaining another framework subclass layer.
2. TanStack file routing is the most direct primary authoring path. The official generator continues to own typed routes; Sparkling only adds container partitioning and manifest/entry emission.
3. A Next app-directory scanner can target the same manifest and runtime without changing the core. This proves the shared-core direction, but does not yet claim full Next runtime/API compatibility.

Validation

• pnpm --filter sparkling-history build
• pnpm --filter sparkling-router build
• pnpm --filter sparkling-router-plugin build
• pnpm --filter sparkling-history test — 29 tests
• pnpm --filter sparkling-router test — 3 tests
• pnpm --filter sparkling-router-plugin test — 3 tests
• pnpm --filter tanstack-router-demo test — 16 tests
• pnpm --filter tanstack-router-demo build — generated spike, home, detail, and settings Lynx bundles
• git diff --check huxpro/main...HEAD

Out of scope

This prototype does not implement or freeze the native stack protocol. The next gate is an iOS implementation plus conformance tests for stack state/versioning, gesture-driven changes, reset/getState, syncOwnLocation, prefetch, and result delivery.

[cursor]

Bugbot is not enabled for your account, so this pull request was not reviewed.

Enable Bugbot in the Cursor dashboard to get automatic reviews on future PRs.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
sparkling	Ready	Preview, Comment	Jul 25, 2026 8:06pm

[Huxpro]

Closing this prototype in favor of the #1 + #19 stack, after adopting its three strongest design points there (commit 7ab4ac7 on #19, with credit):

1. Manifest schema versioning — version + scheme.base are now part of manifest v1; the manifest is treated as the serializable JS↔native contract.
2. presentation: 'push' | 'modal' — now flows manifest → resolver → sparkling scheme (native support pending, push fallback).
3. AST-based marker extraction — regex+eval replaced with the TypeScript API, same direction as this PR's static-config.ts; satisfies supported, unreadable forms fail the build.

Directory-level boundaries were also adopted, with one correction: the boundary file is named -container.ts, not _container.tsx — the official TanStack generator treats _-prefixed files as pathless layout routes (which would corrupt routeTree.gen.ts), while --prefixed files are excluded from routing.

Not carried over: the sparkling-router re-export barrel (adds a package boundary without behavior), the plugin's entries output (maps container ids to route source files, which are not bootable entries), and the resolver's new URL() usage (no URL global in the native Lynx runtime — same class of bug #1's review caught). This branch also predates #1's review fixes (85d184d), so those regressions live on here.

Thanks — the schema and boundary ideas made v1 better.

---

Generated by Claude Code