Macro Packs

A macro is a function on the application server. The model writes one short call, and the server expands it into ordinary A2UI components before anything reaches the renderer. When we package our macros to share them, we call the bundle a macro pack.

What is a macro?

The model writes the call, such as a line chart with a few numbers. The server runs the macro, which builds the whole tree of components, so the model writes about a kilobyte or less where the finished message runs to several thousand bytes or more. Because the expansion happens on the server, the client has nothing to register when the components come from the Basic Catalog. The d3 pack page shows the measured sizes for six examples.

Macro expansion is part of the official A2UI project: its Python agent SDK has a macros module, in its transformers package, with a @macro decorator and a MacroExpander class.

Two targets: the Basic Catalog and a custom catalog

Basic Catalog target (what our macros do today)

The macro call expands to Basic Catalog components: a Card, Text, and an Image that carries the drawing as an SVG, with Row and Button when the example has controls. The examples on the d3 pack page list the exact components of each. Because everything in the message is a Basic Catalog component, any renderer that supports the Basic Catalog can show it.

Custom catalog target (planned, not built)

In a custom catalog the same call would expand to our own components (atoms) in place of the Image, so the client draws the chart itself. Our d3 atoms take the same inputs as the d3 pack's macros where an atom exists. None of our macros emits atoms today: every message they send names the Basic Catalog and nothing else, and there is no demo of the custom target yet.

From macros to macro packs

We write macros one at a time. When we package a set of them together with their tests, licence and notices, we share the set as a macro pack. We have two so far.

Status

Some macros port or follow these d3 modules; their licences and copyright notices are kept with our code: