feat(a2ui-renderer): A2UI v0.9 — BYOC catalogs, dark mode, component-neutral guidelines

Replace @a2ui/lit with @a2ui/web_core 0.9, introduce createCatalog() API for
custom component catalogs, add basic (18 components) and minimal (5 components)
built-in catalogs, CSS variable theming for dark mode, eliminate XSS vector
(dangerouslySetInnerHTML removed from Text component).

Author: mme

packages/a2ui-renderer/package.json

@@ -48,10 +48,10 @@
     "attw": "attw --pack . --profile node16"
   },
   "dependencies": {
-    "@a2ui/lit": "^0.8.1",
+    "@a2ui/web_core": "0.9.0",
     "clsx": "^2.1.1",
-    "markdown-it": "^14.1.0",
-    "zod": "^3.25.75"
+    "zod": "^3.25.75",
+    "zod-to-json-schema": "^3.24.1"
   },
   "devDependencies": {
     "@testing-library/react": "^16.0.0",

packages/a2ui-renderer/src/a2ui-types.ts

@@ -1,5 +1,24 @@
-import { Data, type Types } from "@a2ui/lit/0.8";
+/**
+ * v0.9 A2UI type definitions for CopilotKit integration.
+ */
 
-export type Theme = Types.Theme;
-export type A2UIClientEventMessage = Types.A2UIClientEventMessage;
-export const DEFAULT_SURFACE_ID = Data.A2uiMessageProcessor.DEFAULT_SURFACE_ID;
+/** Theme type - v0.9 themes are passed via createSurface message */
+export type Theme = Record<string, unknown>;
+
+/**
+ * Client event message dispatched when a user interacts with an A2UI surface.
+ * This is the format expected by A2UIMessageRenderer's handleAction.
+ */
+export interface A2UIClientEventMessage {
+  userAction?: {
+    name: string;
+    surfaceId: string;
+    sourceComponentId?: string;
+    context?: Record<string, unknown>;
+    timestamp?: string;
+    dataContextPath?: string;
+  };
+}
+
+/** Default surface ID when none is specified */
+export const DEFAULT_SURFACE_ID = "default";

packages/a2ui-renderer/src/index.ts

@@ -15,17 +15,8 @@
  */
 
 export * from "./react-renderer/index.js";
-export { A2UIViewer } from "./A2UIViewer.js";
 export { DEFAULT_SURFACE_ID } from "./a2ui-types.js";
 export type { Theme, A2UIClientEventMessage } from "./a2ui-types.js";
-export type { A2UIViewerProps } from "./A2UIViewer.js";
-export { theme as viewerTheme } from "./theme/viewer-theme.js";
 
-// Re-export v0_8 types namespace for consumers
-import type { v0_8 } from "@a2ui/lit";
-export type ComponentInstance = v0_8.Types.ComponentInstance;
-export type UserAction = v0_8.Types.UserAction;
-export type Action = v0_8.Types.Action;
-export type ServerToClientMessage = v0_8.Types.ServerToClientMessage;
-export type Surface = v0_8.Types.Surface;
-export type AnyComponentNode = v0_8.Types.AnyComponentNode;
+// Backward compat: viewerTheme (v0.9 themes handled internally)
+export const viewerTheme: Record<string, unknown> = {};

packages/a2ui-renderer/src/react-renderer/a2ui-react/A2uiSurface.tsx

@@ -0,0 +1,154 @@
+/**
+ * Copyright 2026 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import React, { useSyncExternalStore, memo, useMemo, useCallback } from "react";
+import {
+  type SurfaceModel,
+  ComponentContext,
+  type ComponentModel,
+} from "@a2ui/web_core/v0_9";
+import type { ReactComponentImplementation } from "./adapter";
+
+const ResolvedChild = memo(
+  ({
+    surface,
+    id,
+    basePath,
+    compImpl,
+    componentModel,
+  }: {
+    surface: SurfaceModel<ReactComponentImplementation>;
+    id: string;
+    basePath: string;
+    componentModel: ComponentModel;
+    compImpl: ReactComponentImplementation;
+  }) => {
+    const ComponentToRender = compImpl.render;
+
+    // Create context. Recreate if the componentModel instance changes (e.g. type change recreation).
+    const context = useMemo(
+      () => new ComponentContext(surface, id, basePath),
+      // componentModel is used as a trigger for recreation even if not in the body
+      // eslint-disable-next-line react-hooks/exhaustive-deps
+      [surface, id, basePath, componentModel],
+    );
+
+    const buildChild = useCallback(
+      (childId: string, specificPath?: string) => {
+        const path = specificPath || context.dataContext.path;
+        return (
+          <DeferredChild
+            key={`${childId}-${path}`}
+            surface={surface}
+            id={childId}
+            basePath={path}
+          />
+        );
+      },
+      [surface, context.dataContext.path],
+    );
+
+    return <ComponentToRender context={context} buildChild={buildChild} />;
+  },
+);
+ResolvedChild.displayName = "ResolvedChild";
+
+export const DeferredChild: React.FC<{
+  surface: SurfaceModel<ReactComponentImplementation>;
+  id: string;
+  basePath: string;
+}> = memo(({ surface, id, basePath }) => {
+  // 1. Subscribe specifically to this component's existence
+  const store = useMemo(() => {
+    let version = 0;
+    return {
+      subscribe: (cb: () => void) => {
+        const unsub1 = surface.componentsModel.onCreated.subscribe((comp) => {
+          if (comp.id === id) {
+            version++;
+            cb();
+          }
+        });
+        const unsub2 = surface.componentsModel.onDeleted.subscribe((delId) => {
+          if (delId === id) {
+            version++;
+            cb();
+          }
+        });
+        return () => {
+          unsub1.unsubscribe();
+          unsub2.unsubscribe();
+        };
+      },
+      getSnapshot: () => {
+        const comp = surface.componentsModel.get(id);
+        // We use instance identity + version as the snapshot to ensure
+        // type replacements (e.g. Button -> Text) trigger a re-render.
+        return comp ? `${comp.type}-${version}` : `missing-${version}`;
+      },
+    };
+  }, [surface, id]);
+
+  useSyncExternalStore(store.subscribe, store.getSnapshot);
+
+  const componentModel = surface.componentsModel.get(id);
+
+  if (!componentModel) {
+    return (
+      <div
+        style={{
+          padding: "12px 16px",
+          borderRadius: "8px",
+          background:
+            "linear-gradient(90deg, #f3f4f6 25%, #e5e7eb 50%, #f3f4f6 75%)",
+          backgroundSize: "200% 100%",
+          animation: "a2ui-shimmer 1.5s ease-in-out infinite",
+          minHeight: "2rem",
+        }}
+      >
+        <style>{`@keyframes a2ui-shimmer { 0% { background-position: 200% 0; } 100% { background-position: -200% 0; } }`}</style>
+      </div>
+    );
+  }
+
+  const compImpl = surface.catalog.components.get(componentModel.type);
+
+  if (!compImpl) {
+    return (
+      <div style={{ color: "red" }}>
+        Unknown component: {componentModel.type}
+      </div>
+    );
+  }
+
+  return (
+    <ResolvedChild
+      surface={surface}
+      id={id}
+      basePath={basePath}
+      componentModel={componentModel}
+      compImpl={compImpl}
+    />
+  );
+});
+DeferredChild.displayName = "DeferredChild";
+
+export const A2uiSurface: React.FC<{
+  surface: SurfaceModel<ReactComponentImplementation>;
+}> = ({ surface }) => {
+  // The root component always has ID 'root' and base path '/'
+  return <DeferredChild surface={surface} id="root" basePath="/" />;
+};

packages/a2ui-renderer/src/react-renderer/a2ui-react/adapter.tsx

@@ -0,0 +1,136 @@
+/**
+ * Copyright 2026 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import React, {
+  useRef,
+  useSyncExternalStore,
+  useCallback,
+  memo,
+  useEffect,
+} from "react";
+import { type ComponentContext, GenericBinder } from "@a2ui/web_core/v0_9";
+import type {
+  ComponentApi,
+  InferredComponentApiSchemaType,
+  ResolveA2uiProps,
+} from "@a2ui/web_core/v0_9";
+
+export interface ReactComponentImplementation extends ComponentApi {
+  /** The framework-specific rendering wrapper. */
+  render: React.FC<{
+    context: ComponentContext;
+    buildChild: (id: string, basePath?: string) => React.ReactNode;
+  }>;
+}
+
+export type ReactA2uiComponentProps<T> = {
+  props: T;
+  buildChild: (id: string, basePath?: string) => React.ReactNode;
+  context: ComponentContext;
+};
+
+// --- Component Factories ---
+
+/**
+ * Creates a React component implementation using the deep generic binder.
+ */
+export function createReactComponent<Api extends ComponentApi>(
+  api: Api,
+  RenderComponent: React.FC<
+    ReactA2uiComponentProps<
+      ResolveA2uiProps<InferredComponentApiSchemaType<Api>>
+    >
+  >,
+): ReactComponentImplementation {
+  type Props = ResolveA2uiProps<InferredComponentApiSchemaType<Api>>;
+
+  const MemoizedRender = memo(RenderComponent, (prev, next) => {
+    if (prev.props !== next.props) return false;
+    if (prev.context.componentModel.id !== next.context.componentModel.id)
+      return false;
+    if (prev.context.dataContext.path !== next.context.dataContext.path)
+      return false;
+    return true;
+  });
+
+  const ReactWrapper: React.FC<{
+    context: ComponentContext;
+    buildChild: (id: string, basePath?: string) => React.ReactNode;
+  }> = ({ context, buildChild }) => {
+    const bindingRef = useRef<GenericBinder<Props> | null>(null);
+
+    // Create or recreate the binder if the context object changes.
+    // DeferredChild memoizes `context`, so reference changes strictly correspond
+    // to ComponentModel updates (like type changes) or Base Path adjustments.
+    if (!bindingRef.current) {
+      bindingRef.current = new GenericBinder<Props>(context, api.schema);
+    } else if (
+      (bindingRef.current as unknown as { context: ComponentContext })
+        .context !== context
+    ) {
+      bindingRef.current.dispose();
+      bindingRef.current = new GenericBinder<Props>(context, api.schema);
+    }
+    const binding = bindingRef.current;
+
+    const subscribe = useCallback(
+      (callback: () => void) => {
+        const sub = binding.subscribe(callback);
+        return () => sub.unsubscribe();
+      },
+      [binding],
+    );
+
+    const getSnapshot = useCallback(() => binding.snapshot, [binding]);
+    const props = useSyncExternalStore(subscribe, getSnapshot);
+
+    // Prevent DataModel subscription leaks on unmount
+    useEffect(() => {
+      return () => binding.dispose();
+    }, [binding]);
+
+    return (
+      <MemoizedRender
+        props={props || ({} as Props)}
+        buildChild={buildChild}
+        context={context}
+      />
+    );
+  };
+
+  return {
+    name: api.name,
+    schema: api.schema,
+    render: ReactWrapper,
+  };
+}
+
+/**
+ * Creates a React component implementation that manages its own context bindings (no generic binder).
+ */
+export function createBinderlessComponent(
+  api: ComponentApi,
+  RenderComponent: React.FC<{
+    context: ComponentContext;
+    buildChild: (id: string, basePath?: string) => React.ReactNode;
+  }>,
+): ReactComponentImplementation {
+  return {
+    name: api.name,
+    schema: api.schema,
+    render: RenderComponent,
+  };
+}