@zeyos/zx 5.5.0 → 5.6.0

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 (48) hide show
  1. package/CHANGELOG.md +56 -0
  2. package/dist/types/components/agent-thread/agent-thread.d.ts +583 -0
  3. package/dist/types/components/approval-card/approval-card.d.ts +596 -0
  4. package/dist/types/components/avatar/avatar.d.ts +91 -4
  5. package/dist/types/components/block-view/block-view.d.ts +205 -0
  6. package/dist/types/components/composer/composer.d.ts +736 -0
  7. package/dist/types/components/run-status/run-status.d.ts +393 -0
  8. package/dist/types/components/run-trace/run-trace.d.ts +624 -0
  9. package/dist/types/components/source-list/source-list.d.ts +177 -0
  10. package/dist/types/core/messages.d.ts +135 -0
  11. package/dist/types/index.d.ts +8 -0
  12. package/dist/types/internal/agent-model.d.ts +587 -0
  13. package/dist/types/internal/highlight.d.ts +24 -0
  14. package/dist/types/internal/presence-loop.d.ts +148 -0
  15. package/dist/zx-zeyos.esm.js +4648 -4513
  16. package/dist/zx-zeyos.esm.min.js +2 -2
  17. package/dist/zx.css +1927 -1
  18. package/dist/zx.esm.js +15769 -9194
  19. package/dist/zx.esm.min.js +27 -8
  20. package/dist/zx.global.js +15769 -9194
  21. package/dist/zx.global.min.js +27 -8
  22. package/dist/zx.min.css +1 -1
  23. package/docs/api.json +1166 -5
  24. package/docs/llms.md +455 -2
  25. package/docs/llms.txt +10 -1
  26. package/package.json +1 -1
  27. package/src/components/agent-thread/agent-thread.css +417 -0
  28. package/src/components/agent-thread/agent-thread.js +1365 -0
  29. package/src/components/approval-card/approval-card.css +289 -0
  30. package/src/components/approval-card/approval-card.js +1377 -0
  31. package/src/components/avatar/avatar.css +56 -1
  32. package/src/components/avatar/avatar.js +148 -26
  33. package/src/components/block-view/block-view.css +300 -0
  34. package/src/components/block-view/block-view.js +523 -0
  35. package/src/components/composer/composer.css +403 -0
  36. package/src/components/composer/composer.js +1441 -0
  37. package/src/components/run-status/run-status.css +208 -0
  38. package/src/components/run-status/run-status.js +782 -0
  39. package/src/components/run-trace/run-trace.css +443 -0
  40. package/src/components/run-trace/run-trace.js +1209 -0
  41. package/src/components/source-list/source-list.css +208 -0
  42. package/src/components/source-list/source-list.js +355 -0
  43. package/src/core/messages.js +143 -0
  44. package/src/index.js +8 -0
  45. package/src/internal/agent-model.js +488 -0
  46. package/src/internal/highlight.js +104 -0
  47. package/src/internal/presence-loop.js +343 -0
  48. package/styles/zx.css +7 -0
@@ -1,5 +1,6 @@
1
1
  import { Component } from '../../core/component.js';
2
2
  export type AvatarTone = 'blue' | 'teal' | 'green' | 'amber' | 'orange' | 'red' | 'pink' | 'violet' | 'slate';
3
+ export type AgentActivity = import('../../internal/agent-model.js').AgentActivity;
3
4
  export type AvatarOptions = {
4
5
  /**
5
6
  * Image URL.
@@ -33,18 +34,54 @@ export type AvatarOptions = {
33
34
  */
34
35
  tone?: AvatarTone | null;
35
36
  /**
36
- * Optional presence state.
37
+ * Optional presence state of a
38
+ * person. An agent's `activity` takes its place: when both are given, only the activity is drawn
39
+ * and named.
37
40
  */
38
41
  status?: 'online' | 'away' | 'busy' | 'offline' | null;
39
42
  /**
40
43
  * Text alternative for the presence state.
41
44
  */
42
45
  statusLabel?: string | null;
46
+ /**
47
+ * What an agent is doing: `'idle'`, `'thinking'`,
48
+ * `'working'`, `'needs-you'`, `'blocked'` or `'offline'`. Drawn as a dot whose shape and tone
49
+ * differ per activity (a square for blocked, a hollow ring for idle, a dashed ring for offline);
50
+ * its word joins the accessible name and the dot's tooltip. Wins over `status`.
51
+ */
52
+ activity?: AgentActivity | null;
53
+ /**
54
+ * The activity's word, when the default ("Working",
55
+ * "Needs you", …) is not the one to show.
56
+ */
57
+ activityLabel?: string | null;
58
+ /**
59
+ * Moves the avatar with its activity — idle breathes, thinking
60
+ * sways, working bobs, needs-you leans and blinks — in the one animation loop every animated
61
+ * avatar on the page shares. Motion is never the only signal, stops off screen and while the page
62
+ * is hidden, and returns the avatar to rest under reduced motion (the system's, or a
63
+ * `data-zx-motion="reduced"` region). While it is on, the root's `transform` belongs to the loop.
64
+ */
65
+ animate?: boolean;
66
+ /**
67
+ * Where in its activity's cycle the avatar moves, as a
68
+ * fraction from 0 up to 1 (whole turns wrap): two avatars of the same agent on one screen — a
69
+ * roster and an inspector — at different phases never move in step, and 0.5 puts them half a cycle
70
+ * apart. `null` derives the phase from the name (or the initials), so the same agent always moves
71
+ * the same way.
72
+ */
73
+ phase?: number | null;
74
+ /**
75
+ * Localized
76
+ * messages: the activity words, `agent.activity.<activity>`.
77
+ */
78
+ msg?: Record<string, string> | Record<string, Record<string, string>>;
43
79
  };
44
80
  /**
45
81
  * A categorical tone from the design system's tone palette (`--zx-color-tone-*`).
46
82
  * @typedef {'blue'|'teal'|'green'|'amber'|'orange'|'red'|'pink'|'violet'|'slate'} AvatarTone
47
83
  */
84
+ /** @typedef {import('../../internal/agent-model.js').AgentActivity} AgentActivity */
48
85
  /**
49
86
  * @typedef {Object} AvatarOptions
50
87
  * @property {string|null} [src=null] Image URL.
@@ -57,8 +94,28 @@ export type AvatarOptions = {
57
94
  * @property {AvatarTone|null} [tone=null] Fallback colour from the tone palette. `null` derives a
58
95
  * stable tone from the name (or the initials when there is no name), so the same person gets the
59
96
  * same colour on every screen; see {@link avatarTone}.
60
- * @property {'online'|'away'|'busy'|'offline'|null} [status=null] Optional presence state.
97
+ * @property {'online'|'away'|'busy'|'offline'|null} [status=null] Optional presence state of a
98
+ * person. An agent's `activity` takes its place: when both are given, only the activity is drawn
99
+ * and named.
61
100
  * @property {string|null} [statusLabel=null] Text alternative for the presence state.
101
+ * @property {AgentActivity|null} [activity=null] What an agent is doing: `'idle'`, `'thinking'`,
102
+ * `'working'`, `'needs-you'`, `'blocked'` or `'offline'`. Drawn as a dot whose shape and tone
103
+ * differ per activity (a square for blocked, a hollow ring for idle, a dashed ring for offline);
104
+ * its word joins the accessible name and the dot's tooltip. Wins over `status`.
105
+ * @property {string|null} [activityLabel=null] The activity's word, when the default ("Working",
106
+ * "Needs you", …) is not the one to show.
107
+ * @property {boolean} [animate=false] Moves the avatar with its activity — idle breathes, thinking
108
+ * sways, working bobs, needs-you leans and blinks — in the one animation loop every animated
109
+ * avatar on the page shares. Motion is never the only signal, stops off screen and while the page
110
+ * is hidden, and returns the avatar to rest under reduced motion (the system's, or a
111
+ * `data-zx-motion="reduced"` region). While it is on, the root's `transform` belongs to the loop.
112
+ * @property {number|null} [phase=null] Where in its activity's cycle the avatar moves, as a
113
+ * fraction from 0 up to 1 (whole turns wrap): two avatars of the same agent on one screen — a
114
+ * roster and an inspector — at different phases never move in step, and 0.5 puts them half a cycle
115
+ * apart. `null` derives the phase from the name (or the initials), so the same agent always moves
116
+ * the same way.
117
+ * @property {Record<string, string>|Record<string, Record<string, string>>} [msg] Localized
118
+ * messages: the activity words, `agent.activity.<activity>`.
62
119
  */
63
120
  /**
64
121
  * The tone palette, in hash order. Every entry is a valid `tone`; the hash picks among the
@@ -69,7 +126,7 @@ export type AvatarOptions = {
69
126
  export declare const AVATAR_TONES: ReadonlyArray<AvatarTone>;
70
127
  /**
71
128
  * Stable-size user image with a deterministic fallback — initials on a tone picked from the name —
72
- * and an optional presence state.
129
+ * and an optional presence state for a person, or activity for an agent.
73
130
  * @extends {Component<AvatarOptions>}
74
131
  */
75
132
  export declare class Avatar extends Component<AvatarOptions> {
@@ -88,20 +145,37 @@ export declare class Avatar extends Component<AvatarOptions> {
88
145
  tone: AvatarTone;
89
146
  status: "away" | "busy" | "offline" | "online";
90
147
  statusLabel: string;
148
+ activity: import("../../internal/agent-model.js").AgentActivity;
149
+ activityLabel: string;
150
+ animate: boolean;
151
+ phase: number;
91
152
  };
153
+ /** @type {import('../../internal/presence-loop.js').PresenceHandle|null} */
154
+ _presence: import('../../internal/presence-loop.js').PresenceHandle | null;
92
155
  static cssName: string;
93
156
  /** @type {Readonly<AvatarOptions>} */
94
157
  static defaults: Readonly<AvatarOptions>;
95
158
  /** @returns {HTMLElement} */
96
159
  render(): HTMLElement;
97
160
  /**
98
- * Replaces avatar identity and presentation values.
161
+ * Replaces avatar identity and presentation values: any option but `msg`, `phase` included, so
162
+ * an animated avatar can be moved out of step with another of the same agent while it runs.
99
163
  * @param {Partial<AvatarOptions>} values New values.
100
164
  * @returns {this}
101
165
  */
102
166
  set(values?: Partial<AvatarOptions>): this;
103
167
  /** Sets the presence state and its text alternative. @param {AvatarOptions['status']} status @param {string|null} [label=null] @returns {this} */
104
168
  setStatus(status: AvatarOptions['status'], label?: string | null): this;
169
+ /**
170
+ * Sets what an agent is doing and, optionally, the word for it. `null` clears the activity, and
171
+ * a person's `status` shows again if one is set.
172
+ * @param {AgentActivity|null} activity
173
+ * @param {string|null} [label=null] The word, when the default is not the one to show.
174
+ * @returns {this}
175
+ */
176
+ setActivity(activity: AgentActivity | null, label?: string | null): this;
177
+ /** @returns {AgentActivity|null} What the agent is doing, or null. */
178
+ getActivity(): AgentActivity | null;
105
179
  /** Returns whether the image is currently visible. @returns {boolean} */
106
180
  hasImage(): boolean;
107
181
  /** Restores an enhanced target or removes an owned root. @returns {void} */
@@ -114,8 +188,21 @@ export declare class Avatar extends Component<AvatarOptions> {
114
188
  _showImage(visible: boolean): void;
115
189
  /** Ignores a late load/error from a source that has already been replaced. @returns {boolean} */
116
190
  _isCurrentImageSource(): boolean;
191
+ /** The word for the current activity, or null without one. @returns {string|null} */
192
+ _activityWord(): string | null;
117
193
  /** @returns {void} */
118
194
  _syncStatus(): void;
195
+ /**
196
+ * Joins, follows, or leaves the shared presence loop.
197
+ * @param {AgentActivity|null} activity
198
+ * @returns {void}
199
+ */
200
+ _syncMotion(activity: AgentActivity | null): void;
201
+ /**
202
+ * The phase the avatar moves at: the `phase` option, or one derived from the name or initials.
203
+ * @returns {number} A fraction of the cycle.
204
+ */
205
+ _phase(): number;
119
206
  }
120
207
  /**
121
208
  * Derives uppercase initials from the first and last words of a name.
@@ -0,0 +1,205 @@
1
+ import { Component } from '../../core/component.js';
2
+ export type Block = import('../../internal/agent-model.js').Block;
3
+ export type Source = import('../../internal/agent-model.js').Source;
4
+ export type BlockViewOptions = {
5
+ /**
6
+ * The answer's blocks. Model text is data: every string reaches
7
+ * the page as text, through the inline grammar of `**bold**`, `` `code` `` and `[n]` citations.
8
+ */
9
+ blocks?: Block[];
10
+ /**
11
+ * Element level of a `heading` block of level 2; a level-3
12
+ * heading goes one deeper. Set it one below the heading that names the answer.
13
+ */
14
+ headingLevel?: 2 | 3 | 4 | 5;
15
+ /**
16
+ * Prose size: `'sm'` sets the answer at the interface size, for
17
+ * a conversation; `'md'` at the reading size, for a document.
18
+ */
19
+ size?: 'sm' | 'md';
20
+ /**
21
+ * Whether more is still being written. The last block stays
22
+ * open to `appendText()`, and the root is busy until `end()` or `stop()`.
23
+ */
24
+ streaming?: boolean;
25
+ /**
26
+ * The sources citations point at; their titles name the
27
+ * citation buttons.
28
+ */
29
+ sources?: Source[] | null;
30
+ /**
31
+ * Localized messages.
32
+ */
33
+ msg?: Record<string, string> | Record<string, Record<string, string>>;
34
+ /**
35
+ * Citation listener.
36
+ */
37
+ oncite?: (event: CustomEvent<{
38
+ n: number;
39
+ source: Source | null;
40
+ }>) => void;
41
+ /**
42
+ * Artifact listener.
43
+ */
44
+ onartifact?: (event: CustomEvent<{
45
+ id: string;
46
+ }>) => void;
47
+ /**
48
+ * End-of-stream listener.
49
+ */
50
+ onend?: (event: CustomEvent<Record<string, never>>) => void;
51
+ };
52
+ export type RenderBlocksOptions = {
53
+ /**
54
+ * Element level of a level-2 `heading` block.
55
+ */
56
+ headingLevel?: 2 | 3 | 4 | 5;
57
+ /**
58
+ * Message lookup for the few words
59
+ * the blocks add (code copy, artifact kinds).
60
+ */
61
+ msg?: (key: string, ...args: unknown[]) => string;
62
+ };
63
+ /**
64
+ * An answer an agent wrote, drawn block by block as semantic elements inside `.zx-prose`, and
65
+ * written to as it streams. Finished blocks are never redrawn: `appendText()` and `append()` touch
66
+ * only the last block, so a reader's selection or focus in an earlier paragraph survives the rest
67
+ * of the answer arriving.
68
+ *
69
+ * @fires BlockView#cite
70
+ * @fires BlockView#artifact
71
+ * @fires BlockView#end
72
+ * @extends {Component<BlockViewOptions>}
73
+ */
74
+ export declare class BlockView extends Component<BlockViewOptions> {
75
+ _original: import("../../core/dom.js").TargetSnapshot;
76
+ /** @type {Block[]} */
77
+ _blocks: Block[];
78
+ /** @type {HTMLElement[]} */
79
+ _nodes: HTMLElement[];
80
+ /** @type {Source[]} */
81
+ _sources: Source[];
82
+ _streaming: boolean;
83
+ _stopped: boolean;
84
+ /** @type {HTMLElement|null} */
85
+ _stoppedNote: HTMLElement | null;
86
+ _observer: ResizeObserver;
87
+ _destroyed: boolean;
88
+ static cssName: string;
89
+ /** @type {Readonly<BlockViewOptions>} */
90
+ static defaults: Readonly<BlockViewOptions>;
91
+ /** @returns {HTMLElement} */
92
+ render(): HTMLElement;
93
+ /**
94
+ * Replaces every block, clearing a stopped state.
95
+ * @param {Block[]} blocks
96
+ * @param {{streaming?: boolean}} [options={}] `streaming: true` starts a new streamed answer
97
+ * from these blocks; otherwise the streaming state is kept.
98
+ * @returns {this}
99
+ */
100
+ setBlocks(blocks: Block[], options?: {
101
+ streaming?: boolean;
102
+ }): this;
103
+ /**
104
+ * Adds a block after the last one. The blocks before it are left as they are.
105
+ * @param {Block} block
106
+ * @returns {this}
107
+ */
108
+ append(block: Block): this;
109
+ /**
110
+ * Streams text into the answer. It continues the last paragraph, or opens one when the answer
111
+ * ends in anything else; a blank line in the text starts a new paragraph. Only the last
112
+ * paragraph is redrawn, so a marker split across two calls (`**bo` … `ld**`) resolves as soon as
113
+ * its close arrives.
114
+ * @param {string} text
115
+ * @returns {this}
116
+ */
117
+ appendText(text: string): this;
118
+ /**
119
+ * Marks the answer finished.
120
+ * @returns {this}
121
+ */
122
+ end(): this;
123
+ /**
124
+ * Marks the answer stopped where it is, with a line saying so.
125
+ * @returns {this}
126
+ */
127
+ stop(): this;
128
+ /**
129
+ * Sets the sources citations point at.
130
+ * @param {Source[]} sources
131
+ * @returns {this}
132
+ */
133
+ setSources(sources: Source[]): this;
134
+ /**
135
+ * Says whether an artifact's card has its artifact open somewhere — an inspector, a drawer — so
136
+ * the card reads as pressed and names what it controls. The application owns the open state;
137
+ * the card only reflects it.
138
+ * @param {string} id Artifact id.
139
+ * @param {{expanded?: boolean|null, controls?: string|null}} state `expanded` sets or (null)
140
+ * removes `aria-expanded`; `controls` sets or (null) removes `aria-controls`.
141
+ * @returns {this}
142
+ */
143
+ setArtifactState(id: string, state?: {
144
+ expanded?: boolean | null;
145
+ controls?: string | null;
146
+ }): this;
147
+ /** @returns {Block[]} A copy of the blocks. */
148
+ getBlocks(): Block[];
149
+ /** @returns {boolean} Whether more is still being written. */
150
+ isStreaming(): boolean;
151
+ /** @returns {string} The answer as plain text. */
152
+ toText(): string;
153
+ /** @returns {string} The answer as Markdown. */
154
+ toMarkdown(): string;
155
+ /** @returns {void} */
156
+ destroy(): void;
157
+ /**
158
+ * @private
159
+ * @param {Block} block
160
+ * @returns {void}
161
+ */
162
+ private _push;
163
+ /** @private @returns {void} */
164
+ private _redrawLast;
165
+ /** @private @returns {RenderBlocksOptions & {cite: (n: number) => Node, artifact: boolean}} */
166
+ private _renderOptions;
167
+ /** @private @param {number} n @returns {string} */
168
+ private _citeLabel;
169
+ /** @private @param {number} n @returns {Source|null} */
170
+ private _sourceAt;
171
+ /** @private @returns {void} */
172
+ private _syncState;
173
+ /**
174
+ * A wide table scrolls inside the answer; while it does, its wrapper is a named, focusable
175
+ * region so the keyboard can scroll it too. A table that fits is not a tab stop.
176
+ * @private
177
+ * @returns {void}
178
+ */
179
+ private _syncScrollers;
180
+ /** @private @param {MouseEvent} event @returns {void} */
181
+ private _onClick;
182
+ }
183
+ /**
184
+ * Citation listener payload.
185
+ * @event BlockView#cite
186
+ * @type {CustomEvent<{n: number, source: Source|null}>}
187
+ */
188
+ /**
189
+ * Artifact card listener payload.
190
+ * @event BlockView#artifact
191
+ * @type {CustomEvent<{id: string}>}
192
+ */
193
+ /**
194
+ * Fired when a streaming answer is marked finished.
195
+ * @event BlockView#end
196
+ * @type {CustomEvent<Record<string, never>>}
197
+ */
198
+ /**
199
+ * Draws blocks without a component, for a static answer: a transcript, a print view, a preview.
200
+ * Citations are plain superscripts and artifacts plain cards; use `BlockView` for them to act.
201
+ * @param {Block[]} blocks
202
+ * @param {RenderBlocksOptions} [options={}]
203
+ * @returns {DocumentFragment}
204
+ */
205
+ export declare function renderBlocks(blocks: Block[], options?: RenderBlocksOptions): DocumentFragment;