DX Gaps And Roadmap

DX Gaps And Roadmap

This page is a pressure map, not a promise. Planned work is linked to an issue.

Active Work

Issue	Gap	Completion condition
#176	Public docs still mix old string access with alias layers.	One primary mental model and a migration guide.
#218	Client routes, server routes, metadata, layouts, and files do not share one manifest.	Typed unified graph with deterministic diagnostics.
#249	Performance coverage stops at route and render hot paths.	Reproducible hydration, memory, bundle, and competitor fixtures.
#279	The portable server engine is not yet complete across every phase.	Cross-runtime conformance and a performance release gate.
#338	Effect is 90% of the client bundle (120 KB gzip).	Staged, measured reduction with a tracked bundle budget.

Recently Closed

Server-API epic children #250 (typed request/response/error contracts and generated clients), #251 (request scope, middleware ordering, policy merging), #252 (portable Node/Bun adapters and conformance), and #253 (RouterView param-prop semantics) are all closed, as is #301 (scoped server middleware, complete with conformance and benchmarks).

Layer DX

Current rule:

• app.useLayers(...) owns graph initialization.
• define({ layers }) and defineHook({ layers }) create checked local bindings.
• Missing registrations raise LayerBindingNotRegisteredError before user setup.

Remaining pressure:

• Reduce ceremony for large composition roots without introducing runtime auto-registration races.
• Generate capability inventories that can be reviewed and deployed.
• Keep browser and server service contracts synchronized.

Routing And Server DX

Current client and server matchers support bracket segments and route groups, and server matching is indexed in a radix trie so lookup cost is independent of route count. The server middleware pipeline is complete end to end: discovery, compiled scope graph, onion dispatch, bounded rewrites, abort propagation, and tracing. Response and data caching are available and opt-in.

The remaining architecture work is to make files and declarations feed one typed graph for components, API handlers, actions, metadata, and layouts, and to add the cross-runtime conformance suite.

Tooling DX

• Generated server/client entries exist but need a documented stability policy.
• Manifest client generation exists but needs first-class CLI watch workflows.
• Deployment adapters and runtime support need an explicit compatibility matrix.
• Keep the dev app probe contract synchronized as ecosystem surfaces are added.

Documentation DX

This wiki is the current architecture reference. The separate docs rewrite in #176 must migrate examples and add a string-access migration guide before the repository can claim one public documentation contract.

Senior Review Questions

• Does one capability use one vocabulary in components, hooks, and server code?
• Can a missing dependency fail before user code executes?
• Can a generated manifest be reviewed without running the application?
• Does a documented example compile against the current package exports?
• Is every production claim backed by an executable gate?