NIB / DOCUMENTATION
Explore the local fixture — NibGenUI
Run a known A2UI subset through the core and Flutter renderer.
Open interactive viewUse the local source
The three nib_genui 0.0.1 packages are local release candidates with publication disabled. The website fixture is scripted; it does not connect to an agent or a production backend. Do not copy an install command for a package that is not hosted.
The path below runs a known surface through a pure Dart runtime and a Flutter renderer. Keep one runtime per session owner and dispose it when that owner ends.
Prepare a local Flutter consumer
Begin with an app that already runs and a local checkout containing all three NibGenUI packages. They are unpublished 0.0.1 packages, so a hosted install command cannot reproduce this setup. The renderer currently also uses staged Nib package constraints. The paths below assume your app folder sits alongside GenUINib, MotionNib and ComponetsNib; adjust them to your actual checkout.
Put these entries in the app’s pubspec.yaml, merge them with its existing Flutter dependency, and run flutter pub get. The root app’s dependency_overrides selects the local core, motion and component packages. Overrides in a dependency’s own pubspec do not configure your consumer. This local resolution lets you explore the candidate APIs; it does not establish that a clean hosted install works.
dependencies:
flutter:
sdk: flutter
nib_genui:
path: ../GenUINib/packages/nib_genui
dependency_overrides:
nib_genui_core:
path: ../GenUINib/packages/nib_genui_core
nib_motion:
path: ../MotionNib/motion
nib_components:
path: ../ComponetsNib/nib_componentsCreate a bounded runtime
Create the runtime once when the host screen starts. It holds validated surface snapshots, data bindings and registered capabilities. NibCatalog.basic() describes four supported components: Text, Column, Button and TextField. The Flutter renderer supplies their builders. A catalog describes which data is legal; a builder turns accepted data into widgets.
The complete example below creates a surface, adds a root Column with one Text child, and provides the bound title. Each operation returns a result. Stopping on a rejected result during fixture development makes the first mistake visible rather than letting later errors obscure it. In a streaming host, keep the last valid surface and show recoverable feedback instead of throwing away the whole session.
import 'package:flutter/material.dart';
import 'package:nib_genui/nib_genui.dart';
void main() => runApp(const MaterialApp(home: FixturePage()));
class FixturePage extends StatefulWidget {
const FixturePage({super.key});
@override
State<FixturePage> createState() => _FixturePageState();
}
class _FixturePageState extends State<FixturePage> {
late final NibRuntime runtime;
@override
void initState() {
super.initState();
runtime = NibRuntime(
catalogs: [NibCatalog.basic()],
maxSurfaces: 1,
maxNodes: 8,
maxProtocolMessages: 20,
);
final frames = <Map<String, Object?>>[
{'version': 'v0.9.1', 'createSurface': {
'surfaceId': 'main', 'catalogId': NibCatalog.basicId,
}},
{'version': 'v0.9.1', 'updateComponents': {
'surfaceId': 'main',
'components': [
{'id': 'root', 'component': 'Column', 'children': ['title']},
{'id': 'title', 'component': 'Text', 'text': {'path': '/title'}},
],
}},
{'version': 'v0.9.1', 'updateDataModel': {
'surfaceId': 'main', 'path': '/', 'value': {'title': 'Hello from Nib'},
}},
];
for (final frame in frames) {
final result = runtime.apply(frame);
if (!result.accepted) {
throw StateError(result.diagnostics.first.code);
}
}
}
@override
void dispose() {
runtime.dispose();
super.dispose();
}
@override
Widget build(BuildContext context) => Scaffold(
body: Padding(
padding: const EdgeInsets.all(24),
child: NibGeneratedSurface(runtime: runtime, surfaceId: 'main'),
),
);
}| API | Type | Default | Behavior |
|---|---|---|---|
| catalogs | Iterable<NibCatalog> | required | Exact catalog IDs accepted by the runtime. |
| actions | Map<String, NibActionHandler> | {} | Host-owned event handlers; generated data cannot create callbacks. |
| actionContextPaths | Map<String, Map<String, String>> | {} | Allowed context key and JSON Pointer pairs per action. |
| dispose() | void | host call | Releases retained surfaces and closes runtime streams. |
Render only a committed surface
Apply component and data frames after createSurface. Inspect NibApplyResult.accepted and diagnostics on every frame. A rejected frame leaves the prior committed surface in place.
Place NibGeneratedSurface in the widget tree with the same runtime and surfaceId. It subscribes to node changes and cancels its own subscription on disposal. The host still owns the runtime.
NibGeneratedSurface(
runtime: runtime,
surfaceId: 'main',
)Replay before adding a transport
Copy the complete example into lib/main.dart. It uses no network and should display Hello from Nib. The website fixture is a larger version: press Next frame three times to create a surface, define a form, and populate its data. The form can exist before its bound data arrives. Press Say hello with an empty name to see the host guard reject it; type a name and press again to get local feedback.
Replay fixture creates a fresh runtime because the demo deliberately budgets exactly three protocol messages. It also resets the message and the frame counter. A real screen should make the same ownership explicit: the renderer subscribes to the runtime but does not dispose that shared runtime for you. Dispose it when the session owner ends, after stopping any transport that could send more updates.
Next change only the title data frame and leave the component definition unchanged. The binding updates the displayed text. Then change the binding path without supplying matching data and observe the unresolved state. Once these local transitions are predictable, study the protocol and binding guides before adding HTTP. No AI provider or production backend is needed to understand the client contract.