Proposal: Extract @a2ui/core to enable framework-agnostic component integration

[abalmush]

The problem

External developers who want to integrate A2UI with their existing component libraries (React, Vue, or custom design systems) currently have to rebuild core functionality from scratch. The data processing, path resolution, and message handling logic lives inside @a2ui/lit, which means:

• React teams must reimplement A2uiMessageProcessor and all the JSON Pointer utilities
• Vue teams do the same
• Anyone not using Lit or Angular starts from zero

I've been analyzing what it takes for a React-based component library to integrate with A2UI. The work includes:

• JSON Pointer path resolution (RFC 6901 style)
• Surface and data model management
• Two-way binding infrastructure
• Adjacency list to component tree conversion
• Template expansion with scope handling
• Validation function registry
• Action context resolution and dispatch

This is roughly 800+ lines of framework-agnostic logic that every integration team rewrites.

What already exists

The good news: most of this code already exists in renderers/lit/src/0.8/ and it's already framework-agnostic:

Code	Location	Framework dependencies
A2uiMessageProcessor	data/model-processor.ts	None
Type definitions	types/types.ts	None
Type guards	data/guards.ts	None
Primitive types	types/primitives.ts	None

The problem is packaging. These files live in @a2ui/lit, so importing them pulls in Lit dependencies and feels wrong for React/Vue projects.

Proposed solution

Extract framework-agnostic code into a new @a2ui/core package:

renderers/
├── core/                          # NEW: @a2ui/core
│   ├── src/
│   │   ├── processor/             # A2uiMessageProcessor
│   │   ├── types/                 # All type definitions
│   │   ├── guards/                # Type guards
│   │   ├── validation/            # Validation function registry
│   │   ├── actions/               # Action dispatch utilities
│   │   └── adapters/              # Component adapter pattern
│   └── package.json
│
├── angular/                       # imports from @a2ui/core
├── lit/                           # imports from @a2ui/core
└── react/                         # NEW: optional React bindings

Component adapter pattern

For external developers wrapping their existing components, I'm proposing a decorator-based adapter pattern that works across frameworks:

import { A2UIComponent, prop } from '@a2ui/core';

@A2UIComponent({ type: 'Chart' })
class ChartAdapter {
  @prop() chartType: string;
  @prop() title: StringValue;
  @prop({ name: 'data' }) chartData: StringValue;
}

This adapter is pure metadata. Framework-specific bindings use it:

// React
import { useA2UIAdapter } from '@a2ui/react';

function Chart({ node, processor, surfaceId }) {
  const resolved = useA2UIAdapter(ChartAdapter, { node, processor, surfaceId });
  return <ChartJS type={resolved.chartType} data={resolved.chartData} />;
}

// Angular
@Component({ ... })
export class Chart extends createAdapterComponent(ChartAdapter) { }

The adapter handles:

• Property mapping from A2UI node to component props
• Auto-resolution of path-based values
• Default values
• Type hints for the framework binding layer

Migration path

This change is backward compatible:

1. Move framework-agnostic code from @a2ui/lit to @a2ui/core
2. Update @a2ui/lit and @a2ui/angular to import from @a2ui/core
3. Existing code continues to work; external teams get a clean entry point

Open questions

• Should @a2ui/react be part of this repo or a separate community package? (I've create a PR already if interested: feat: add React renderer and sample clients #367 )
• Should the adapter pattern be opt-in or the recommended way to extend the catalog?
• How do we handle theme extension for custom components?

I'd like to hear from anyone who's integrated A2UI with non-Lit/Angular frameworks. What pain points did you hit? What would have helped?

[abalmush]

Here is a PR just to get an idea on how this change might look: #532