@urbicon-ui/blocks 6.38.0 → 6.39.0

package/dist/components/Chat/A2UIView/a2ui-render.js

@@ -0,0 +1,140 @@
+/**
+ * Render-tree assembly for the A2UI renderer — the bridge between the pure-TS
+ * processor (`a2ui-validate.ts`, plain Maps) and the recursive Svelte dispatcher
+ * (`A2UINode.svelte`). Pure TS, no Svelte, so `A2UINode` and `A2UIView` share
+ * one typed contract (the house pattern of `md-context.ts`, deliberately not a
+ * Svelte context — the tree is private and explicit prop flow keeps it
+ * inspectable).
+ *
+ * `buildRenderTree` walks the component graph from `root` into a fully-expanded,
+ * BOUNDED node tree: child/children references resolved, list templates expanded
+ * over the data model, dangling references marked, and the depth/node/cycle
+ * limits enforced in ONE place so the Svelte layer can never recurse without
+ * bound regardless of payload. Graph-level ISSUES (the reportable faults) are
+ * still produced by `collectGraphIssues` in `a2ui-validate.ts`; this walk only
+ * shapes what renders.
+ */
+import { getAtPointer } from './a2ui-data.js';
+/** Default traversal bounds — mirror `collectGraphIssues` so the tree and the issue list agree. */
+export const A2UI_MAX_DEPTH = 32;
+export const A2UI_MAX_NODES = 512;
+/** Clamp a finite number into `[min, max]`; NaN/∞ collapse to `min`. */
+function clampWeight(value, min, max) {
+    if (!Number.isFinite(value))
+        return min;
+    return Math.min(max, Math.max(min, value));
+}
+/**
+ * Resolve a `{ path }` data binding to the ABSOLUTE JSON Pointer it addresses,
+ * honouring the template scope for relative paths. Returns `undefined` for
+ * literals and function-call bindings (nothing to write back into).
+ */
+export function bindingPointer(value, scopePrefix) {
+    if (value === null || typeof value !== 'object' || Array.isArray(value))
+        return undefined;
+    const object = value;
+    if (typeof object.call === 'string')
+        return undefined;
+    if (typeof object.path !== 'string')
+        return undefined;
+    const path = object.path;
+    return path.startsWith('/') ? path : `${scopePrefix ?? ''}/${path}`;
+}
+/** Coerce an unknown model value to a string array of stable option values (for ChoicePicker). */
+export function toStringArray(value) {
+    if (!Array.isArray(value))
+        return [];
+    return value.filter((item) => typeof item === 'string');
+}
+/** Coerce a scalar model value to the string an `<input>` displays. */
+export function toInputString(value) {
+    if (value === null || value === undefined)
+        return '';
+    if (typeof value === 'string')
+        return value;
+    if (typeof value === 'number' && Number.isFinite(value))
+        return String(value);
+    if (typeof value === 'boolean')
+        return String(value);
+    return '';
+}
+function childRefs(instance, scopePrefix, state) {
+    const out = [];
+    const single = instance.props.get('child');
+    if (typeof single === 'string')
+        out.push({ id: single, scope: scopePrefix });
+    const children = instance.props.get('children');
+    if (Array.isArray(children)) {
+        for (const childId of children) {
+            if (typeof childId === 'string')
+                out.push({ id: childId, scope: scopePrefix });
+        }
+    }
+    else if (children !== null && typeof children === 'object') {
+        const template = children;
+        if (typeof template.componentId === 'string' && typeof template.path === 'string') {
+            const absPath = template.path.startsWith('/')
+                ? template.path
+                : `${scopePrefix ?? ''}/${template.path}`;
+            const list = getAtPointer(state.dataModel, absPath);
+            if (Array.isArray(list)) {
+                for (let i = 0; i < list.length; i++) {
+                    out.push({ id: template.componentId, scope: `${absPath}/${i}` });
+                    if (out.length > state.maxNodes)
+                        break; // bound the expansion itself
+                }
+            }
+            // non-array / undefined → render nothing (issue reported by collectGraphIssues)
+        }
+    }
+    return out;
+}
+function buildNode(id, scopePrefix, key, parentIsFlex, ancestors, depth, state) {
+    if (state.count >= state.maxNodes || depth > state.maxDepth)
+        return null;
+    state.count++;
+    const instance = state.components.get(id);
+    if (!instance) {
+        return { key, id, instance: null, scopePrefix, children: [] };
+    }
+    const node = { key, id, instance, scopePrefix, children: [] };
+    if (parentIsFlex) {
+        const weight = instance.props.get('weight');
+        if (typeof weight === 'number' && Number.isFinite(weight)) {
+            node.weight = clampWeight(weight, 0, 100);
+        }
+    }
+    const isFlex = instance.component === 'Row' || instance.component === 'Column';
+    const nextAncestors = new Set(ancestors);
+    nextAncestors.add(id);
+    const refs = childRefs(instance, scopePrefix, state);
+    for (let i = 0; i < refs.length; i++) {
+        if (state.count >= state.maxNodes)
+            break;
+        const ref = refs[i];
+        if (nextAncestors.has(ref.id))
+            continue; // cycle: truncate (issue reported elsewhere)
+        const childKey = `${ref.id}@${ref.scope ?? ''}#${i}`;
+        const child = buildNode(ref.id, ref.scope, childKey, isFlex, nextAncestors, depth + 1, state);
+        if (child)
+            node.children.push(child);
+    }
+    return node;
+}
+/**
+ * Assemble the bounded render tree for a surface, starting at `root`. Returns
+ * `null` when no `root` component exists yet (the caller renders a placeholder
+ * while streaming, or a fault chip once settled).
+ */
+export function buildRenderTree(surface, options) {
+    if (!surface.components.has('root'))
+        return null;
+    const state = {
+        components: surface.components,
+        dataModel: surface.dataModel,
+        maxDepth: options?.maxDepth ?? A2UI_MAX_DEPTH,
+        maxNodes: options?.maxNodes ?? A2UI_MAX_NODES,
+        count: 0
+    };
+    return buildNode('root', undefined, 'root', false, new Set(), 0, state);
+}

package/dist/components/Chat/A2UIView/a2ui-validate.d.ts

@@ -0,0 +1,75 @@
+/**
+ * The A2UI processor: incremental, whitelist-only, fail-loud validation that
+ * turns a stream of Server→Client envelopes into per-surface component maps and
+ * data models. Pure TS, no Svelte — deliberately NOT reactive (the house
+ * pattern of the streaming-markdown engine: plain Maps mutated in place; the
+ * Svelte layer bumps a version counter to re-derive the render tree).
+ *
+ * Security posture (untrusted-payload path):
+ * - Whitelist-only: only registry-declared props reach the render layer, so
+ *   handler injection (`onclick`, …) and prop smuggling are structurally
+ *   impossible — there is no payload spread.
+ * - `__proto__`/`constructor`/`prototype` are rejected as component ids, prop
+ *   keys, pointer segments and action-context keys.
+ * - Never merges or spreads payload objects; everything flows through `Map`s.
+ * - `collectGraphIssues` bounds traversal (depth 32, nodes 512) to cap DoS.
+ *
+ * Issue routing: envelope-level faults (bad version, unknown envelope type,
+ * op-before-createSurface) land in `globalIssues`; everything scoped to a known
+ * surface lands in that surface's `issues`. Graph-level faults (cycle, depth,
+ * node count, dangling refs) are computed on demand by `collectGraphIssues`,
+ * because "dangling" is a warning mid-stream and an error once settled.
+ */
+import { type A2uiValidationIssue } from './a2ui.types.js';
+export interface A2uiComponentInstance {
+    id: string;
+    component: string;
+    /** Only registry-declared props; the raw payload values (dynamics resolved at render). */
+    props: ReadonlyMap<string, unknown>;
+    /** Index of the envelope that last defined this component. */
+    sourceIndex: number;
+}
+export interface A2uiSurfaceState {
+    surfaceId: string;
+    components: Map<string, A2uiComponentInstance>;
+    /** Root of the surface data model (mutated in place by two-way edits). */
+    dataModel: unknown;
+    issues: A2uiValidationIssue[];
+}
+export interface A2uiProcessor {
+    surfaces: Map<string, A2uiSurfaceState>;
+    globalIssues: A2uiValidationIssue[];
+    /** Validate + apply one envelope. `index` positions it as `/messages/<index>` in issue paths. */
+    apply(envelope: unknown, index: number): void;
+}
+export declare function createA2uiProcessor(): A2uiProcessor;
+/**
+ * Normalize a render payload into an envelope list. Accepts an envelope array,
+ * a single envelope, or the golden-file `{ messages: [...] }` wrapper. Returns
+ * an `issue` (and no envelopes) only for wholly unusable input.
+ */
+export declare function normalizeA2uiPayload(payload: unknown): {
+    envelopes: unknown[];
+    issue?: A2uiValidationIssue;
+};
+export interface GraphIssueOptions {
+    /** When true, dangling refs are warnings (still streaming); when false, errors. @default false */
+    streaming?: boolean;
+    /** @default 32 */
+    maxDepth?: number;
+    /** @default 512 */
+    maxNodes?: number;
+}
+/**
+ * Walk the component graph from `root` and collect structural faults that only
+ * exist once components are assembled: cycles, excessive depth/nodes, dangling
+ * child references, non-array template paths, and mis-placed `weight`.
+ *
+ * NOTE — contract extension. The design's published `a2ui-validate.ts` surface
+ * is `createA2uiProcessor` + `normalizeA2uiPayload`. This function is an
+ * additive export (no existing signature changed): the renderer (WP-B) needs
+ * render-time graph faults whose severity depends on the `streaming` flag, and
+ * the test suite exercises them here. Traversal is bounded by `maxNodes` so a
+ * template over a huge array cannot DoS the walk itself.
+ */
+export declare function collectGraphIssues(surface: A2uiSurfaceState, options?: GraphIssueOptions): A2uiValidationIssue[];