0030 xt.ui Application Boundary

Purpose

xt.ui is the generic application and UI toolkit above xt.substrate. It provides the recurring state, form, collection, CRUD, feedback, widget, and frame mechanics that applications should not rebuild. It does not require React and Flutter applications to share routes or screens.

PostgreSQL and generated RPC contracts
                ↓
xt.substrate models, commands and events
                ↓
xt.ui.state.* headless state and actions
                ↓
xt.ui.widgets.* semantic widget contracts
                ↓
xt.ui.frames.* optional reusable compositions
                ↓
handwritten React/Next.js or Dart/Flutter application

Namespace ownership

• xt.ui.core owns nodes, contracts, registries, runtimes, slots, capabilities, and typed services.
• xt.ui.state.* owns UI-independent controllers, substrate projection, forms, collections, CRUD, sessions, feedback, and sanitized diagnostics.
• xt.ui.widgets.* owns small semantic widget contracts and constructors.
• xt.ui.frames.* composes widgets around state and actions for optional shells, forms, tables, detail panels, and feedback regions.
• js.ui.* and dart.ui.* are platform adapters. Application packages own framework lifecycle, routing, navigation, and native SDK integration.

xt.ui.state.* must not construct UiNode values. A frame is optional and must support named region overrides or complete native replacement.

Choosing the state strategy

Every application slice declares one strategy.

Use feature_store by default, particularly for engagement-heavy flows, state reused by several screens, or experiences likely to differ on web and mobile.

Use page_controller for platform-neutral operational workflows such as superuser screens, schema-driven forms, and table-heavy CRUD with filtering, pagination, selection, and bulk actions. A page controller may expose a frame specification but never owns a route or navigation operation.

Generation boundary

Generation may produce database-derived contracts, identifiers, schemas, errors, events, feature stores, approved page controllers, and declarative operational frame specifications.

Generation stops before Next.js routes, React components, Flutter widgets, navigation, platform lifecycle, and native SDK calls. Platform applications may render the same frame, override parts of it, or build a different screen from the same state and actions.

JavaScript browser applications use the shared-worker/proxy substrate. Dart and Flutter use standalone in-process Dart xt.db.node with native Dart adapters and no JavaScript process or webserver bridge.

Package boundary

The JavaScript library is published as @xtalk/ui with core, state, widgets, frames, and platform-adapter subpaths. Dart exposes the same responsibilities from xtalk_ui; equivalent responsibility does not imply identical screen composition.

Statstrade keeps application-specific common, state, ui, and app packages. The state packages instantiate the generated stores/controllers. The UI and app packages are native to React/Next.js or Flutter/Dart.

Extension sequence

1. Add durable behavior as typed PostgreSQL functions and permissions.
2. Generate RPC schemas, identifiers, models, commands, and events.
3. Classify the slice as feature_store or page_controller.
4. Reuse or extend xt.ui.state.* and test it without a UI runtime.
5. For operational screens, optionally select or extend an xt.ui.frames.* composition.
6. Implement each required platform route and presentation independently.
7. Validate shared contracts and state transitions across JS and Dart, then validate each platform UI independently.

Credentials, privileged test-user operations, framework objects, database clients, transports, and navigation objects must not enter portable state.