@ayni.org/ayni-ui-core 0.3.1 → 0.3.3

package/README.md

@@ -16,7 +16,7 @@ The browser draws with CSS and the Ayni app with React Native styles. What the t
 
 | Surface | Design values and colour roles | What it shows |
 | --- | --- | --- |
-| A conversation | `CONVERSATION_DESIGN`, `CONVERSATION_COLORS` | `replyQuoteOf`, `reactionPillOf`, `plainText` |
+| A conversation | `CONVERSATION_DESIGN`, `CONVERSATION_COLORS` | `replyQuoteOf`, `reactionPillOf`, `plainText`, `progressOf` (the agent is working) |
 | The home page (rail and column) | `HOME_DESIGN`, `HOME_COLORS` | `TRUST_MARK`, `CONTROLLER_KIND_ICON`, `formatTime` |
 | The Proof of Trust | `PROOF_OF_TRUST_DESIGN`, `PROOF_OF_TRUST_COLORS` | `verdictOf`, `identityStepOf`, `accreditationLine`, `otherCredentialLine`, `claimRows`, and its English wording (`PROOF_OF_TRUST_COPY`) |
 
@@ -24,5 +24,20 @@ The browser's stylesheet is the reference: tests in this repository compare it,
 with these values, so a change made on one side only fails. The app builds its styles from the same values. A change
 of look or wording on one of these surfaces starts here.
 
+## One conversation, every device
+
+A conversation shows the same transcript on every device of a person (AG-UI profile PROF-STREAM-005,
+PROF-HIST-007). The agent sends a session what the person's other devices add; the reducer places a text message
+by its role and its id, so a message typed elsewhere lands on the person's side. For what a client missed while it
+was away:
+
+| Function | What it does |
+| --- | --- |
+| `readCatchUp(transcript, read)` | Reads the newest pages of history, going back until one reaches what the transcript holds, history ends, or four pages were read; then merges them. |
+| `catchUp(transcript, pages)` | The merge itself. The transcript keeps its own paging position; when more was missed than was read, it starts over from the pages, so it never shows a hole. |
+| `reachesTranscript(transcript, page)` | Whether a page of history holds a message the transcript already has. |
+
+A client calls `readCatchUp` every time a session's stream attaches.
+
 Published to npm from this repository by the `npm-publish` workflow whenever `package.json` carries a version that is
 not on npm yet.

package/dist/conversationDesign.d.ts

@@ -75,6 +75,33 @@ export declare const CONVERSATION_DESIGN: {
         readonly bottom: 12;
         readonly awayBeyond: 320;
     };
+    /**
+     * The agent is working (UI-CONV-016): a bubble on the agent's side with three bouncing dots, then the steps of
+     * the run in progress or "Thinking…".
+     */
+    readonly progress: {
+        readonly fontSize: 13;
+        readonly gap: 10;
+        readonly paddingY: 10;
+        readonly paddingX: 14;
+        readonly radius: 16;
+        readonly tailRadius: 4;
+    };
+    /**
+     * The three dots: each rises and brightens, one after the other. Over one period a dot is at rest until it
+     * starts, at its peak at `peakAt` of the period and back at rest from `restFrom`; the second and third dots
+     * start `delayMs` and twice `delayMs` later.
+     */
+    readonly dots: {
+        readonly size: 7;
+        readonly gap: 4;
+        readonly periodMs: 1200;
+        readonly delayMs: 150;
+        readonly lift: 4;
+        readonly restOpacity: 0.35;
+        readonly peakAt: 0.4;
+        readonly restFrom: 0.8;
+    };
 };
 export type ConversationDesign = typeof CONVERSATION_DESIGN;
 /** The colour roles both palettes define, in the browser as custom properties and in the app as theme colours. */
@@ -113,6 +140,13 @@ export declare const CONVERSATION_COLORS: {
         readonly border: "border";
         readonly icon: "text";
     };
+    readonly progress: {
+        readonly background: "surface";
+        readonly text: "muted";
+    };
+    readonly dots: {
+        readonly color: "accent";
+    };
 };
 /** The side a message sits on, and the corner its bubble tightens. */
 export declare function bubbleSide(role: 'user' | 'assistant' | 'system'): 'mine' | 'theirs' | 'system';
@@ -165,3 +199,26 @@ export declare function reactionPillOf(reactions: readonly {
     }[];
     mine?: string;
 } | null;
+/** The wording of a conversation the two renderers share, in English (the browser's `conversation.*` keys). */
+export declare const CONVERSATION_COPY: {
+    readonly thinking: "Thinking…";
+};
+/**
+ * What the transcript shows while the agent works (UI-CONV-016): the steps of the run in progress when it reports
+ * some; else "thinking", from the start of a run until its reply begins to stream; nothing when no run is in
+ * progress or the reply is already arriving. A run started from another device of the person counts the same.
+ */
+export declare function progressOf(transcript: {
+    run: {
+        steps: readonly string[];
+    } | null;
+    messages: readonly {
+        role: string;
+        streaming?: boolean;
+    }[];
+} | null | undefined): {
+    kind: 'steps';
+    steps: readonly string[];
+} | {
+    kind: 'thinking';
+} | null;

package/dist/conversationDesign.js

@@ -59,6 +59,17 @@ export const CONVERSATION_DESIGN = {
     },
     /** the button that returns to the latest message */
     latestButton: { size: 36, right: 20, bottom: 12, awayBeyond: 320 },
+    /**
+     * The agent is working (UI-CONV-016): a bubble on the agent's side with three bouncing dots, then the steps of
+     * the run in progress or "Thinking…".
+     */
+    progress: { fontSize: 13, gap: 10, paddingY: 10, paddingX: 14, radius: 16, tailRadius: 4 },
+    /**
+     * The three dots: each rises and brightens, one after the other. Over one period a dot is at rest until it
+     * starts, at its peak at `peakAt` of the period and back at rest from `restFrom`; the second and third dots
+     * start `delayMs` and twice `delayMs` later.
+     */
+    dots: { size: 7, gap: 4, periodMs: 1200, delayMs: 150, lift: 4, restOpacity: 0.35, peakAt: 0.4, restFrom: 0.8 },
 };
 /** Which colour role paints what in a conversation. */
 export const CONVERSATION_COLORS = {
@@ -70,6 +81,8 @@ export const CONVERSATION_COLORS = {
     quote: { border: 'accent', who: 'accent' },
     reactionPill: { background: 'bg', border: 'border', text: 'text', mineBorder: 'accent' },
     latestButton: { background: 'bg', border: 'border', icon: 'text' },
+    progress: { background: 'surface', text: 'muted' },
+    dots: { color: 'accent' },
 };
 /** The side a message sits on, and the corner its bubble tightens. */
 export function bubbleSide(role) {
@@ -123,3 +136,21 @@ export function reactionPillOf(reactions, me) {
         mine: own?.emoji,
     };
 }
+/** The wording of a conversation the two renderers share, in English (the browser's `conversation.*` keys). */
+export const CONVERSATION_COPY = {
+    thinking: 'Thinking…',
+};
+/**
+ * What the transcript shows while the agent works (UI-CONV-016): the steps of the run in progress when it reports
+ * some; else "thinking", from the start of a run until its reply begins to stream; nothing when no run is in
+ * progress or the reply is already arriving. A run started from another device of the person counts the same.
+ */
+export function progressOf(transcript) {
+    const run = transcript?.run;
+    if (!run)
+        return null;
+    if (run.steps.length)
+        return { kind: 'steps', steps: run.steps };
+    const replying = transcript.messages.some((m) => m.role !== 'activity' && m.streaming);
+    return replying ? null : { kind: 'thinking' };
+}

package/dist/reducer.d.ts

@@ -4,9 +4,14 @@ export interface Reduction {
     transcript: Transcript;
     session: SessionRecord;
     /** signals the shell reacts to (title, badge, sound) */
-    signals: ('message' | 'bound' | 'closed' | 'token' | 'approval' | 'identified')[];
+    signals: ('message' | 'bound' | 'closed' | 'token' | 'approval' | 'identified' | 'conversations')[];
 }
 export declare function emptyTranscript(sessionId: string): Transcript;
+/**
+ * The agent's signal that the person's list of conversations changed (PROF-CONV-007): a title, an archive, a
+ * closure, made from any device. Named here until the profile package that lists it is the one every client has.
+ */
+export declare const CONVERSATION_CHANGED = "ayni.conversation.changed";
 /** The five closed states of a flow (flow profile §5.2). */
 export declare function isClosedFlow(state: unknown): boolean;
 export declare function reduce(transcript: Transcript, session: SessionRecord, event: AgUiEvent, fromRun: boolean, isOnScreen: boolean): Reduction;
@@ -19,3 +24,23 @@ export declare function reactionsOf(page: Record<string, unknown>[]): Record<str
 }[]>;
 /** Merges a history page (newest last) into the transcript without duplicates (UI-CONV-012, UI-PRIV-003). */
 export declare function mergeHistory(transcript: Transcript, page: Record<string, unknown>[], nextBefore: string | null): Transcript;
+/** A page of history as the agent returns it (PROF-HIST-001): newest last, with where the page before it starts. */
+export interface HistoryPage {
+    messages: Record<string, unknown>[];
+    nextBefore: string | null;
+}
+/** Whether a page of history reaches what the transcript holds: one of its messages is already there. */
+export declare function reachesTranscript(transcript: Transcript, page: Record<string, unknown>[]): boolean;
+/**
+ * What a device missed while it was away, merged into the transcript it holds (UI-CONV-022, PROF-HIST-007): a
+ * conversation continued from another device, or events its stream could not replay. `pages` are the newest pages
+ * of history, newest first, read until one reached the transcript or history ended. The transcript keeps its own
+ * paging position when a page reached it. When none did, more was missed than was read: the transcript starts
+ * over from the pages, so it never shows a hole between what it held and what it read.
+ */
+export declare function catchUp(transcript: Transcript, pages: readonly HistoryPage[]): Transcript;
+/**
+ * Reads what `catchUp` needs: the newest pages of history, going back until one reaches the transcript, history
+ * ends, or `maxPages` were read; then merges them.
+ */
+export declare function readCatchUp(transcript: Transcript, read: (before?: string) => Promise<HistoryPage>, maxPages?: number): Promise<Transcript>;

package/dist/reducer.js

@@ -7,6 +7,11 @@ export function emptyTranscript(sessionId) {
     return { sessionId, messages: [], oldestLoadedId: null, complete: false, run: null, routed: {}, reactions: {} };
 }
 const now = () => new Date().toISOString();
+/**
+ * The agent's signal that the person's list of conversations changed (PROF-CONV-007): a title, an archive, a
+ * closure, made from any device. Named here until the profile package that lists it is the one every client has.
+ */
+export const CONVERSATION_CHANGED = 'ayni.conversation.changed';
 /** The five closed states of a flow (flow profile §5.2). */
 export function isClosedFlow(state) {
     return (state === 'completed' || state === 'declined' || state === 'cancelled' || state === 'failed' || state === 'expired');
@@ -75,9 +80,13 @@ export function reduce(transcript, session, event, fromRun, isOnScreen) {
             break;
         case 'TEXT_MESSAGE_START': {
             const role = event.role === 'user' ? 'user' : event.role === 'system' ? 'system' : 'assistant';
+            const id = String(event.messageId);
+            // a message already held comes again when a stream replays it after a reconnect: it keeps its time, so
+            // it stays where it is in the transcript
+            const held = t.messages.find((m) => m.id === id);
             t = {
                 ...t,
-                messages: upsertMessage(t.messages, { id: String(event.messageId), role, content: '', at, streaming: true }),
+                messages: upsertMessage(t.messages, { id, role, content: '', at: held?.at ?? at, streaming: true }),
             };
             break;
         }
@@ -187,6 +196,11 @@ export function reduce(transcript, session, event, fromRun, isOnScreen) {
                     }
                     break;
                 }
+                case CONVERSATION_CHANGED:
+                    // a conversation of the person was renamed, archived or closed, here or on another device: the client
+                    // reads the agent's list again (PROF-CONV-007)
+                    signals.push('conversations');
+                    break;
                 case CUSTOM_EVENT.sessionBound:
                     s = {
                         ...s,
@@ -308,3 +322,50 @@ export function mergeHistory(transcript, page, nextBefore) {
         complete: nextBefore === null || page.length === 0,
     };
 }
+/** Whether a page of history reaches what the transcript holds: one of its messages is already there. */
+export function reachesTranscript(transcript, page) {
+    const known = new Set(transcript.messages.map((m) => m.id));
+    return page.some((m) => {
+        const external = m.metadata?.externalId;
+        return known.has(String(m.id)) || (!!external && known.has(external));
+    });
+}
+/**
+ * What a device missed while it was away, merged into the transcript it holds (UI-CONV-022, PROF-HIST-007): a
+ * conversation continued from another device, or events its stream could not replay. `pages` are the newest pages
+ * of history, newest first, read until one reached the transcript or history ended. The transcript keeps its own
+ * paging position when a page reached it. When none did, more was missed than was read: the transcript starts
+ * over from the pages, so it never shows a hole between what it held and what it read.
+ */
+export function catchUp(transcript, pages) {
+    if (!pages.length)
+        return transcript;
+    const held = transcript.messages.length > 0;
+    const reached = !held || pages.some((p) => p.nextBefore === null || reachesTranscript(transcript, p.messages));
+    let merged = reached ? transcript : { ...transcript, messages: [], reactions: {} };
+    for (const page of pages)
+        merged = mergeHistory(merged, page.messages, page.nextBefore);
+    return held && reached
+        ? { ...merged, oldestLoadedId: transcript.oldestLoadedId, complete: transcript.complete }
+        : merged;
+}
+/**
+ * Reads what `catchUp` needs: the newest pages of history, going back until one reaches the transcript, history
+ * ends, or `maxPages` were read; then merges them.
+ */
+export async function readCatchUp(transcript, read, maxPages = 4) {
+    const pages = [];
+    let before;
+    for (let i = 0; i < maxPages; i++) {
+        const page = await read(before);
+        pages.push(page);
+        const done = page.nextBefore === null ||
+            page.messages.length === 0 ||
+            transcript.messages.length === 0 ||
+            reachesTranscript(transcript, page.messages);
+        if (done)
+            break;
+        before = page.nextBefore ?? undefined;
+    }
+    return catchUp(transcript, pages);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ayni.org/ayni-ui-core",
-  "version": "0.3.1",
+  "version": "0.3.3",
   "description": "Framework-independent core of the Ayni UI (UI-SHELL-004): agents and controllers, trust resolution, sessions and binding, the conversation reducer, the local store and sync; shared by the browser UI and the Ayni app",
   "type": "module",
   "main": "./dist/index.js",