@africode/core 5.0.0 → 5.0.2

package/components/base.d.ts

@@ -56,7 +56,7 @@ export class AfriCodeComponent extends HTMLElement {
   /**
    * Load and apply component styles
    */
-  loadStyles(css?: string): void;
+  loadStyles(css?: string): Promise<void>;
 
   /**
    * Render component to shadow DOM

package/components/base.js

@@ -9,11 +9,14 @@
 
 import { html } from '../core/html.js';
 
+const BaseHTMLElement = globalThis.HTMLElement ?? class {};
+const hasConstructableStylesheets = typeof CSSStyleSheet !== 'undefined';
+
 /**
  * Base class for AfriCode components
  * All components extend this to inherit common functionality
  */
-export class AfriCodeComponent extends HTMLElement {
+export class AfriCodeComponent extends BaseHTMLElement {
     constructor() {
         super();
         this.attachShadow({ mode: 'open' });
@@ -84,8 +87,11 @@ export class AfriCodeComponent extends HTMLElement {
      * @param {CSSStyleSheet} sheet - A Constructable Stylesheet instance
      */
     static injectGlobalSheet(sheet) {
+        if (!hasConstructableStylesheets) {
+            return;
+        }
+
         if (!(sheet instanceof CSSStyleSheet)) {
-            console.error('[AfriCode] injectGlobalSheet requires a CSSStyleSheet instance.');
             return;
         }
         if (!AfriCodeComponent.globalSheets.includes(sheet)) {
@@ -98,37 +104,77 @@ export class AfriCodeComponent extends HTMLElement {
      * Optimized to fetch only once per session.
      * Also adopts any globally injected sheets (e.g. Tailwind utilities).
      */
-    async loadStyles() {
+    async loadStyles(css = '') {
         const styleUrl = '/styles/africanity.css';
+        if (!this.shadowRoot) {
+            return;
+        }
+
+        const canAdoptStyleSheets = hasConstructableStylesheets && 'adoptedStyleSheets' in this.shadowRoot;
+        const sourceKey = typeof css === 'string' && css.length > 0 ? css : styleUrl;
+        const stylesheetText = typeof css === 'string' && css.length > 0 ? css : null;
 
         // 1. Check cache first
-        if (AfriCodeComponent.styleCache.has(styleUrl)) {
-            this.shadowRoot.adoptedStyleSheets = [
-                AfriCodeComponent.styleCache.get(styleUrl),
-                ...AfriCodeComponent.globalSheets
-            ];
+        if (AfriCodeComponent.styleCache.has(sourceKey)) {
+            const cached = AfriCodeComponent.styleCache.get(sourceKey);
+            if (canAdoptStyleSheets) {
+                this.shadowRoot.adoptedStyleSheets = [
+                    cached,
+                    ...AfriCodeComponent.globalSheets
+                ];
+            } else {
+                this._applyFallbackStyle(cached?.cssText || cached?.text || cached || '');
+            }
             return;
         }
 
         // 2. Fetch if not cached (Single Request)
         try {
-            const response = await fetch(styleUrl);
-            const css = await response.text();
+            let resolvedCss = stylesheetText;
 
-            const styleSheet = new CSSStyleSheet();
-            styleSheet.replaceSync(css);
+            if (!resolvedCss) {
+                const response = await fetch(styleUrl);
+                if (!response.ok) {
+                    throw new Error(`Unable to load stylesheet: ${response.status}`);
+                }
+                resolvedCss = await response.text();
+            }
+
+            if (canAdoptStyleSheets) {
+                const styleSheet = new CSSStyleSheet();
+                styleSheet.replaceSync(resolvedCss);
+
+                // Cache it
+                AfriCodeComponent.styleCache.set(sourceKey, styleSheet);
+
+                // Apply core + any global sheets
+                this.shadowRoot.adoptedStyleSheets = [
+                    styleSheet,
+                    ...AfriCodeComponent.globalSheets
+                ];
+                return;
+            }
+
+            this._applyFallbackStyle(resolvedCss);
+            AfriCodeComponent.styleCache.set(sourceKey, { text: resolvedCss });
+        } catch (err) {
+            this._applyFallbackStyle(stylesheetText || '');
+        }
+    }
 
-            // Cache it
-            AfriCodeComponent.styleCache.set(styleUrl, styleSheet);
+    _applyFallbackStyle(css) {
+        if (!this.shadowRoot) {
+            return;
+        }
 
-            // Apply core + any global sheets
-            this.shadowRoot.adoptedStyleSheets = [
-                styleSheet,
-                ...AfriCodeComponent.globalSheets
-            ];
-        } catch (err) {
-            console.warn('AfriCode: Failed to load core styles', err);
+        let style = this.shadowRoot.querySelector('style[data-africode-core-styles]');
+        if (!style) {
+            style = document.createElement('style');
+            style.setAttribute('data-africode-core-styles', '');
+            this.shadowRoot.prepend(style);
         }
+
+        style.textContent = css;
     }
 
     /**
@@ -175,6 +221,10 @@ export class AfriCodeComponent extends HTMLElement {
  * @param {typeof HTMLElement} component - Component class
  */
 export function registerComponent(name, component) {
+    if (typeof customElements === 'undefined') {
+        return;
+    }
+
     if (!customElements.get(name)) {
         customElements.define(name, component);
     }

package/core/a2ui-schema-manager.js

@@ -170,7 +170,7 @@ export class A2UISchemaManager {
         }));
 
         // Extract CSS custom properties
-        const cssMatches = [...content.matchAll(/var\(['--([a-z0-9-]+)['"\)]/g)];
+        const cssMatches = [...content.matchAll(/var\(--([a-z0-9-]+)\)/g)];
         const cssCustomProperties = cssMatches.map(m => '--' + m[1]);
 
         // Extract JSDoc comments
@@ -217,7 +217,7 @@ export class A2UISchemaManager {
                     errors.push('Forbidden: eval() detected');
                 }
             } else if (pattern === 'innerHTML = userInput') {
-                if (/innerHTML\s*=\s*(?!`[^`]*<[a-z]/i.test(html)) {
+                if (/innerHTML\s*=/i.test(html)) {
                     warnings.push('Warning: innerHTML assignment detected — ensure content is sanitized');
                 }
             }
@@ -266,6 +266,11 @@ export class A2UISchemaManager {
 
         return this.schema;
     }
+
+    /**
+     * Validate component props against the generated schema
+     */
+    validateComponent(tagName, props = {}) {
         const component = this.schema.components.find(c => c.tagName === tagName);
         if (!component) {
             return { valid: false, error: `Component ${tagName} not found in schema` };
@@ -327,6 +332,8 @@ export class A2UISchemaManager {
     }
 }
 
+export { A2UISchemaManager as A2uiSchemaManager };
+
 /**
  * CLI Usage
  * node core/a2ui-schema-manager.js generate

package/core/a2ui.js

@@ -8,6 +8,8 @@
  * @module core/a2ui
  */
 
+import { componentMap as coreComponentMap } from '../components/index.js';
+
 /**
  * A2UI Message Types
  */
@@ -37,6 +39,51 @@ export const A2UI_SCHEMAS = {
     }
 };
 
+function escapeHtml(value) {
+    return String(value)
+        .replace(/&/g, '&')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;')
+        .replace(/'/g, '&#039;');
+}
+
+function renderNode(node) {
+    if (Array.isArray(node)) {
+        return node.map(renderNode).join('');
+    }
+
+    if (node === null || node === undefined || node === false) {
+        return '';
+    }
+
+    if (typeof node === 'string' || typeof node === 'number' || typeof node === 'boolean') {
+        return escapeHtml(node);
+    }
+
+    if (typeof node !== 'object') {
+        return '';
+    }
+
+    const tag = node.tag || node.tagName;
+    if (!tag) {
+        return '';
+    }
+
+    const props = node.props || {};
+    const attributes = Object.entries(props)
+        .filter(([, value]) => value !== null && value !== undefined && value !== false)
+        .map(([key, value]) => value === true ? key : `${key}="${escapeHtml(value)}"`)
+        .join(' ');
+
+    const children = renderNode(node.children ?? node.content ?? '');
+    return `<${tag}${attributes ? ` ${attributes}` : ''}>${children}</${tag}>`;
+}
+
+function isUnsafeHtml(html) {
+    return /<\s*script\b|on\w+\s*=|javascript:/i.test(String(html));
+}
+
 /**
  * A2UI Renderer
  * Renders A2UI messages into actual DOM elements
@@ -51,63 +98,74 @@ export class A2UIRenderer {
      * Render an A2UI message
      * @param {Object} message - A2UI message object
      */
-    async render(message) {
+    render(message) {
         if (!message || !message.type) {
             throw new Error('Invalid A2UI message');
         }
 
-        const canRenderToDOM = this.root && typeof this.root.appendChild === 'function';
+        if (message.html !== undefined) {
+            if (isUnsafeHtml(message.html)) {
+                throw new Error('Unsafe HTML is not allowed in A2UI render messages');
+            }
+
+            throw new Error('Raw HTML payloads are not supported in A2UI render messages');
+        }
+
+        const output = Array.isArray(message.components)
+            ? message.components.map(renderNode).join('')
+            : renderNode(message.component || message);
 
-        if (!canRenderToDOM) {
-            const placeholder = {
-                id: message.id || `a2ui-${Date.now()}`,
+        if (message.id) {
+            this.components.set(message.id, {
+                id: message.id,
                 type: message.type,
                 props: message.props || {},
-                children: message.children || []
-            };
+                children: message.children || message.components || []
+            });
+        }
 
-            if (placeholder.id) {
-                this.components.set(placeholder.id, placeholder);
+        const canRenderToDOM = this.root && typeof this.root.appendChild === 'function' && typeof document !== 'undefined';
+        if (canRenderToDOM && output) {
+            const container = document.createElement('div');
+            container.innerHTML = output;
+            while (container.firstChild) {
+                this.root.appendChild(container.firstChild);
             }
-
-            return placeholder;
         }
 
-        const element = await this.createElement(message);
-        this.root.appendChild(element);
-        return element;
+        return output;
     }
 
     /**
      * Create DOM element from A2UI component
      * @param {Object} component - A2UI component definition
      */
-    async createElement(component) {
+    createElement(component) {
         const { type, props = {}, children = [] } = component;
 
         let element;
 
         switch (type) {
             case A2UI_TYPES.COMPONENT:
-                element = await this.createCustomComponent(props);
+                element = this.createCustomComponent(props);
                 break;
             case A2UI_TYPES.FORM:
-                element = await this.createForm(props);
+                element = this.createForm(props);
                 break;
             case A2UI_TYPES.LIST:
-                element = await this.createList(props);
+                element = this.createList(props);
                 break;
             case A2UI_TYPES.CARD:
-                element = await this.createCard(props);
+                element = this.createCard(props);
                 break;
             case A2UI_TYPES.MODAL:
-                element = await this.createModal(props);
+                element = this.createModal(props);
                 break;
             case A2UI_TYPES.TOAST:
-                element = await this.createToast(props);
+                element = this.createToast(props);
                 break;
             case A2UI_TYPES.PROGRESS:
-                element = await this.createProgress(props);
+                element = this.createProgress(props);
                 break;
             default:
                 throw new Error(`Unknown A2UI component type: ${type}`);
@@ -116,7 +174,7 @@ export class A2UIRenderer {
         // Render children
         if (children.length > 0) {
             for (const child of children) {
-                const childElement = await this.createElement(child);
+                const childElement = this.createElement(child);
                 element.appendChild(childElement);
             }
         }
@@ -127,7 +185,7 @@ export class A2UIRenderer {
     /**
      * Create custom AfriCode component
      */
-    async createCustomComponent({ tag, ...props }) {
+    createCustomComponent({ tag, ...props }) {
         const element = document.createElement(tag || 'div');
         Object.assign(element, props);
         return element;
@@ -136,7 +194,7 @@ export class A2UIRenderer {
     /**
      * Create form component
      */
-    async createForm({ fields = [], onSubmit }) {
+    createForm({ fields = [], onSubmit }) {
         const form = document.createElement('af-form');
 
         for (const field of fields) {
@@ -157,11 +215,11 @@ export class A2UIRenderer {
     /**
      * Create list component
      */
-    async createList({ items = [] }) {
+    createList({ items = [] }) {
         const list = document.createElement('af-grid');
 
         for (const item of items) {
-            const card = await this.createCard(item);
+            const card = this.createCard(item);
             list.appendChild(card);
         }
 
@@ -171,7 +229,7 @@ export class A2UIRenderer {
     /**
      * Create card component
      */
-    async createCard({ title, content, image }) {
+    createCard({ title, content, image }) {
         const card = document.createElement('af-card');
 
         if (title) {
@@ -199,7 +257,7 @@ export class A2UIRenderer {
     /**
      * Create modal component
      */
-    async createModal({ title, content, actions = [] }) {
+    createModal({ title, content, actions = [] }) {
         const modal = document.createElement('af-modal');
         modal.setAttribute('open', '');
 
@@ -238,7 +296,7 @@ export class A2UIRenderer {
     /**
      * Create toast component
      */
-    async createToast({ message, type = 'info', duration = 3000 }) {
+    createToast({ message, type = 'info', duration = 3000 }) {
         const toast = document.createElement('af-toast');
         toast.setAttribute('type', type);
         toast.textContent = message;
@@ -254,7 +312,7 @@ export class A2UIRenderer {
     /**
      * Create progress component
      */
-    async createProgress({ value = 0, max = 100, label }) {
+    createProgress({ value = 0, max = 100, label }) {
         const progress = document.createElement('af-progress');
         progress.setAttribute('value', value);
         progress.setAttribute('max', max);
@@ -269,7 +327,7 @@ export class A2UIRenderer {
     /**
      * Update existing component
      */
-    async update(id, newProps) {
+    update(id, newProps) {
         const element = this.components.get(id);
         if (element) {
             Object.assign(element, newProps);
@@ -314,7 +372,7 @@ export class A2UIProtocol {
      * Send a message into the A2UI system
      * @param {Object|string} message - A2UI message
      */
-    async sendMessage(message) {
+    sendMessage(message) {
         return this.processMessage(message);
     }
 
@@ -322,28 +380,31 @@ export class A2UIProtocol {
      * Process incoming A2UI message
      * @param {Object|string} message - A2UI message
      */
-    async processMessage(message) {
+    processMessage(message) {
         if (typeof message === 'string') {
             try {
                 message = JSON.parse(message);
             } catch {
                 console.warn('Invalid A2UI message format:', message);
-                return;
+                return null;
             }
         }
 
-        this.messageQueue.push(message);
-        await this.processQueue();
+        if (message?.type === 'render' && this.renderer) {
+            return this.renderer.render(message);
+        }
 
         for (const handler of this.messageHandlers) {
             handler(message);
         }
+
+        return message;
     }
 
     /**
      * Process queued messages
      */
-    async processQueue() {
+    processQueue() {
         if (this.isProcessing || this.messageQueue.length === 0) {
             return;
         }
@@ -354,7 +415,7 @@ export class A2UIProtocol {
             const message = this.messageQueue.shift();
 
             try {
-                await this.renderer.render(message);
+                this.renderer.render(message);
             } catch (error) {
                 console.error('A2UI render error:', error);
             }
@@ -388,16 +449,41 @@ export class A2UIProtocol {
 
             for (const message of messages) {
                 if (message.trim()) {
-                    await this.processMessage(message.trim());
+                    this.processMessage(message.trim());
                 }
             }
         }
 
         // Process any remaining buffer
         if (buffer.trim()) {
-            await this.processMessage(buffer.trim());
+            this.processMessage(buffer.trim());
         }
     }
+
+    createStream() {
+        const subscribers = new Set();
+
+        return {
+            subscribe(callback) {
+                if (typeof callback !== 'function') {
+                    return () => {};
+                }
+
+                subscribers.add(callback);
+                return () => subscribers.delete(callback);
+            },
+            push(message) {
+                for (const callback of subscribers) {
+                    callback(message);
+                }
+            }
+        };
+    }
+
+    validateAgainstSchema(component) {
+        const tag = component?.tag || component?.tagName;
+        return Promise.resolve(Boolean(tag && coreComponentMap[tag]));
+    }
 }
 
 /**
@@ -423,9 +509,11 @@ export function initA2UI(root) {
             update: (id, props) => renderer.update(id, props),
             remove: (id) => renderer.remove(id),
             sendMessage: (message) => protocol.sendMessage(message),
-            onMessage: (callback) => protocol.onMessage(callback)
+            onMessage: (callback) => protocol.onMessage(callback),
+            createStream: () => protocol.createStream(),
+            validateAgainstSchema: (component) => protocol.validateAgainstSchema(component)
         };
     }
 
     return { renderer, protocol };
-}
+}

package/core/actions.js

@@ -0,0 +1,27 @@
+/**
+ * Session-aware action helpers for AfriCode.
+ *
+ * @module core/actions
+ */
+
+import { sessionStore } from './session-store.js';
+
+export const actions = {
+  incrementCounter(sessionId) {
+    const session = sessionStore.get(sessionId);
+    const current = session.counter?.value || 0;
+    const nextValue = current + 1;
+    sessionStore.set(sessionId, 'counter/value', nextValue);
+    return nextValue;
+  },
+
+  resetCounter(sessionId) {
+    sessionStore.set(sessionId, 'counter/value', 0);
+    return 0;
+  },
+
+  getCounter(sessionId) {
+    const session = sessionStore.get(sessionId);
+    return session.counter?.value || 0;
+  }
+};