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 hot paths.	Reproducible SSR, hydration, memory, bundle, and competitor fixtures.
#250	Native request schemas are not yet attached to generated route contracts.	Typed request, response, error, and generated-client propagation.
#251	Request scope, middleware, and route policies need one ownership model.	Leak-free request services and deterministic policy merging.
#252	Server runtime portability lacks a conformance matrix.	Tested Node, Bun, edge, and serverless adapter guarantees.
#253	Router param props can collide with script-exposed template values.	Explicit semantics, types, diagnostics, and migration policy.

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. The remaining architecture work is to make files and declarations feed one typed graph for components, API handlers, actions, metadata, and layouts.

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?