@africode/core 5.0.10 → 5.0.13

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (222) hide show
  1. package/AGENTS.md +585 -585
  2. package/AGENT_INSTRUCTIONS.md +595 -595
  3. package/COMPONENT_SCHEMA.json +1826 -1800
  4. package/LICENSE +623 -623
  5. package/README.md +476 -476
  6. package/bin/africode.js +73 -73
  7. package/bin/cli.ts +82 -82
  8. package/bin/create-africode.js +220 -220
  9. package/bin/scaffold.ts +218 -218
  10. package/components/accordion.js +183 -183
  11. package/components/alert.js +131 -131
  12. package/components/auth-form.js +154 -154
  13. package/components/auth.js +172 -172
  14. package/components/avatar.js +117 -117
  15. package/components/badge.js +104 -104
  16. package/components/base.d.ts +139 -139
  17. package/components/base.js +234 -234
  18. package/components/breadcrumb.js +76 -72
  19. package/components/button.js +164 -164
  20. package/components/card.js +144 -137
  21. package/components/carousel.js +32 -32
  22. package/components/cart-drawer.js +28 -28
  23. package/components/code-block.js +20 -20
  24. package/components/contact-form.js +25 -25
  25. package/components/cookie-consent.js +23 -23
  26. package/components/cta-banner.js +38 -38
  27. package/components/cultural-card.js +243 -243
  28. package/components/dashboard-activity-list.js +103 -103
  29. package/components/dashboard-card.js +85 -85
  30. package/components/dashboard-metric.js +81 -81
  31. package/components/dashboard-shell.js +85 -85
  32. package/components/dashboard-topbar.js +84 -84
  33. package/components/divider.js +83 -83
  34. package/components/dropdown.js +171 -171
  35. package/components/error-boundary.js +155 -155
  36. package/components/faq-accordion.js +23 -23
  37. package/components/feature-grid.js +85 -85
  38. package/components/file-uploader.js +22 -22
  39. package/components/filter-bar.js +19 -19
  40. package/components/footer.js +113 -113
  41. package/components/form.js +131 -131
  42. package/components/gallery.js +22 -22
  43. package/components/hero.js +140 -138
  44. package/components/icon.js +36 -36
  45. package/components/index.js +128 -128
  46. package/components/input.js +252 -256
  47. package/components/kanga-card.js +185 -185
  48. package/components/kyc-upload.js +173 -173
  49. package/components/language-switcher.js +108 -108
  50. package/components/loader.js +80 -80
  51. package/components/modal.js +262 -262
  52. package/components/motion.js +84 -84
  53. package/components/nav-drawer.js +216 -216
  54. package/components/navbar.js +243 -236
  55. package/components/newsletter-signup.js +24 -24
  56. package/components/pagination.js +31 -31
  57. package/components/pattern-showcase.js +225 -225
  58. package/components/pricing-card.js +100 -100
  59. package/components/product-card.js +41 -41
  60. package/components/progress.js +132 -134
  61. package/components/react.js +111 -111
  62. package/components/search-box.js +24 -24
  63. package/components/section.js +54 -54
  64. package/components/select.js +321 -322
  65. package/components/sidebar.js +180 -180
  66. package/components/simple-chart.js +22 -22
  67. package/components/skeleton.js +85 -85
  68. package/components/stepper.js +28 -28
  69. package/components/table.js +181 -181
  70. package/components/tabs.js +202 -202
  71. package/components/team-grid.js +23 -23
  72. package/components/testimonial.js +94 -94
  73. package/components/theme-toggle.js +82 -82
  74. package/components/toast.js +139 -139
  75. package/components/tooltip.js +167 -167
  76. package/components/transaction-ledger.js +138 -138
  77. package/components/ui-avatar.js +79 -79
  78. package/components/ui-badge.js +61 -61
  79. package/components/ui-button.js +149 -149
  80. package/components/ui-card.js +74 -75
  81. package/components/ui-chip.js +87 -87
  82. package/components/ui-input.js +110 -110
  83. package/components/ui-popover.js +84 -84
  84. package/components/ui-progress-ring.js +60 -60
  85. package/components/ui-select.js +85 -85
  86. package/components/ui-stat.js +75 -75
  87. package/components/ui-switch.js +85 -85
  88. package/components/ui-table.js +69 -69
  89. package/components/ui-tabs.js +99 -99
  90. package/components/ui-tag.js +64 -64
  91. package/components/ui-textarea.js +84 -84
  92. package/components/ui-tooltip.js +66 -66
  93. package/components/video-player.js +22 -22
  94. package/components/wallet-balance.js +114 -114
  95. package/core/a2ui-schema-manager.js +351 -351
  96. package/core/a2ui.js +696 -696
  97. package/core/actions.js +27 -27
  98. package/core/bun-runtime.js +398 -397
  99. package/core/cli/commands/add.js +23 -23
  100. package/core/cli/commands/audit.js +58 -58
  101. package/core/cli/commands/build.js +193 -193
  102. package/core/cli/commands/create-plugin.js +241 -241
  103. package/core/cli/commands/dev.js +252 -285
  104. package/core/cli/commands/lint.js +23 -23
  105. package/core/cli/commands/test.js +33 -34
  106. package/core/cli/migrator.js +71 -71
  107. package/core/cli/ui.js +56 -56
  108. package/core/compliance.js +823 -823
  109. package/core/config.js +265 -265
  110. package/core/db-advanced.js +478 -481
  111. package/core/db.js +282 -284
  112. package/core/enhanced-hmr.js +406 -406
  113. package/core/errors.js +222 -222
  114. package/core/file-router.js +52 -50
  115. package/core/hmr-client.js +203 -204
  116. package/core/hmr.js +205 -197
  117. package/core/html.d.ts +30 -30
  118. package/core/html.js +84 -84
  119. package/core/hydration.js +52 -52
  120. package/core/lipa-namba-journey.js +548 -605
  121. package/core/logging.js +14 -14
  122. package/core/middleware.js +145 -145
  123. package/core/motion.js +106 -106
  124. package/core/nida-cig-middleware.js +417 -460
  125. package/core/patterns.d.ts +124 -124
  126. package/core/patterns.js +947 -1001
  127. package/core/plugins/index.js +345 -345
  128. package/core/request-analytics.js +253 -253
  129. package/core/request-identity.js +93 -93
  130. package/core/router.js +386 -386
  131. package/core/sdk-browser.js +140 -140
  132. package/core/sdk-client.js +61 -61
  133. package/core/sdk.d.ts +133 -133
  134. package/core/sdk.js +148 -148
  135. package/core/seo.js +76 -76
  136. package/core/server/auth-endpoints.js +339 -339
  137. package/core/server/auth.js +180 -180
  138. package/core/server/csrf.js +200 -206
  139. package/core/server/db.js +39 -39
  140. package/core/server/middleware.js +324 -324
  141. package/core/server/rate-limit.js +238 -238
  142. package/core/server/render.js +67 -69
  143. package/core/server/router.js +102 -120
  144. package/core/session-store.js +68 -68
  145. package/core/shim.js +28 -28
  146. package/core/state.d.ts +86 -86
  147. package/core/state.js +276 -276
  148. package/core/store.d.ts +122 -122
  149. package/core/store.js +61 -61
  150. package/core/validation.d.ts +232 -232
  151. package/core/validation.js +602 -602
  152. package/core/websocket.js +656 -641
  153. package/dist/africode.js +233 -230
  154. package/dist/africode.js.map +83 -83
  155. package/dist/build-info.json +3 -3
  156. package/dist/components.js +195 -192
  157. package/dist/components.js.map +73 -73
  158. package/dist/styles/africanity.css +321 -321
  159. package/dist/styles/typography.css +140 -140
  160. package/docs/IDE-Guide.md +50 -50
  161. package/package.json +113 -113
  162. package/scripts/generate-component-schema.js +82 -79
  163. package/styles/africanity.css +321 -321
  164. package/styles/typography.css +140 -140
  165. package/templates/starter/.env.example +15 -15
  166. package/templates/starter/africode.config.js +40 -40
  167. package/templates/starter/package.json +13 -13
  168. package/templates/starter/src/index.js +18 -18
  169. package/templates/starter/src/pages/index.html +55 -55
  170. package/templates/starter/src/pages/index.js +17 -17
  171. package/templates/starter/src/styles/main.css +3 -3
  172. package/templates/starter-3d/.env.example +7 -7
  173. package/templates/starter-3d/africode.config.js +29 -29
  174. package/templates/starter-3d/components/af-model-viewer.js +125 -125
  175. package/templates/starter-3d/package.json +14 -14
  176. package/templates/starter-3d/src/pages/index.html +55 -55
  177. package/templates/starter-3d/src/pages/index.js +50 -50
  178. package/templates/starter-3d/src/styles/main.css +3 -3
  179. package/templates/starter-dashboard/.env.example +21 -21
  180. package/templates/starter-dashboard/africode.config.js +20 -20
  181. package/templates/starter-dashboard/package.json +14 -14
  182. package/templates/starter-dashboard/src/index.js +17 -17
  183. package/templates/starter-dashboard/src/pages/api/analytics.js +24 -24
  184. package/templates/starter-dashboard/src/pages/index.html +118 -118
  185. package/templates/starter-dashboard/src/pages/index.js +110 -110
  186. package/templates/starter-dashboard/src/styles/main.css +172 -172
  187. package/templates/starter-fintech/.env.example +28 -28
  188. package/templates/starter-fintech/africode.config.js +20 -20
  189. package/templates/starter-fintech/package.json +15 -15
  190. package/templates/starter-fintech/src/index.js +17 -17
  191. package/templates/starter-fintech/src/pages/api/auth.js +45 -45
  192. package/templates/starter-fintech/src/pages/api/dashboard.js +19 -0
  193. package/templates/starter-fintech/src/pages/api/transfer.js +65 -65
  194. package/templates/starter-fintech/src/pages/api/wallet.js +39 -39
  195. package/templates/starter-fintech/src/pages/api/webhooks/payment.js +32 -32
  196. package/templates/starter-fintech/src/pages/index.html +169 -169
  197. package/templates/starter-fintech/src/pages/index.js +161 -161
  198. package/templates/starter-fintech/src/styles/main.css +246 -246
  199. package/templates/starter-react/.env.example +15 -15
  200. package/templates/starter-react/africode.config.js +40 -40
  201. package/templates/starter-react/package.json +15 -15
  202. package/templates/starter-react/src/pages/index.html +55 -55
  203. package/templates/starter-react/src/pages/index.js +68 -68
  204. package/templates/starter-react/src/styles/main.css +3 -3
  205. package/templates/starter-tailwind/.env.example +15 -15
  206. package/templates/starter-tailwind/africode.config.js +40 -40
  207. package/templates/starter-tailwind/package.json +19 -19
  208. package/templates/starter-tailwind/src/pages/index.html +55 -55
  209. package/templates/starter-tailwind/src/pages/index.js +67 -67
  210. package/templates/starter-tailwind/src/styles/main.css +3 -3
  211. package/templates/starter-tailwind/src/styles/tailwind.css +1 -1
  212. package/templates/starter-tailwind/src/tailwind-loader.js +30 -30
  213. package/templates/starter-tailwind/tailwind.config.cjs +18 -18
  214. package/templates/starter-website/.env.example +18 -18
  215. package/templates/starter-website/africode.config.js +20 -20
  216. package/templates/starter-website/package.json +14 -14
  217. package/templates/starter-website/src/index.js +17 -17
  218. package/templates/starter-website/src/pages/index.html +124 -124
  219. package/templates/starter-website/src/pages/index.js +116 -116
  220. package/templates/starter-website/src/styles/main.css +195 -195
  221. package/bin/africode.js.1758507140 +0 -343
  222. package/core/heartbeat.js +0 -64
package/core/a2ui.js CHANGED
@@ -1,696 +1,696 @@
1
- /**
2
- * A2UI Protocol Implementation
3
- * Agent-to-User Interface declarative protocol for generative AI
4
- *
5
- * Enables AI agents to return UI widgets as part of responses without
6
- * executing arbitrary code, ensuring security and consistency.
7
- *
8
- * @module core/a2ui
9
- */
10
-
11
- import { componentMap as coreComponentMap } from '../components/index.js';
12
-
13
- /**
14
- * A2UI Message Types
15
- */
16
- export const A2UI_TYPES = {
17
- COMPONENT: 'component',
18
- FORM: 'form',
19
- LIST: 'list',
20
- CARD: 'card',
21
- MODAL: 'modal',
22
- TOAST: 'toast',
23
- PROGRESS: 'progress',
24
- CHART: 'chart',
25
- DATATABLE: 'datatable',
26
- TABS: 'tabs',
27
- ACCORDION: 'accordion',
28
- STEPPER: 'stepper',
29
- DASHBOARD_WIDGET: 'dashboard-widget'
30
- };
31
-
32
- /**
33
- * A2UI Component Schemas
34
- */
35
- export const A2UI_SCHEMAS = {
36
- component: {
37
- type: 'object',
38
- properties: {
39
- id: { type: 'string' },
40
- type: { type: 'string', enum: Object.values(A2UI_TYPES) },
41
- props: { type: 'object' },
42
- children: { type: 'array', items: { $ref: '#' } }
43
- },
44
- required: ['id', 'type']
45
- }
46
- };
47
-
48
- function escapeHtml(value) {
49
- return String(value)
50
- .replace(/&/g, '&')
51
- .replace(/</g, '&lt;')
52
- .replace(/>/g, '&gt;')
53
- .replace(/"/g, '&quot;')
54
- .replace(/'/g, '&#039;');
55
- }
56
-
57
- function renderNode(node) {
58
- if (Array.isArray(node)) {
59
- return node.map(renderNode).join('');
60
- }
61
-
62
- if (node === null || node === undefined || node === false) {
63
- return '';
64
- }
65
-
66
- if (typeof node === 'string' || typeof node === 'number' || typeof node === 'boolean') {
67
- return escapeHtml(node);
68
- }
69
-
70
- if (typeof node !== 'object') {
71
- return '';
72
- }
73
-
74
- const tag = node.tag || node.tagName;
75
- if (!tag) {
76
- return '';
77
- }
78
-
79
- const props = node.props || {};
80
- const attributes = Object.entries(props)
81
- .filter(([, value]) => value !== null && value !== undefined && value !== false)
82
- .map(([key, value]) => value === true ? key : `${key}="${escapeHtml(value)}"`)
83
- .join(' ');
84
-
85
- const children = renderNode(node.children ?? node.content ?? '');
86
- return `<${tag}${attributes ? ` ${attributes}` : ''}>${children}</${tag}>`;
87
- }
88
-
89
- function isUnsafeHtml(html) {
90
- return /<\s*script\b|on\w+\s*=|javascript:/i.test(String(html));
91
- }
92
-
93
- /**
94
- * A2UI Renderer
95
- * Renders A2UI messages into actual DOM elements
96
- */
97
- export class A2UIRenderer {
98
- constructor(rootElement) {
99
- this.root = rootElement;
100
- this.components = new Map();
101
- }
102
-
103
- /**
104
- * Render an A2UI message
105
- * @param {Object} message - A2UI message object
106
- */
107
- render(message) {
108
- if (!message || !message.type) {
109
- throw new Error('Invalid A2UI message');
110
- }
111
-
112
- if (message.html !== undefined) {
113
- if (isUnsafeHtml(message.html)) {
114
- throw new Error('Unsafe HTML is not allowed in A2UI render messages');
115
- }
116
-
117
- throw new Error('Raw HTML payloads are not supported in A2UI render messages');
118
- }
119
-
120
- const output = Array.isArray(message.components)
121
- ? message.components.map(renderNode).join('')
122
- : renderNode(message.component || message);
123
-
124
- if (message.id) {
125
- this.components.set(message.id, {
126
- id: message.id,
127
- type: message.type,
128
- props: message.props || {},
129
- children: message.children || message.components || []
130
- });
131
- }
132
-
133
- const canRenderToDOM = this.root && typeof this.root.appendChild === 'function' && typeof document !== 'undefined';
134
- if (canRenderToDOM && output) {
135
- const container = document.createElement('div');
136
- container.innerHTML = output;
137
- while (container.firstChild) {
138
- this.root.appendChild(container.firstChild);
139
- }
140
- }
141
-
142
- return output;
143
- }
144
-
145
- /**
146
- * Create DOM element from A2UI component
147
- * @param {Object} component - A2UI component definition
148
- */
149
- createElement(component) {
150
- const { type, props = {}, children = [] } = component;
151
-
152
- let element;
153
-
154
- switch (type) {
155
- case A2UI_TYPES.COMPONENT:
156
- element = this.createCustomComponent(props);
157
- break;
158
- case A2UI_TYPES.FORM:
159
- element = this.createForm(props);
160
- break;
161
- case A2UI_TYPES.LIST:
162
- element = this.createList(props);
163
- break;
164
- case A2UI_TYPES.CARD:
165
- element = this.createCard(props);
166
- break;
167
- case A2UI_TYPES.MODAL:
168
- element = this.createModal(props);
169
- break;
170
- case A2UI_TYPES.TOAST:
171
- element = this.createToast(props);
172
- break;
173
- case A2UI_TYPES.PROGRESS:
174
- element = this.createProgress(props);
175
- break;
176
- case A2UI_TYPES.CHART:
177
- element = this.createChart(props);
178
- break;
179
- case A2UI_TYPES.DATATABLE:
180
- element = this.createDatatable(props);
181
- break;
182
- case A2UI_TYPES.TABS:
183
- element = this.createTabs(props);
184
- break;
185
- case A2UI_TYPES.ACCORDION:
186
- element = this.createAccordion(props);
187
- break;
188
- case A2UI_TYPES.STEPPER:
189
- element = this.createStepper(props);
190
- break;
191
- case A2UI_TYPES.DASHBOARD_WIDGET:
192
- element = this.createDashboardWidget(props);
193
- break;
194
- default:
195
- throw new Error(`Unknown A2UI component type: ${type}`);
196
- }
197
-
198
- // Render children
199
- if (children.length > 0) {
200
- for (const child of children) {
201
- const childElement = this.createElement(child);
202
- element.appendChild(childElement);
203
- }
204
- }
205
-
206
- return element;
207
- }
208
-
209
- /**
210
- * Create custom AfriCode component
211
- */
212
- createCustomComponent({ tag, ...props }) {
213
- const element = document.createElement(tag || 'div');
214
- Object.assign(element, props);
215
- return element;
216
- }
217
-
218
- /**
219
- * Create form component
220
- */
221
- createForm({ fields = [], onSubmit }) {
222
- const form = document.createElement('af-form');
223
-
224
- for (const field of fields) {
225
- const input = document.createElement('af-input');
226
- input.setAttribute('name', field.name);
227
- input.setAttribute('placeholder', field.placeholder || '');
228
- input.setAttribute('type', field.type || 'text');
229
- form.appendChild(input);
230
- }
231
-
232
- if (onSubmit) {
233
- form.addEventListener('submit', onSubmit);
234
- }
235
-
236
- return form;
237
- }
238
-
239
- /**
240
- * Create list component
241
- */
242
- createList({ items = [] }) {
243
- const list = document.createElement('af-grid');
244
-
245
- for (const item of items) {
246
- const card = this.createCard(item);
247
- list.appendChild(card);
248
- }
249
-
250
- return list;
251
- }
252
-
253
- /**
254
- * Create card component
255
- */
256
- createCard({ title, content, image }) {
257
- const card = document.createElement('af-card');
258
-
259
- if (title) {
260
- const titleEl = document.createElement('h3');
261
- titleEl.textContent = title;
262
- card.appendChild(titleEl);
263
- }
264
-
265
- if (content) {
266
- const contentEl = document.createElement('p');
267
- contentEl.textContent = content;
268
- card.appendChild(contentEl);
269
- }
270
-
271
- if (image) {
272
- const img = document.createElement('img');
273
- img.src = image;
274
- img.alt = title || 'Card image';
275
- card.appendChild(img);
276
- }
277
-
278
- return card;
279
- }
280
-
281
- /**
282
- * Create modal component
283
- */
284
- createModal({ title, content, actions = [] }) {
285
- const modal = document.createElement('af-modal');
286
- modal.setAttribute('open', '');
287
-
288
- if (title) {
289
- const titleEl = document.createElement('h2');
290
- titleEl.slot = 'header';
291
- titleEl.textContent = title;
292
- modal.appendChild(titleEl);
293
- }
294
-
295
- if (content) {
296
- const contentEl = document.createElement('p');
297
- contentEl.textContent = content;
298
- modal.appendChild(contentEl);
299
- }
300
-
301
- const actionsContainer = document.createElement('div');
302
- actionsContainer.slot = 'footer';
303
-
304
- for (const action of actions) {
305
- const button = document.createElement('af-button');
306
- button.textContent = action.label;
307
- if (action.primary) {
308
- button.setAttribute('variant', 'primary');
309
- }
310
- if (action.onClick) {
311
- button.addEventListener('click', action.onClick);
312
- }
313
- actionsContainer.appendChild(button);
314
- }
315
-
316
- modal.appendChild(actionsContainer);
317
- return modal;
318
- }
319
-
320
- /**
321
- * Create toast component
322
- */
323
- createToast({ message, type = 'info', duration = 3000 }) {
324
- const toast = document.createElement('af-toast');
325
- toast.setAttribute('type', type);
326
- toast.textContent = message;
327
-
328
- // Auto-remove after duration
329
- setTimeout(() => {
330
- toast.remove();
331
- }, duration);
332
-
333
- return toast;
334
- }
335
-
336
- /**
337
- * Create progress component
338
- */
339
- createProgress({ value = 0, max = 100, label }) {
340
- const progress = document.createElement('af-progress');
341
- progress.setAttribute('value', value);
342
- progress.setAttribute('max', max);
343
-
344
- if (label) {
345
- progress.setAttribute('label', label);
346
- }
347
-
348
- return progress;
349
- }
350
-
351
- /**
352
- * Create chart component
353
- */
354
- createChart({ type = 'bar', data = [], labels = [], title, options = {} }) {
355
- const chart = document.createElement('af-chart');
356
-
357
- chart.setAttribute('type', type);
358
- chart.setAttribute('data', JSON.stringify(data));
359
- chart.setAttribute('labels', JSON.stringify(labels));
360
-
361
- if (title) {
362
- chart.setAttribute('title', title);
363
- }
364
-
365
- if (options) {
366
- chart.setAttribute('options', JSON.stringify(options));
367
- }
368
-
369
- return chart;
370
- }
371
-
372
- /**
373
- * Create datatable component
374
- */
375
- createDatatable({ columns = [], rows = [], title, options = {} }) {
376
- const table = document.createElement('af-datatable');
377
-
378
- table.setAttribute('columns', JSON.stringify(columns));
379
- table.setAttribute('rows', JSON.stringify(rows));
380
-
381
- if (title) {
382
- table.setAttribute('title', title);
383
- }
384
-
385
- if (options) {
386
- table.setAttribute('options', JSON.stringify(options));
387
- }
388
-
389
- return table;
390
- }
391
-
392
- /**
393
- * Create tabs component
394
- */
395
- createTabs({ tabs = [], activeTab = 0 }) {
396
- const tabsContainer = document.createElement('af-tabs');
397
- tabsContainer.setAttribute('active', activeTab);
398
-
399
- for (let i = 0; i < tabs.length; i++) {
400
- const tab = tabs[i];
401
- const tabButton = document.createElement('af-tab-button');
402
- tabButton.setAttribute('tab-id', i);
403
- tabButton.textContent = tab.title;
404
-
405
- const tabContent = document.createElement('af-tab-content');
406
- tabContent.setAttribute('tab-id', i);
407
- tabContent.innerHTML = tab.content || '';
408
-
409
- tabsContainer.appendChild(tabButton);
410
- tabsContainer.appendChild(tabContent);
411
- }
412
-
413
- return tabsContainer;
414
- }
415
-
416
- /**
417
- * Create accordion component
418
- */
419
- createAccordion({ items = [] }) {
420
- const accordion = document.createElement('af-accordion');
421
-
422
- for (const item of items) {
423
- const panel = document.createElement('af-accordion-panel');
424
-
425
- const header = document.createElement('af-accordion-header');
426
- header.textContent = item.title;
427
-
428
- const content = document.createElement('af-accordion-content');
429
- content.innerHTML = item.content || '';
430
-
431
- panel.appendChild(header);
432
- panel.appendChild(content);
433
- accordion.appendChild(panel);
434
- }
435
-
436
- return accordion;
437
- }
438
-
439
- /**
440
- * Create stepper component
441
- */
442
- createStepper({ steps = [], currentStep = 0 }) {
443
- const stepper = document.createElement('af-stepper');
444
- stepper.setAttribute('current-step', currentStep);
445
-
446
- for (let i = 0; i < steps.length; i++) {
447
- const step = document.createElement('af-step');
448
- step.setAttribute('step-number', i + 1);
449
- step.setAttribute('active', i <= currentStep);
450
-
451
- if (i === currentStep) {
452
- step.setAttribute('current', 'true');
453
- }
454
-
455
- step.textContent = steps[i].title || `Step ${i + 1}`;
456
- stepper.appendChild(step);
457
- }
458
-
459
- return stepper;
460
- }
461
-
462
- /**
463
- * Create dashboard widget component
464
- */
465
- createDashboardWidget({ title, content, type = 'card', size = 'medium', actions = [] }) {
466
- const widget = document.createElement('af-dashboard-widget');
467
- widget.setAttribute('type', type);
468
- widget.setAttribute('size', size);
469
-
470
- if (title) {
471
- const header = document.createElement('h3');
472
- header.className = 'widget-title';
473
- header.textContent = title;
474
- widget.appendChild(header);
475
- }
476
-
477
- if (content) {
478
- const contentEl = document.createElement('div');
479
- contentEl.className = 'widget-content';
480
- contentEl.innerHTML = typeof content === 'string' ? content : JSON.stringify(content);
481
- widget.appendChild(contentEl);
482
- }
483
-
484
- if (actions.length > 0) {
485
- const actionsEl = document.createElement('div');
486
- actionsEl.className = 'widget-actions';
487
-
488
- for (const action of actions) {
489
- const button = document.createElement('af-button');
490
- button.textContent = action.label;
491
- button.setAttribute('variant', action.variant || 'secondary');
492
- if (action.onClick) {
493
- button.addEventListener('click', action.onClick);
494
- }
495
- actionsEl.appendChild(button);
496
- }
497
-
498
- widget.appendChild(actionsEl);
499
- }
500
-
501
- return widget;
502
- }
503
-
504
- /**
505
- * Update existing component
506
- */
507
- update(id, newProps) {
508
- const element = this.components.get(id);
509
- if (element) {
510
- Object.assign(element, newProps);
511
- }
512
- }
513
-
514
- /**
515
- * Remove component
516
- */
517
- remove(id) {
518
- const element = this.components.get(id);
519
- if (element) {
520
- element.remove();
521
- this.components.delete(id);
522
- }
523
- }
524
- }
525
-
526
- /**
527
- * A2UI Protocol Handler
528
- * Processes streaming A2UI messages from AI agents
529
- */
530
- export class A2UIProtocol {
531
- constructor(renderer) {
532
- this.renderer = renderer;
533
- this.messageQueue = [];
534
- this.messageHandlers = [];
535
- this.isProcessing = false;
536
- }
537
-
538
- /**
539
- * Register a message handler callback
540
- * @param {Function} callback - Handler to receive processed messages
541
- */
542
- onMessage(callback) {
543
- if (typeof callback === 'function') {
544
- this.messageHandlers.push(callback);
545
- }
546
- }
547
-
548
- /**
549
- * Send a message into the A2UI system
550
- * @param {Object|string} message - A2UI message
551
- */
552
- sendMessage(message) {
553
- return this.processMessage(message);
554
- }
555
-
556
- /**
557
- * Process incoming A2UI message
558
- * @param {Object|string} message - A2UI message
559
- */
560
- processMessage(message) {
561
- if (typeof message === 'string') {
562
- try {
563
- message = JSON.parse(message);
564
- } catch {
565
- console.warn('Invalid A2UI message format:', message);
566
- return null;
567
- }
568
- }
569
-
570
- if (message?.type === 'render' && this.renderer) {
571
- return this.renderer.render(message);
572
- }
573
-
574
- for (const handler of this.messageHandlers) {
575
- handler(message);
576
- }
577
-
578
- return message;
579
- }
580
-
581
- /**
582
- * Process queued messages
583
- */
584
- processQueue() {
585
- if (this.isProcessing || this.messageQueue.length === 0) {
586
- return;
587
- }
588
-
589
- this.isProcessing = true;
590
-
591
- while (this.messageQueue.length > 0) {
592
- const message = this.messageQueue.shift();
593
-
594
- try {
595
- this.renderer.render(message);
596
- } catch (error) {
597
- console.error('A2UI render error:', error);
598
- }
599
- }
600
-
601
- this.isProcessing = false;
602
- }
603
-
604
- /**
605
- * Stream handler for real-time AI responses
606
- * @param {ReadableStream} stream - AI response stream
607
- */
608
- async handleStream(stream) {
609
- const reader = stream.getReader();
610
- const decoder = new TextDecoder();
611
-
612
- let buffer = '';
613
-
614
- while (true) {
615
- const { done, value } = await reader.read();
616
-
617
- if (done) {
618
- break;
619
- }
620
-
621
- buffer += decoder.decode(value, { stream: true });
622
-
623
- // Process complete messages
624
- const messages = buffer.split('\n');
625
- buffer = messages.pop(); // Keep incomplete message in buffer
626
-
627
- for (const message of messages) {
628
- if (message.trim()) {
629
- this.processMessage(message.trim());
630
- }
631
- }
632
- }
633
-
634
- // Process any remaining buffer
635
- if (buffer.trim()) {
636
- this.processMessage(buffer.trim());
637
- }
638
- }
639
-
640
- createStream() {
641
- const subscribers = new Set();
642
-
643
- return {
644
- subscribe(callback) {
645
- if (typeof callback !== 'function') {
646
- return () => {};
647
- }
648
-
649
- subscribers.add(callback);
650
- return () => subscribers.delete(callback);
651
- },
652
- push(message) {
653
- for (const callback of subscribers) {
654
- callback(message);
655
- }
656
- }
657
- };
658
- }
659
-
660
- validateAgainstSchema(component) {
661
- const tag = component?.tag || component?.tagName;
662
- return Promise.resolve(Boolean(tag && coreComponentMap[tag]));
663
- }
664
- }
665
-
666
- /**
667
- * Initialize A2UI system
668
- * @param {HTMLElement} root - Root element for rendering
669
- */
670
- export function initA2UI(root) {
671
- // Handle server-side rendering (no DOM)
672
- if (typeof document === 'undefined') {
673
- root = null;
674
- } else {
675
- root = root || document.body;
676
- }
677
-
678
- const renderer = new A2UIRenderer(root);
679
- const protocol = new A2UIProtocol(renderer);
680
-
681
- // Make globally available for AI agents
682
- if (typeof window !== 'undefined') {
683
- window.a2ui = {
684
- render: (message) => protocol.processMessage(message),
685
- handleStream: (stream) => protocol.handleStream(stream),
686
- update: (id, props) => renderer.update(id, props),
687
- remove: (id) => renderer.remove(id),
688
- sendMessage: (message) => protocol.sendMessage(message),
689
- onMessage: (callback) => protocol.onMessage(callback),
690
- createStream: () => protocol.createStream(),
691
- validateAgainstSchema: (component) => protocol.validateAgainstSchema(component)
692
- };
693
- }
694
-
695
- return { renderer, protocol };
696
- }
1
+ /**
2
+ * A2UI Protocol Implementation
3
+ * Agent-to-User Interface declarative protocol for generative AI
4
+ *
5
+ * Enables AI agents to return UI widgets as part of responses without
6
+ * executing arbitrary code, ensuring security and consistency.
7
+ *
8
+ * @module core/a2ui
9
+ */
10
+
11
+ import { componentMap as coreComponentMap } from '../components/index.js';
12
+
13
+ /**
14
+ * A2UI Message Types
15
+ */
16
+ export const A2UI_TYPES = {
17
+ COMPONENT: 'component',
18
+ FORM: 'form',
19
+ LIST: 'list',
20
+ CARD: 'card',
21
+ MODAL: 'modal',
22
+ TOAST: 'toast',
23
+ PROGRESS: 'progress',
24
+ CHART: 'chart',
25
+ DATATABLE: 'datatable',
26
+ TABS: 'tabs',
27
+ ACCORDION: 'accordion',
28
+ STEPPER: 'stepper',
29
+ DASHBOARD_WIDGET: 'dashboard-widget'
30
+ };
31
+
32
+ /**
33
+ * A2UI Component Schemas
34
+ */
35
+ export const A2UI_SCHEMAS = {
36
+ component: {
37
+ type: 'object',
38
+ properties: {
39
+ id: { type: 'string' },
40
+ type: { type: 'string', enum: Object.values(A2UI_TYPES) },
41
+ props: { type: 'object' },
42
+ children: { type: 'array', items: { $ref: '#' } }
43
+ },
44
+ required: ['id', 'type']
45
+ }
46
+ };
47
+
48
+ function escapeHtml(value) {
49
+ return String(value)
50
+ .replace(/&/g, '&amp;')
51
+ .replace(/</g, '&lt;')
52
+ .replace(/>/g, '&gt;')
53
+ .replace(/"/g, '&quot;')
54
+ .replace(/'/g, '&#039;');
55
+ }
56
+
57
+ function renderNode(node) {
58
+ if (Array.isArray(node)) {
59
+ return node.map(renderNode).join('');
60
+ }
61
+
62
+ if (node === null || node === undefined || node === false) {
63
+ return '';
64
+ }
65
+
66
+ if (typeof node === 'string' || typeof node === 'number' || typeof node === 'boolean') {
67
+ return escapeHtml(node);
68
+ }
69
+
70
+ if (typeof node !== 'object') {
71
+ return '';
72
+ }
73
+
74
+ const tag = node.tag || node.tagName;
75
+ if (!tag) {
76
+ return '';
77
+ }
78
+
79
+ const props = node.props || {};
80
+ const attributes = Object.entries(props)
81
+ .filter(([, value]) => value !== null && value !== undefined && value !== false)
82
+ .map(([key, value]) => value === true ? key : `${key}="${escapeHtml(value)}"`)
83
+ .join(' ');
84
+
85
+ const children = renderNode(node.children ?? node.content ?? '');
86
+ return `<${tag}${attributes ? ` ${attributes}` : ''}>${children}</${tag}>`;
87
+ }
88
+
89
+ function isUnsafeHtml(html) {
90
+ return /<\s*script\b|on\w+\s*=|javascript:/i.test(String(html));
91
+ }
92
+
93
+ /**
94
+ * A2UI Renderer
95
+ * Renders A2UI messages into actual DOM elements
96
+ */
97
+ export class A2UIRenderer {
98
+ constructor(rootElement) {
99
+ this.root = rootElement;
100
+ this.components = new Map();
101
+ }
102
+
103
+ /**
104
+ * Render an A2UI message
105
+ * @param {Object} message - A2UI message object
106
+ */
107
+ render(message) {
108
+ if (!message || !message.type) {
109
+ throw new Error('Invalid A2UI message');
110
+ }
111
+
112
+ if (message.html !== undefined) {
113
+ if (isUnsafeHtml(message.html)) {
114
+ throw new Error('Unsafe HTML is not allowed in A2UI render messages');
115
+ }
116
+
117
+ throw new Error('Raw HTML payloads are not supported in A2UI render messages');
118
+ }
119
+
120
+ const output = Array.isArray(message.components)
121
+ ? message.components.map(renderNode).join('')
122
+ : renderNode(message.component || message);
123
+
124
+ if (message.id) {
125
+ this.components.set(message.id, {
126
+ id: message.id,
127
+ type: message.type,
128
+ props: message.props || {},
129
+ children: message.children || message.components || []
130
+ });
131
+ }
132
+
133
+ const canRenderToDOM = this.root && typeof this.root.appendChild === 'function' && typeof document !== 'undefined';
134
+ if (canRenderToDOM && output) {
135
+ const container = document.createElement('div');
136
+ container.innerHTML = output;
137
+ while (container.firstChild) {
138
+ this.root.appendChild(container.firstChild);
139
+ }
140
+ }
141
+
142
+ return output;
143
+ }
144
+
145
+ /**
146
+ * Create DOM element from A2UI component
147
+ * @param {Object} component - A2UI component definition
148
+ */
149
+ createElement(component) {
150
+ const { type, props = {}, children = [] } = component;
151
+
152
+ let element;
153
+
154
+ switch (type) {
155
+ case A2UI_TYPES.COMPONENT:
156
+ element = this.createCustomComponent(props);
157
+ break;
158
+ case A2UI_TYPES.FORM:
159
+ element = this.createForm(props);
160
+ break;
161
+ case A2UI_TYPES.LIST:
162
+ element = this.createList(props);
163
+ break;
164
+ case A2UI_TYPES.CARD:
165
+ element = this.createCard(props);
166
+ break;
167
+ case A2UI_TYPES.MODAL:
168
+ element = this.createModal(props);
169
+ break;
170
+ case A2UI_TYPES.TOAST:
171
+ element = this.createToast(props);
172
+ break;
173
+ case A2UI_TYPES.PROGRESS:
174
+ element = this.createProgress(props);
175
+ break;
176
+ case A2UI_TYPES.CHART:
177
+ element = this.createChart(props);
178
+ break;
179
+ case A2UI_TYPES.DATATABLE:
180
+ element = this.createDatatable(props);
181
+ break;
182
+ case A2UI_TYPES.TABS:
183
+ element = this.createTabs(props);
184
+ break;
185
+ case A2UI_TYPES.ACCORDION:
186
+ element = this.createAccordion(props);
187
+ break;
188
+ case A2UI_TYPES.STEPPER:
189
+ element = this.createStepper(props);
190
+ break;
191
+ case A2UI_TYPES.DASHBOARD_WIDGET:
192
+ element = this.createDashboardWidget(props);
193
+ break;
194
+ default:
195
+ throw new Error(`Unknown A2UI component type: ${type}`);
196
+ }
197
+
198
+ // Render children
199
+ if (children.length > 0) {
200
+ for (const child of children) {
201
+ const childElement = this.createElement(child);
202
+ element.appendChild(childElement);
203
+ }
204
+ }
205
+
206
+ return element;
207
+ }
208
+
209
+ /**
210
+ * Create custom AfriCode component
211
+ */
212
+ createCustomComponent({ tag, ...props }) {
213
+ const element = document.createElement(tag || 'div');
214
+ Object.assign(element, props);
215
+ return element;
216
+ }
217
+
218
+ /**
219
+ * Create form component
220
+ */
221
+ createForm({ fields = [], onSubmit }) {
222
+ const form = document.createElement('af-form');
223
+
224
+ for (const field of fields) {
225
+ const input = document.createElement('af-input');
226
+ input.setAttribute('name', field.name);
227
+ input.setAttribute('placeholder', field.placeholder || '');
228
+ input.setAttribute('type', field.type || 'text');
229
+ form.appendChild(input);
230
+ }
231
+
232
+ if (onSubmit) {
233
+ form.addEventListener('submit', onSubmit);
234
+ }
235
+
236
+ return form;
237
+ }
238
+
239
+ /**
240
+ * Create list component
241
+ */
242
+ createList({ items = [] }) {
243
+ const list = document.createElement('af-grid');
244
+
245
+ for (const item of items) {
246
+ const card = this.createCard(item);
247
+ list.appendChild(card);
248
+ }
249
+
250
+ return list;
251
+ }
252
+
253
+ /**
254
+ * Create card component
255
+ */
256
+ createCard({ title, content, image }) {
257
+ const card = document.createElement('af-card');
258
+
259
+ if (title) {
260
+ const titleEl = document.createElement('h3');
261
+ titleEl.textContent = title;
262
+ card.appendChild(titleEl);
263
+ }
264
+
265
+ if (content) {
266
+ const contentEl = document.createElement('p');
267
+ contentEl.textContent = content;
268
+ card.appendChild(contentEl);
269
+ }
270
+
271
+ if (image) {
272
+ const img = document.createElement('img');
273
+ img.src = image;
274
+ img.alt = title || 'Card image';
275
+ card.appendChild(img);
276
+ }
277
+
278
+ return card;
279
+ }
280
+
281
+ /**
282
+ * Create modal component
283
+ */
284
+ createModal({ title, content, actions = [] }) {
285
+ const modal = document.createElement('af-modal');
286
+ modal.setAttribute('open', '');
287
+
288
+ if (title) {
289
+ const titleEl = document.createElement('h2');
290
+ titleEl.slot = 'header';
291
+ titleEl.textContent = title;
292
+ modal.appendChild(titleEl);
293
+ }
294
+
295
+ if (content) {
296
+ const contentEl = document.createElement('p');
297
+ contentEl.textContent = content;
298
+ modal.appendChild(contentEl);
299
+ }
300
+
301
+ const actionsContainer = document.createElement('div');
302
+ actionsContainer.slot = 'footer';
303
+
304
+ for (const action of actions) {
305
+ const button = document.createElement('af-button');
306
+ button.textContent = action.label;
307
+ if (action.primary) {
308
+ button.setAttribute('variant', 'primary');
309
+ }
310
+ if (action.onClick) {
311
+ button.addEventListener('click', action.onClick);
312
+ }
313
+ actionsContainer.appendChild(button);
314
+ }
315
+
316
+ modal.appendChild(actionsContainer);
317
+ return modal;
318
+ }
319
+
320
+ /**
321
+ * Create toast component
322
+ */
323
+ createToast({ message, type = 'info', duration = 3000 }) {
324
+ const toast = document.createElement('af-toast');
325
+ toast.setAttribute('type', type);
326
+ toast.textContent = message;
327
+
328
+ // Auto-remove after duration
329
+ setTimeout(() => {
330
+ toast.remove();
331
+ }, duration);
332
+
333
+ return toast;
334
+ }
335
+
336
+ /**
337
+ * Create progress component
338
+ */
339
+ createProgress({ value = 0, max = 100, label }) {
340
+ const progress = document.createElement('af-progress');
341
+ progress.setAttribute('value', value);
342
+ progress.setAttribute('max', max);
343
+
344
+ if (label) {
345
+ progress.setAttribute('label', label);
346
+ }
347
+
348
+ return progress;
349
+ }
350
+
351
+ /**
352
+ * Create chart component
353
+ */
354
+ createChart({ type = 'bar', data = [], labels = [], title, options = {} }) {
355
+ const chart = document.createElement('af-chart');
356
+
357
+ chart.setAttribute('type', type);
358
+ chart.setAttribute('data', JSON.stringify(data));
359
+ chart.setAttribute('labels', JSON.stringify(labels));
360
+
361
+ if (title) {
362
+ chart.setAttribute('title', title);
363
+ }
364
+
365
+ if (options) {
366
+ chart.setAttribute('options', JSON.stringify(options));
367
+ }
368
+
369
+ return chart;
370
+ }
371
+
372
+ /**
373
+ * Create datatable component
374
+ */
375
+ createDatatable({ columns = [], rows = [], title, options = {} }) {
376
+ const table = document.createElement('af-datatable');
377
+
378
+ table.setAttribute('columns', JSON.stringify(columns));
379
+ table.setAttribute('rows', JSON.stringify(rows));
380
+
381
+ if (title) {
382
+ table.setAttribute('title', title);
383
+ }
384
+
385
+ if (options) {
386
+ table.setAttribute('options', JSON.stringify(options));
387
+ }
388
+
389
+ return table;
390
+ }
391
+
392
+ /**
393
+ * Create tabs component
394
+ */
395
+ createTabs({ tabs = [], activeTab = 0 }) {
396
+ const tabsContainer = document.createElement('af-tabs');
397
+ tabsContainer.setAttribute('active', activeTab);
398
+
399
+ for (let i = 0; i < tabs.length; i++) {
400
+ const tab = tabs[i];
401
+ const tabButton = document.createElement('af-tab-button');
402
+ tabButton.setAttribute('tab-id', i);
403
+ tabButton.textContent = tab.title;
404
+
405
+ const tabContent = document.createElement('af-tab-content');
406
+ tabContent.setAttribute('tab-id', i);
407
+ tabContent.innerHTML = tab.content || '';
408
+
409
+ tabsContainer.appendChild(tabButton);
410
+ tabsContainer.appendChild(tabContent);
411
+ }
412
+
413
+ return tabsContainer;
414
+ }
415
+
416
+ /**
417
+ * Create accordion component
418
+ */
419
+ createAccordion({ items = [] }) {
420
+ const accordion = document.createElement('af-accordion');
421
+
422
+ for (const item of items) {
423
+ const panel = document.createElement('af-accordion-panel');
424
+
425
+ const header = document.createElement('af-accordion-header');
426
+ header.textContent = item.title;
427
+
428
+ const content = document.createElement('af-accordion-content');
429
+ content.innerHTML = item.content || '';
430
+
431
+ panel.appendChild(header);
432
+ panel.appendChild(content);
433
+ accordion.appendChild(panel);
434
+ }
435
+
436
+ return accordion;
437
+ }
438
+
439
+ /**
440
+ * Create stepper component
441
+ */
442
+ createStepper({ steps = [], currentStep = 0 }) {
443
+ const stepper = document.createElement('af-stepper');
444
+ stepper.setAttribute('current-step', currentStep);
445
+
446
+ for (let i = 0; i < steps.length; i++) {
447
+ const step = document.createElement('af-step');
448
+ step.setAttribute('step-number', i + 1);
449
+ step.setAttribute('active', i <= currentStep);
450
+
451
+ if (i === currentStep) {
452
+ step.setAttribute('current', 'true');
453
+ }
454
+
455
+ step.textContent = steps[i].title || `Step ${i + 1}`;
456
+ stepper.appendChild(step);
457
+ }
458
+
459
+ return stepper;
460
+ }
461
+
462
+ /**
463
+ * Create dashboard widget component
464
+ */
465
+ createDashboardWidget({ title, content, type = 'card', size = 'medium', actions = [] }) {
466
+ const widget = document.createElement('af-dashboard-widget');
467
+ widget.setAttribute('type', type);
468
+ widget.setAttribute('size', size);
469
+
470
+ if (title) {
471
+ const header = document.createElement('h3');
472
+ header.className = 'widget-title';
473
+ header.textContent = title;
474
+ widget.appendChild(header);
475
+ }
476
+
477
+ if (content) {
478
+ const contentEl = document.createElement('div');
479
+ contentEl.className = 'widget-content';
480
+ contentEl.innerHTML = typeof content === 'string' ? content : JSON.stringify(content);
481
+ widget.appendChild(contentEl);
482
+ }
483
+
484
+ if (actions.length > 0) {
485
+ const actionsEl = document.createElement('div');
486
+ actionsEl.className = 'widget-actions';
487
+
488
+ for (const action of actions) {
489
+ const button = document.createElement('af-button');
490
+ button.textContent = action.label;
491
+ button.setAttribute('variant', action.variant || 'secondary');
492
+ if (action.onClick) {
493
+ button.addEventListener('click', action.onClick);
494
+ }
495
+ actionsEl.appendChild(button);
496
+ }
497
+
498
+ widget.appendChild(actionsEl);
499
+ }
500
+
501
+ return widget;
502
+ }
503
+
504
+ /**
505
+ * Update existing component
506
+ */
507
+ update(id, newProps) {
508
+ const element = this.components.get(id);
509
+ if (element) {
510
+ Object.assign(element, newProps);
511
+ }
512
+ }
513
+
514
+ /**
515
+ * Remove component
516
+ */
517
+ remove(id) {
518
+ const element = this.components.get(id);
519
+ if (element) {
520
+ element.remove();
521
+ this.components.delete(id);
522
+ }
523
+ }
524
+ }
525
+
526
+ /**
527
+ * A2UI Protocol Handler
528
+ * Processes streaming A2UI messages from AI agents
529
+ */
530
+ export class A2UIProtocol {
531
+ constructor(renderer) {
532
+ this.renderer = renderer;
533
+ this.messageQueue = [];
534
+ this.messageHandlers = [];
535
+ this.isProcessing = false;
536
+ }
537
+
538
+ /**
539
+ * Register a message handler callback
540
+ * @param {Function} callback - Handler to receive processed messages
541
+ */
542
+ onMessage(callback) {
543
+ if (typeof callback === 'function') {
544
+ this.messageHandlers.push(callback);
545
+ }
546
+ }
547
+
548
+ /**
549
+ * Send a message into the A2UI system
550
+ * @param {Object|string} message - A2UI message
551
+ */
552
+ sendMessage(message) {
553
+ return this.processMessage(message);
554
+ }
555
+
556
+ /**
557
+ * Process incoming A2UI message
558
+ * @param {Object|string} message - A2UI message
559
+ */
560
+ processMessage(message) {
561
+ if (typeof message === 'string') {
562
+ try {
563
+ message = JSON.parse(message);
564
+ } catch {
565
+ console.warn('Invalid A2UI message format:', message);
566
+ return null;
567
+ }
568
+ }
569
+
570
+ if (message?.type === 'render' && this.renderer) {
571
+ return this.renderer.render(message);
572
+ }
573
+
574
+ for (const handler of this.messageHandlers) {
575
+ handler(message);
576
+ }
577
+
578
+ return message;
579
+ }
580
+
581
+ /**
582
+ * Process queued messages
583
+ */
584
+ processQueue() {
585
+ if (this.isProcessing || this.messageQueue.length === 0) {
586
+ return;
587
+ }
588
+
589
+ this.isProcessing = true;
590
+
591
+ while (this.messageQueue.length > 0) {
592
+ const message = this.messageQueue.shift();
593
+
594
+ try {
595
+ this.renderer.render(message);
596
+ } catch (error) {
597
+ console.error('A2UI render error:', error);
598
+ }
599
+ }
600
+
601
+ this.isProcessing = false;
602
+ }
603
+
604
+ /**
605
+ * Stream handler for real-time AI responses
606
+ * @param {ReadableStream} stream - AI response stream
607
+ */
608
+ async handleStream(stream) {
609
+ const reader = stream.getReader();
610
+ const decoder = new TextDecoder();
611
+
612
+ let buffer = '';
613
+
614
+ while (true) {
615
+ const { done, value } = await reader.read();
616
+
617
+ if (done) {
618
+ break;
619
+ }
620
+
621
+ buffer += decoder.decode(value, { stream: true });
622
+
623
+ // Process complete messages
624
+ const messages = buffer.split('\n');
625
+ buffer = messages.pop(); // Keep incomplete message in buffer
626
+
627
+ for (const message of messages) {
628
+ if (message.trim()) {
629
+ this.processMessage(message.trim());
630
+ }
631
+ }
632
+ }
633
+
634
+ // Process any remaining buffer
635
+ if (buffer.trim()) {
636
+ this.processMessage(buffer.trim());
637
+ }
638
+ }
639
+
640
+ createStream() {
641
+ const subscribers = new Set();
642
+
643
+ return {
644
+ subscribe(callback) {
645
+ if (typeof callback !== 'function') {
646
+ return () => {};
647
+ }
648
+
649
+ subscribers.add(callback);
650
+ return () => subscribers.delete(callback);
651
+ },
652
+ push(message) {
653
+ for (const callback of subscribers) {
654
+ callback(message);
655
+ }
656
+ }
657
+ };
658
+ }
659
+
660
+ validateAgainstSchema(component) {
661
+ const tag = component?.tag || component?.tagName;
662
+ return Promise.resolve(Boolean(tag && coreComponentMap[tag]));
663
+ }
664
+ }
665
+
666
+ /**
667
+ * Initialize A2UI system
668
+ * @param {HTMLElement} root - Root element for rendering
669
+ */
670
+ export function initA2UI(root) {
671
+ // Handle server-side rendering (no DOM)
672
+ if (typeof document === 'undefined') {
673
+ root = null;
674
+ } else {
675
+ root = root || document.body;
676
+ }
677
+
678
+ const renderer = new A2UIRenderer(root);
679
+ const protocol = new A2UIProtocol(renderer);
680
+
681
+ // Make globally available for AI agents
682
+ if (typeof window !== 'undefined') {
683
+ window.a2ui = {
684
+ render: (message) => protocol.processMessage(message),
685
+ handleStream: (stream) => protocol.handleStream(stream),
686
+ update: (id, props) => renderer.update(id, props),
687
+ remove: (id) => renderer.remove(id),
688
+ sendMessage: (message) => protocol.sendMessage(message),
689
+ onMessage: (callback) => protocol.onMessage(callback),
690
+ createStream: () => protocol.createStream(),
691
+ validateAgainstSchema: (component) => protocol.validateAgainstSchema(component)
692
+ };
693
+ }
694
+
695
+ return { renderer, protocol };
696
+ }