@urbicon-ui/blocks 6.40.4 → 6.43.0

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

@@ -0,0 +1,264 @@
+/**
+ * Surface routing across message boundaries.
+ *
+ * `A2UIView` is payload-driven: one view renders one envelope array, and its
+ * processor lives with that view. In a chat that means one view per assistant
+ * message — so a surface dies with the message that created it. The A2UI spec
+ * says the opposite: a `surfaceId` is "globally unique for the renderer's
+ * lifetime", `deleteSurface` is the only way to retire one, and
+ * `updateComponents`/`updateDataModel` are patches an agent may send at any
+ * later point. A model that patches a form it built two turns ago is reading
+ * the protocol correctly; the renderer just had nowhere to put the envelope.
+ *
+ * This router closes that gap WITHOUT giving the engine a second state
+ * lifetime. It is a pure bookkeeping layer over the transcript: it remembers
+ * which source (message + a2ui part) owns which surface, and splits each
+ * source's envelopes into the ones that stay put and the ones that belong to an
+ * earlier source's payload. The consumer appends those to that payload
+ * (`[...payload, ...patch]`, keeping element identity) and `A2UIView` consumes
+ * them incrementally — two-way edits the user already made survive, because the
+ * view never rebuilds.
+ *
+ * The transcript stays the single source of truth: every envelope still lives
+ * in exactly one payload, so undo (`revoke`) and replay are plain array work.
+ *
+ * Zero-dependency and Svelte-free — usable from a server-side transcript
+ * reducer, not just from the browser.
+ */
+import { A2UI_ISSUE_CODES } from './a2ui.types.js';
+/** The four operations an envelope may carry, in the order the spec lists them. */
+const OP_KEYS = ['createSurface', 'updateComponents', 'updateDataModel', 'deleteSurface'];
+function isPlainObject(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+/**
+ * Read `(operation, surfaceId)` off an envelope — tolerantly, and without
+ * duplicating the validator. Anything that is not exactly one known operation
+ * with a non-empty string `surfaceId` returns `undefined`: the router then
+ * leaves the envelope where it is and the processor reports the real fault.
+ */
+function readTarget(envelope) {
+    if (!isPlainObject(envelope))
+        return null;
+    const ops = OP_KEYS.filter((key) => envelope[key] !== undefined);
+    if (ops.length !== 1)
+        return null;
+    const op = ops[0];
+    const body = envelope[op];
+    if (!isPlainObject(body))
+        return null;
+    const surfaceId = body.surfaceId;
+    if (typeof surfaceId !== 'string' || surfaceId === '')
+        return null;
+    return { op, surfaceId };
+}
+/**
+ * Tracks surface ownership across sources and routes envelopes to the payload
+ * that owns their surface.
+ *
+ * A "source" is one A2UI payload in the transcript — in a chat app, one `a2ui`
+ * part of one message. The key is the consumer's to choose; it only has to be
+ * stable for that payload's lifetime (e.g. `` `${messageId}#${partIndex}` ``).
+ *
+ * Ownership rules:
+ * - `createSurface` for an unknown id → the calling source owns it.
+ * - `createSurface` for an id owned by ANOTHER source → ownership transfers to
+ *   the caller (last writer wins, so the new surface actually renders) and a
+ *   `SURFACE_RECREATED` issue is raised for the agent.
+ * - Any operation on a surface owned by another source → routed to that owner.
+ * - Any operation on an UNKNOWN surface stays with the caller, so the
+ *   processor's `NO_SURFACE` error surfaces instead of vanishing here.
+ * - `deleteSurface` routes to the owner and then frees the id for re-use.
+ *
+ * @example One assistant turn, wired into the transcript
+ * ```ts
+ * const result = router.route(`${messageId}#0`, part.payload);
+ * part.payload = result.own;
+ * for (const patch of result.patches) appendToPayload(patch.targetKey, patch.envelopes);
+ * for (const surfaceId of result.promoted) markLongLived(surfaceId);
+ * ```
+ */
+export class A2uiSurfaceRouter {
+    /** surfaceId → owning sourceKey. */
+    #owners = new Map();
+    #sources = new Map();
+    /**
+     * surfaceId → the sources that patched it from the outside. Counting the
+     * patchers (rather than flagging a boolean) keeps the promotion signal honest
+     * when a turn is regenerated: take the last outside patch away and the
+     * surface stops being long-lived, so a later patch promotes it afresh.
+     */
+    #patchedBy = new Map();
+    /**
+     * Detach a source: release the surfaces it owns, undo its share of every
+     * promotion, and report the envelopes it had pushed elsewhere.
+     */
+    #detach(sourceKey, source) {
+        for (const [surfaceId, owner] of this.#owners) {
+            if (owner === sourceKey) {
+                this.#owners.delete(surfaceId);
+                this.#patchedBy.delete(surfaceId);
+            }
+        }
+        for (const surfaceId of source.patched) {
+            const patchers = this.#patchedBy.get(surfaceId);
+            if (!patchers)
+                continue;
+            patchers.delete(sourceKey);
+            if (patchers.size === 0)
+                this.#patchedBy.delete(surfaceId);
+        }
+        const patches = [];
+        for (const [targetKey, envelopes] of source.sent) {
+            if (envelopes.length > 0)
+                patches.push({ targetKey, envelopes });
+        }
+        return patches;
+    }
+    /**
+     * Route one source's envelope list.
+     *
+     * Call it as often as you like — on every streamed token, if that is when the
+     * payload grows. Only envelopes appended since the last call are examined; an
+     * unchanged prefix is never re-routed, so patches are never duplicated. If
+     * the prefix DID change (a regenerated turn), the source is rebuilt from
+     * scratch and its previous patches come back in `revoked`.
+     *
+     * @param sourceKey Stable id of the payload being routed.
+     * @param envelopes The payload's accumulated envelopes, in stream order.
+     */
+    route(sourceKey, envelopes) {
+        const previous = this.#sources.get(sourceKey);
+        const isAppend = previous !== undefined &&
+            envelopes.length >= previous.seen.length &&
+            previous.seen.every((envelope, index) => envelope === envelopes[index]);
+        const revoked = [];
+        let source;
+        let startIndex;
+        if (isAppend) {
+            source = previous;
+            startIndex = previous.seen.length;
+        }
+        else {
+            // Rebuild: hand back whatever this source had pushed into other payloads
+            // and drop the surfaces it owned, so re-routing re-establishes them.
+            if (previous)
+                revoked.push(...this.#detach(sourceKey, previous));
+            source = { seen: [], own: [], sent: new Map(), patched: new Set() };
+            this.#sources.set(sourceKey, source);
+            startIndex = 0;
+        }
+        const patches = new Map();
+        const promoted = [];
+        const issues = [];
+        for (let index = startIndex; index < envelopes.length; index++) {
+            const envelope = envelopes[index];
+            source.seen.push(envelope);
+            const target = readTarget(envelope);
+            if (!target) {
+                source.own.push(envelope);
+                continue;
+            }
+            const { op, surfaceId } = target;
+            const owner = this.#owners.get(surfaceId);
+            if (op === 'createSurface') {
+                if (owner !== undefined && owner !== sourceKey) {
+                    issues.push({
+                        severity: 'warning',
+                        code: A2UI_ISSUE_CODES.SURFACE_RECREATED,
+                        surfaceId,
+                        message: `Surface "${surfaceId}" was already created earlier in this conversation. ` +
+                            "A surfaceId must stay unique for the renderer's lifetime — to change an " +
+                            'existing surface send updateComponents/updateDataModel for it instead of ' +
+                            'createSurface, or pick a new id.'
+                    });
+                }
+                // Last writer wins either way: the newest source owns the id, so its
+                // surface renders and later patches follow it. A recreated surface is
+                // a fresh one — its promotion history goes with the old incarnation.
+                this.#owners.set(surfaceId, sourceKey);
+                this.#patchedBy.delete(surfaceId);
+                source.own.push(envelope);
+                continue;
+            }
+            // An unknown surface stays here on purpose — fail loud through the
+            // processor rather than silently dropping the envelope.
+            if (owner === undefined || owner === sourceKey) {
+                source.own.push(envelope);
+                if (op === 'deleteSurface' && owner === sourceKey)
+                    this.#owners.delete(surfaceId);
+                continue;
+            }
+            // The surface lives in an earlier payload — send the patch there.
+            const bucket = patches.get(owner) ?? [];
+            bucket.push(envelope);
+            patches.set(owner, bucket);
+            const sent = source.sent.get(owner) ?? [];
+            sent.push(envelope);
+            source.sent.set(owner, sent);
+            const patchers = this.#patchedBy.get(surfaceId) ?? new Set();
+            const wasLongLived = patchers.size > 0;
+            patchers.add(sourceKey);
+            this.#patchedBy.set(surfaceId, patchers);
+            source.patched.add(surfaceId);
+            if (!wasLongLived)
+                promoted.push(surfaceId);
+            if (op === 'deleteSurface') {
+                this.#owners.delete(surfaceId);
+                this.#patchedBy.delete(surfaceId);
+            }
+        }
+        return {
+            own: source.own.slice(),
+            patches: [...patches].map(([targetKey, list]) => ({ targetKey, envelopes: list })),
+            revoked,
+            promoted,
+            issues
+        };
+    }
+    /**
+     * Forget a source entirely — call it when a message leaves the transcript
+     * (regenerate, delete, branch switch). The returned patches are the envelopes
+     * this source had pushed into other payloads; remove them by reference so no
+     * orphaned patch survives its author.
+     */
+    revoke(sourceKey) {
+        const source = this.#sources.get(sourceKey);
+        if (!source)
+            return [];
+        this.#sources.delete(sourceKey);
+        return this.#detach(sourceKey, source);
+    }
+    /** The source whose payload currently holds `surfaceId`, if any. */
+    ownerOf(surfaceId) {
+        return this.#owners.get(surfaceId);
+    }
+    /**
+     * Whether a surface has been patched from a later source — the promotion
+     * predicate, for clients that need to ask after the fact rather than react to
+     * {@link A2uiRouteResult.promoted}.
+     */
+    isLongLived(surfaceId) {
+        return (this.#patchedBy.get(surfaceId)?.size ?? 0) > 0;
+    }
+    /** Every surface currently owned by a source, in creation order. */
+    surfaceIds() {
+        return [...this.#owners.keys()];
+    }
+    /**
+     * Every source key routed so far, in first-seen order.
+     *
+     * Needed to retire a source whose payload no longer shows it: a message whose
+     * envelopes ALL travelled to earlier surfaces keeps no a2ui part of its own,
+     * so the caller cannot reconstruct its keys by counting parts.
+     */
+    sourceKeys() {
+        return [...this.#sources.keys()];
+    }
+    /** Drop all bookkeeping (new conversation). */
+    reset() {
+        this.#owners.clear();
+        this.#sources.clear();
+        this.#patchedBy.clear();
+    }
+}

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

@@ -0,0 +1,45 @@
+/**
+ * Optional per-surface DATA schema for the A2UI engine — the data-model side of
+ * the registry's prop typing (findings §4.3). A schema declares the shape of the
+ * fields a surface's data model may hold (JSON Pointer → type + optional
+ * enum/format/description). It does two things:
+ * - documents the declared fields in the system prompt (`a2uiDataSchemaSection`),
+ *   so the agent knows which paths exist and what they hold;
+ * - validates `updateDataModel` writes against those declarations
+ *   (`validateSchemaWrite`), turning a type mismatch on a declared pointer into a
+ *   `SCHEMA_TYPE_MISMATCH` error and a write to an undeclared top-level branch
+ *   into a `SCHEMA_UNDECLARED_PATH` warning — both relayed through the same
+ *   `onValidationError` feedback loop the agent already consumes.
+ *
+ * Pure TS, no Svelte. Deliberately MINIMAL (v1): exact-pointer type/enum checks
+ * and a top-level "did you mean to write here?" warning. Deferred: required
+ * fields, nested object schemas, cross-field constraints, and transporting the
+ * schema inside the envelope.
+ */
+import { type A2uiValidationIssue } from './a2ui.types.js';
+/** The JSON primitive/shape a declared field holds. */
+export type A2uiSchemaType = 'string' | 'number' | 'integer' | 'boolean' | 'array' | 'object';
+/** One declared field: its type plus optional enum/format/description for the prompt. */
+export interface A2uiSchemaField {
+    type: A2uiSchemaType;
+    /** Agent-facing description; emitted into the prompt verbatim. */
+    description?: string;
+    /** Allowed literal values (documented + enforced for string/number fields). */
+    enum?: readonly (string | number)[];
+    /** A format hint (e.g. `date`, `time`, `email`) — documented, not enforced in v1. */
+    format?: string;
+}
+/** Surface data schema: absolute JSON Pointer → field declaration. */
+export type A2uiDataSchema = Readonly<Record<string, A2uiSchemaField>>;
+/**
+ * Validate one `updateDataModel` write against the schema. `pointer` is the
+ * write target (`''`/`'/'`/`undefined` = whole model); `value` is the written
+ * value (`undefined` for a delete — never flagged). Returns any schema issues.
+ */
+export declare function validateSchemaWrite(schema: A2uiDataSchema, pointer: string | undefined, value: unknown, surfaceId?: string): A2uiValidationIssue[];
+/**
+ * Render the schema as a prompt section listing every declared field, its type
+ * and any enum/format/description. Appended by the app after `a2uiSystemPrompt`
+ * (like the transport section), NOT baked into the generator.
+ */
+export declare function a2uiDataSchemaSection(schema: A2uiDataSchema): string;

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

@@ -0,0 +1,133 @@
+/**
+ * Optional per-surface DATA schema for the A2UI engine — the data-model side of
+ * the registry's prop typing (findings §4.3). A schema declares the shape of the
+ * fields a surface's data model may hold (JSON Pointer → type + optional
+ * enum/format/description). It does two things:
+ * - documents the declared fields in the system prompt (`a2uiDataSchemaSection`),
+ *   so the agent knows which paths exist and what they hold;
+ * - validates `updateDataModel` writes against those declarations
+ *   (`validateSchemaWrite`), turning a type mismatch on a declared pointer into a
+ *   `SCHEMA_TYPE_MISMATCH` error and a write to an undeclared top-level branch
+ *   into a `SCHEMA_UNDECLARED_PATH` warning — both relayed through the same
+ *   `onValidationError` feedback loop the agent already consumes.
+ *
+ * Pure TS, no Svelte. Deliberately MINIMAL (v1): exact-pointer type/enum checks
+ * and a top-level "did you mean to write here?" warning. Deferred: required
+ * fields, nested object schemas, cross-field constraints, and transporting the
+ * schema inside the envelope.
+ */
+import { A2UI_ISSUE_CODES } from './a2ui.types.js';
+import { getAtPointer } from './a2ui-data.js';
+function typeMatches(type, value) {
+    switch (type) {
+        case 'string':
+            return typeof value === 'string';
+        case 'number':
+            return typeof value === 'number' && Number.isFinite(value);
+        case 'integer':
+            return typeof value === 'number' && Number.isInteger(value);
+        case 'boolean':
+            return typeof value === 'boolean';
+        case 'array':
+            return Array.isArray(value);
+        case 'object':
+            return value !== null && typeof value === 'object' && !Array.isArray(value);
+    }
+}
+/** The first pointer segment (`/booking/date` → `booking`); `''` for the root. */
+function topSegment(pointer) {
+    const trimmed = pointer.startsWith('/') ? pointer.slice(1) : pointer;
+    return trimmed.split('/')[0] ?? '';
+}
+function fieldIssues(field, pointer, value, surfaceId) {
+    if (!typeMatches(field.type, value)) {
+        return [
+            {
+                severity: 'error',
+                code: A2UI_ISSUE_CODES.SCHEMA_TYPE_MISMATCH,
+                surfaceId,
+                path: pointer,
+                message: `Data at "${pointer}" must be a ${field.type} per the surface schema`
+            }
+        ];
+    }
+    if (field.enum &&
+        (typeof value === 'string' || typeof value === 'number') &&
+        !field.enum.includes(value)) {
+        return [
+            {
+                severity: 'error',
+                code: A2UI_ISSUE_CODES.SCHEMA_TYPE_MISMATCH,
+                surfaceId,
+                path: pointer,
+                message: `Data at "${pointer}" must be one of: ${field.enum.join(', ')}`
+            }
+        ];
+    }
+    return [];
+}
+/**
+ * Validate one `updateDataModel` write against the schema. `pointer` is the
+ * write target (`''`/`'/'`/`undefined` = whole model); `value` is the written
+ * value (`undefined` for a delete — never flagged). Returns any schema issues.
+ */
+export function validateSchemaWrite(schema, pointer, value, surfaceId) {
+    if (value === undefined)
+        return []; // a delete never violates a type
+    const whole = pointer === undefined || pointer === '' || pointer === '/';
+    if (whole) {
+        // Whole-model write: check every declared field against the new model.
+        const issues = [];
+        for (const [declaredPointer, field] of Object.entries(schema)) {
+            const at = getAtPointer(value, declaredPointer);
+            if (at !== undefined)
+                issues.push(...fieldIssues(field, declaredPointer, at, surfaceId));
+        }
+        return issues;
+    }
+    // `Object.hasOwn`, not a bare lookup: a pointer like `/toString` or `/__proto__`
+    // would otherwise resolve an inherited Object.prototype member and mis-report a
+    // type mismatch on a field that was never declared.
+    const field = Object.hasOwn(schema, pointer) ? schema[pointer] : undefined;
+    if (field)
+        return fieldIssues(field, pointer, value, surfaceId);
+    // Undeclared pointer: warn only when its whole top-level branch is unknown, so
+    // a write into a declared object (a deeper path we don't model yet) stays quiet.
+    const top = topSegment(pointer);
+    const declared = Object.keys(schema).some((declaredPointer) => topSegment(declaredPointer) === top);
+    if (!declared) {
+        return [
+            {
+                severity: 'warning',
+                code: A2UI_ISSUE_CODES.SCHEMA_UNDECLARED_PATH,
+                surfaceId,
+                path: pointer,
+                message: `Data path "${pointer}" is not declared in the surface schema`
+            }
+        ];
+    }
+    return [];
+}
+/**
+ * Render the schema as a prompt section listing every declared field, its type
+ * and any enum/format/description. Appended by the app after `a2uiSystemPrompt`
+ * (like the transport section), NOT baked into the generator.
+ */
+export function a2uiDataSchemaSection(schema) {
+    const lines = [
+        '## Data schema',
+        '',
+        'The surface data model holds these fields (bind inputs to them with { path }',
+        'and initialize them via updateDataModel). Write only the declared types:'
+    ];
+    for (const [pointer, field] of Object.entries(schema)) {
+        const bits = [field.type];
+        if (field.enum)
+            bits.push(`one of: ${field.enum.join(' | ')}`);
+        if (field.format)
+            bits.push(`format ${field.format}`);
+        const suffix = field.description ? ` — ${field.description}` : '';
+        lines.push(`- ${pointer} (${bits.join('; ')})${suffix}`);
+    }
+    return lines.join('\n');
+}

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

@@ -0,0 +1,120 @@
+/** A streamed text segment. Structurally assignable to blocks' `ChatMessagePart` (`text`). */
+export interface A2uiStreamTextPart {
+    type: 'text';
+    text: string;
+}
+/** A streamed A2UI segment. `payload` is the accumulated envelope array (assignable to `ChatMessagePart` `a2ui`). */
+export interface A2uiStreamUiPart {
+    type: 'a2ui';
+    payload: unknown[];
+}
+export type A2uiStreamPart = A2uiStreamTextPart | A2uiStreamUiPart;
+/** A non-fatal finding from the split (a malformed JSONL line, an unterminated fence). */
+export interface A2uiStreamIssue {
+    code: 'UNPARSEABLE_LINE' | 'UNTERMINATED_FENCE';
+    message: string;
+    /** The offending source line, when applicable. */
+    line?: string;
+}
+/**
+ * The info string that marks a fence as A2UI. Shared by the parser and by
+ * `a2uiFencedTransportSection()` so the prompt can never name a different tag
+ * than the splitter accepts.
+ */
+export declare const A2UI_FENCE_TAG = "a2ui";
+export declare class A2uiStreamSplitter {
+    /** Committed parts (immutable; replaced wholesale on every mutation). */
+    private committed;
+    private mode;
+    /**
+     * When in text mode inside a *regular* (non-a2ui) markdown code fence, the
+     * marker that opened it. A `` ```a2ui `` line inside such a block is literal
+     * code, NOT a surface — this is what stops a quoted example from executing.
+     */
+    private codeFence;
+    /** Buffered trailing line that has not yet seen its newline. */
+    private pending;
+    private rawText;
+    private readonly issueList;
+    /**
+     * Raw lines of an in-progress multi-line envelope (a pretty-printed object
+     * spanning several fence lines), plus the depth-scanner state that tracks
+     * whether the object has closed. Empty/zeroed while envelopes arrive as
+     * proper single-line JSONL.
+     */
+    private objLines;
+    private objDepth;
+    private objInString;
+    private objEscape;
+    /** Feed the next token / chunk of model output. */
+    push(chunk: string): void;
+    /** Signal end of stream: flush the trailing partial line and settle state. */
+    end(): void;
+    private asText;
+    private resetObjBuffer;
+    /**
+     * Advance the depth scanner across one line: brace/bracket depth outside of
+     * strings, with `\"`-escape handling inside them. Returns `false` when the
+     * buffer can never become valid JSON — depth underflow, or a string left
+     * open at end-of-line (raw newlines are illegal inside JSON strings).
+     */
+    private scanDepth;
+    /**
+     * Abandon the current a2ui fence: drop an empty surface, record an issue and
+     * re-emit the buffered lines (plus the offending one, if any) as text inside
+     * a synthetic ``` code block. `codeFence` is armed so the fence's real
+     * closing ``` closes that block instead of opening a stray one downstream.
+     */
+    private fenceFallback;
+    private processLine;
+    /**
+     * The current parts, including the buffered trailing text tail for a
+     * responsive stream. A partial line that might still become a fence marker is
+     * held back (never flashed). a2ui parts are carried by reference so A2UIView
+     * consumes them incrementally.
+     */
+    snapshot(): A2uiStreamPart[];
+    /** The raw model output fed so far (fences included) — the faithful wire form. */
+    get raw(): string;
+    /** Accumulated non-fatal issues (malformed JSONL, unterminated fence). */
+    get issues(): A2uiStreamIssue[];
+}
+/** Options for {@link a2uiFencedTransportSection}. */
+export interface A2uiTransportSectionOptions {
+    /**
+     * Prefix your client puts on a user turn that reports an action, followed by
+     * the JSON `A2uiActionEvent`. Set to `false` if actions reach the agent some
+     * other way (a tool result, a structured field) — the round-channel paragraph
+     * is then omitted. @default '[ui-action]'
+     */
+    actionPrefix?: string | false;
+    /**
+     * Prefix for a turn that reports validation issues as JSON, so the agent can
+     * repair the surface. `false` omits it. @default '[ui-error]'
+     */
+    errorPrefix?: string | false;
+}
+/**
+ * The transport half of the fenced-JSONL contract: the prompt section that makes
+ * an agent emit exactly what {@link A2uiStreamSplitter} parses.
+ *
+ * `a2uiSystemPrompt()` deliberately says nothing about transport, because how
+ * envelopes travel is the app's business. This is the transport for apps that
+ * take the model's ordinary text stream and let it open a ` ```a2ui ` fence —
+ * the setup the splitter exists for. Append it after `a2uiSystemPrompt()` (and
+ * after `a2uiDataSchemaSection()`, if you use one).
+ *
+ * Anything domain-specific — which tools to call, what never to invent — stays
+ * yours to append; this covers only the wire format and the return path.
+ *
+ * @example
+ * ```ts
+ * const system = [
+ *   a2uiSystemPrompt({ catalog: urbiconA2uiCatalogSpec }),
+ *   a2uiDataSchemaSection(MY_SCHEMA),
+ *   a2uiFencedTransportSection(),
+ *   MY_DOMAIN_RULES
+ * ].join('\n\n');
+ * ```
+ */
+export declare function a2uiFencedTransportSection(options?: A2uiTransportSectionOptions): string;