genui_gen 0.14.1

Annotations and runtime helpers to generate genui CatalogItems from your own Flutter widgets. Derive the schema from the constructor so the catalog can never drift.

0.14.1

• genUiFuzz takes host, the app each surface is drawn in. It was always a plain MaterialApp, so a catalog whose components read their app's theme failed on every component before any case ran: drawn outside its app, a component that reads a ThemeExtension with ! has nothing to read. Found fuzzing a real app's catalog. Left out, host is the same plain app as before.

0.14.0

• Re-exports Catalog, CatalogItem and JsonMap alongside A2uiSchemas, ClientFunction and ClientFunctionReturnType, which were already here. Generated code names those six and nothing else of the renderer, so an annotated file, and the generated catalog, now need only this library. genui is being redesigned as a2ui_flutter; with the renderer behind this one export, moving to it is a change in this package rather than in every app's generated code. If your analyzer now reports an import of package:genui/genui.dart as unnecessary, nothing else in that file used it and it can go.
• genUiCatalogDiff no longer reports a child property as a breaking type change when one catalog writes "type": "string" and the other points at ComponentId in A2UI's common_types.json. That definition is a string and nothing more, and it is how a2ui_flutter describes a child. A reference to any other definition still compares by name.

0.13.2

• Documentation only. The quickstart asked for genui_gen: ^0.12.0, which never resolves to 0.13 and leaves out the recorder fix in 0.13.1. It asks for ^0.13.1 now.
• The README links Quincena, a complete app built with this package: an agent composes every answer from twenty generated components and six generated functions, with the inspector, recorded sessions and the test helpers wired in.

0.13.1

• GenUiTraceRecorder copied nothing when it recorded a message from the agent. The controller can keep an updateDataModel's value by reference and write into it as the person types, so a recorded message changed after the fact and the trace showed the person's input as if the agent had sent it. It also skipped redact, which only looked at the data model steps. Found by a copied session in an app that redacts the free-text field of a form: the field came out redacted in the data steps and in full in the agent's message. Messages are now copied when they are recorded.
• redact now applies to what an agent writes with updateDataModel as well, including one that writes below the root. A path named there never reaches the file, whoever put the value in it.

0.13.0

• Added package:genui_gen/inspector.dart. GenUiInspector wraps the app and draws a panel over the running session: the component tree the model built, every data model path with what holds it and what reads it, what a screen reader would announce, and the messages that got the screen into this state. Debugging an ordinary screen starts by opening the file that built it, and a generated screen has no such file.
• The Data tab reads bindings both ways, which is where it earns its keep. A path nothing on the surface reads is payload the agent paid for and nobody saw; a path a component binds that the data model has no entry for is the usual reason a field renders empty with no error anywhere.
• Added GenUiSurfaceGraph, the same reading with no widgets in it, for a test that wants to assert on the shape of a surface. It reports components nothing reaches from the root and components that contain themselves, and is honest about the one thing it cannot know: A2UI names a child with a plain string, so a reference to a component that was never created is indistinguishable from text.
• GenUiTraceRecorder now implements A2uiMessageSink, so it drops into anywhere a controller goes, and exposes changes for a UI built over a trace that is still growing.
• Added GenUiSemanticNode.isOperable, the rule genUiSemanticsAudit already used for "is this a control someone works, or a region they scroll past". The inspector reads the same rule, so an unnamed scrollable is not reported as an unnamed control in one place and ignored in the other.

0.12.0

• Added genUiAsStringMap, genUiAsNumMap and genUiAsBoolMap, which the generated code calls for a Map<String, V> property. An entry the model got wrong is dropped rather than defaulted: a map is a set of keys the model chose, so a key it could not express is better absent than present and wrong.

0.11.0

• Added genUiFuzz, which renders everything the catalog's own schema allows and reports what broke. A catalog is a contract with something that cannot be recompiled, and the only thing holding a model to it is a JSON schema. Every widget test writes the input the author had in mind; this writes the ones the schema permits and the author did not: a required property left out, a string where a number was declared, a binding that never resolves, a list with two hundred entries. Each finding carries the exact component the renderer was handed, so a case can be pasted into a test rather than reconstructed from a description of it.
• The cases come from mutating each item's own generated example rather than from reading the schema, so a hand-written CatalogItem is fuzzed as well as a generated one, as long as it carries example data.
• Added genUiFuzzSummary, a table by component for a CI log.
• Added genUiCoverage, which reads a corpus of recorded sessions and says what the agent actually used. genUiCatalogWeight already said what each component costs; this says which ones earned it. Together they answer the question nothing else does: the example's catalog spends 43% of every request on components its agent has never once composed. It also names the properties never filled and the enum values never chosen.
• Better few-shot samples. The example is what the model learns the property is for, and 42 in a price teaches it that prices are round integers. A property whose name the generator recognises now gets a value that reads like one of its kind, and entries of a list vary instead of repeating. Format hints (a URL, a date, a hex colour) still apply to optional properties, because the model cannot guess a shape it has not seen; prose only replaces a placeholder the example was going to carry anyway.

0.10.0

• Added @GenUiChecked, the validation half of an input component. A2UI lets the agent attach rules to a component: a CheckRule is a condition and the message to show when it fails, and both are required. The rules belong to the agent, because what counts as valid depends on what it is asking for, so a widget only has to be willing to say so. Annotating a parameter adds a checks property to the generated schema and hands that parameter the answer: a String? takes the message of the first failing rule, a bool takes whether every rule passes, and a GenUiCheckResult takes both.
• Added GenUiChecks and GenUiCheckResult, which the generated code builds. Each rule is evaluated on its own rather than combined, which is what keeps the message. genui's checksToExpression folds the conditions into a single and and drops every message, so the basic catalog can only colour a field red; the sentence the agent wrote for the person reading the screen is the only part of a rule they ever see.
• A rule whose condition has not resolved yet counts as passing, so a field is not announced as invalid before the data model arrives. A rule with no message is skipped rather than shown as an unexplained failure, and a condition that throws counts as passing rather than taking the screen down.
• Worth knowing if you compose catalogs: Catalog.copyWith takes items and functions separately, and the README used to show only newItems. A checks rule calls required, regex or email, which live in the basic catalog's functions, so merging only the items leaves those rules naming functions nobody registered. The examples now pass newFunctions too.

0.9.0

• Added @GenUiFunction, the other half of an A2UI catalog. A catalog holds components, which the agent composes a surface out of, and functions, which it computes a value with through the {"call": ...} form any bound property already accepts. genui ships fourteen of them and an app could add its own only by writing a ClientFunction by hand: the name, the description, an argumentSchema spelled out in JSON schema, the return type, and an execute that digs each argument back out of a map and casts it. That is the same drift this package removes from components, one half of the catalog over.
• Added GenUiClientFunction, which the generated code builds: a ClientFunction whose body is a callback. Three constructors, for a function that answers immediately, one that answers once later (.async), and one that keeps answering as its own sources change (.streaming). A throw inside the body becomes an error on the stream rather than an exception out of the expression that called it.
• ClientFunction, ClientFunctionReturnType and A2uiSchemas are now re-exported, for the same reason S is: a file that declares only catalog functions names them in its generated part and should not have to import genui to get them.

0.8.1

• Documentation only; no API change.
• Corrected the install instructions. They still listed json_schema_builder as a direct dependency and imported it in the annotated file, which stopped being true in 0.3.0 when this package began re-exporting S, Schema and ObjectSchema for exactly that reason.
• The README now covers what 0.4 through 0.8 added: @GenUiWrites, child templates, lists of scalars and enums, and the assembled genUiCatalog with its catalog_id.
• Added homepage, pointing at https://diegolopezrm.github.io/genui_gen/.

0.8.0

• Added genUiTemplateChildren and genUiTemplatePath, the runtime half of child templates. A2UI describes the children of a component in two ways: a list of ids the agent wrote out, or {"componentId": "row", "path": "/rows"} repeated once per entry of the data model. The second is what makes a list that grows when the agent sends data rather than a new surface, and a generated widget could not accept it.
• Each template child reads its own entry: the child of /rows at index 2 binds title against /rows/2/title, so one component describes every row. Children are keyed by entry rather than by position, so a row removed from the middle takes its state with it instead of handing it to the row below.
• Added GenUiBinding.value and GenUiValues.raw, which resolve a path and hand back what it holds without coercing it. The typed bindings are right for a widget property; a template needs the list or the map itself.

0.7.0

• Added package:genui_gen/tracing.dart: record an agent session and replay it. A generative interface has a problem an ordinary app does not — the screen that failed is not in the source, because a model composed it once from a context that will not come back — and a trace is that session, kept. GenUiTraceRecorder.attach keeps every message the agent sent, the contents of each surface's data model whenever they changed, and every action the app sent back; GenUiTracePlayer replays it with no model and no network, and GenUiTraceView shows it, at any step.

  final player = GenUiTracePlayer(trace, catalog: genUiCatalog)..seek(7);
  await tester.pumpWidget(MaterialApp(home: GenUiTraceView(player: player)));
  

  Because the replay renders against the app's current catalog, an old session is also a regression test: a catalog change that breaks a real conversation fails before a user finds it.

• redact names the data model paths a recording must not keep. A session records what the user typed, so the field holding an email has to be named before the first recording rather than after the first leak.

• Added genUiCatalogDiff, which reports what changed between two catalog documents from where it matters: the model. A removed component, a new required property, a dropped enum value and a changed type are breaking, because the agent's prompt still describes the old one. A new optional property and a new enum value are not.

• Added genUiSemanticsAudit, which reads the recording the golden test already keeps and reports what a screen reader user could not work with: a control with nothing to announce, a component that reaches assistive technology as nothing at all, two controls that announce themselves identically.

• Added genUiCatalogWeight, which says how much of every prompt each component takes up. A catalog is sent on every request and nothing makes its cost visible.

• GenUiSemanticNode now records tooltip alongside name. A control named only by a tooltip is not unnamed, but it is not named the same way either, and the recording shows which of the two it has.

• The example app records a session with its own widgets, checks its catalog against the published one, and lists what the basic catalog gives a screen reader today: an audio player whose play button and two sliders announce nothing, an image that exposes nothing at all, and a slider with a label the catalog never passes on.

0.6.0

• Added package:genui_gen/testing.dart, which checks the half of a catalog the schema cannot: what a generated component actually exposes to the person using it. genUiSemantics reads the role, name, value, state and actions of a rendered surface, in traversal order; genUiSemanticsGolden records that into a JSON file and fails when it changes; GenUiExampleSurface renders one item's generated example through a real SurfaceController, so the test covers the whole path — schema, bindings and actions — rather than the widget alone.

  expect(
    genUiSemanticsGolden(recorded, File('test/genui_semantics.json')),
    isNull,
  );
  

• The recorded file is checked in and read in review. It is the answer to "what can the model make this app announce, press or report", which is the part of a change that a Dart diff does not show. Re-record a deliberate change with GENUI_UPDATE_GOLDENS=1.

• The file is written in the shape A2UI's rendering cases use — role, name, value, state, actions — so the same recording describes the catalog to a renderer on another platform.

• example/test/genui_semantics.json records the example app's catalog, and example/test/genui_semantics_test.dart is the test to copy.

• a2ui_core is now a dependency: GenUiExampleSurface builds the surface from the same message types genui takes.

0.5.0

• Added genUiCatalogJson and genUiCatalogJsonString, which turn a Catalog into the A2UI catalog.json document that describes it. Inside the app genui puts the catalog in the prompt for you; everything outside this Flutter process needs it as a document — an agent written in Python, a second client rendering the same surfaces in SwiftUI, a review that has to answer what the model was allowed to ask for last Tuesday. The result is the shape A2UI publishes for its own basic catalog: catalogId, components, functions when the catalog has any, and the $defs a renderer resolves a component against.

  final json = genUiCatalogJsonString(genUiCatalog, title: 'Acme catalog');
  

• The export takes a title and a description of its own. genui fills in A2UI Catalog and Custom catalog of A2UI components and functions. for every catalog ever generated, and an agent handed three of them has nothing else to tell them apart by.

• A catalog with no catalogId is rejected rather than exported. A surface names the catalog it was built against, so a document without an id describes components that nothing can ask for.

• example/catalog.json is generated from a test, and the README shows the pattern: write the file under --update-goldens and compare against it otherwise, so the document in the repository cannot fall behind the widgets and a reviewer sees what a new @GenUiWidget exposed to the model.

0.4.0

• Added @GenUiWrites, which makes a control the user operates annotatable. A void Function(T) parameter marked @GenUiWrites('<property>') receives a callback that writes the user's value into the surface's data model, at the path the model bound <property> to. It is what genui's own TextField, Slider, CheckBox, ChoicePicker, DateTimeInput and Tabs already do, and until now an annotated widget had no way to express it: a property was read-only, so a switch or a text field could not be annotated at all. T may be a String, an int, a double, a num, a bool or an enum.
• A property some callback writes to is now read back through the same path it is written to, so the control reflects what the user just did. A literal the model sent is still honoured until that path holds something, the way TextField seeds itself from its initial value. When the model sends a literal rather than a binding there is no path it named, so the value is written to <componentId>.<property> — the fallback the core catalog uses — and the control stays interactive.
• The description of a written property gains a sentence saying so. The callback itself is not in the schema, because the model never supplies it, so the model would otherwise have no way to know that binding the property to a path is how it reads the answer.
• Added the runtime helpers genUiValueWriter, genUiWritePath and genUiWriteReference, called by generated code. A write the data model refuses — a non-numeric segment on a list, an index out of bounds — is reported through ctx.reportError rather than thrown out of a gesture handler, exactly as a failed action is.
• The callback's argument may not be nullable. A2UI has no agreed meaning for writing null to a path, so ValueChanged<String?> is a build error rather than a silent choice between "clear it" and "store null".
• Additive release: a widget that uses only 0.3 types generates identical code.

0.3.0

• Added lists of scalars: a @GenUiWidget parameter or @GenUiData field may now be a List<int>, List<double>, List<num>, or a List<E> for an enum E. Each was a build error in 0.2.
• Added GenUiBinding.numberList and GenUiValues.numberList, resolved through genui's BoundList. Entries that are not numbers are dropped, and a numeric string is parsed, the way the core catalog's number binding does.
• Added the coercion helper genUiAsNumList, used by generated decoders for numeric list fields of a @GenUiData class.
• A list of enums is carried as strings and mapped back by name. A name the enum does not declare is dropped rather than defaulted: the list is the model's, and one bad entry should not silently become a value the author never wrote.
• Re-exported S, Schema and ObjectSchema from json_schema_builder, so an annotated file imports genui_gen alone and json_schema_builder stops being a direct dependency of consumers. shown rather than exported wholesale; if S collides with another one-letter name, import with hide S.
• json_schema_builder moved from dev_dependencies to dependencies, since those three names are now part of this package's public API.
• Additive release: widgets that only use 0.2 types generate identical code.

0.2.0

• Added @GenUiData, marking a plain Dart class as a data shape an annotated widget may receive. A @GenUiWidget parameter may now be a data class, or a List of one, so widgets that take rows, points or items are annotatable.
• Added the GenUiDecoder<T> typedef used by generated code to rebuild a data class from the map the model produced.
• Added GenUiBinding.object and GenUiBinding.objectList, resolved through genui's BoundObject and BoundList, plus the matching GenUiValues.object and GenUiValues.objectList accessors. objectList skips entries that are not maps instead of throwing.
• Added the coercion helpers genUiAsString, genUiAsNum, genUiAsBool, genUiAsStringList, genUiAsObject and genUiAsObjectList. Generated decoders call them instead of casting, so a field of the wrong type degrades the way genui's Bound* widgets degrade instead of throwing a TypeError inside build.
• Added GenUiMissingFieldReporter, genUiMissingField and genUiNestedField, which carry the missing-property report into a data object: a required field the model left out of a row reaches the model as rows.label.
• Additive release: widgets that only use 0.1 types generate identical code.

0.1.2

• Version bump to stay aligned with genui_gen_builder 0.1.2. No API changes.