@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
package/docs/llms.md CHANGED
@@ -998,14 +998,28 @@ and the component is decorative by default so adjacent identity text is not anno
998
998
  - **Options** — `src`, `name`, `initials`, `label`, `size: 'sm'|'md'|'lg'|<pixels>` (24 / 32 /
999
999
  40px at the default spacing unit), `shape: 'circle'|'rounded'|'square'`, `tone:
1000
1000
  'blue'|'teal'|'green'|'amber'|'orange'|'red'|'pink'|'violet'|'slate'|null`, `status:
1001
- 'online'|'away'|'busy'|'offline'|null`, and `statusLabel`.
1001
+ 'online'|'away'|'busy'|'offline'|null`, `statusLabel`, `activity:
1002
+ 'idle'|'thinking'|'working'|'needs-you'|'blocked'|'offline'|null`, `activityLabel`, `animate: false`, and `phase: null|number`.
1002
1003
  - **Fallback** — no ring; the `--zx-color-tone-*-bg` fill with its `-fg` ink, initials at 0.4× the
1003
1004
  size (never under 10px), weight 600, one initial below 24px. `tone: null` derives the tone with
1004
1005
  `avatarTone(name)` (exported from the module): FNV-1a over the trimmed, NFC-normalised,
1005
1006
  lower-cased name, mapped onto the eight chromatic tones, so a person keeps their colour on every
1006
1007
  screen. `slate`, the neutral, is reserved for an avatar with no name and can be set explicitly.
1007
1008
  The root carries `data-tone`. `avatarInitials(name, limit = 2)` returns the initials.
1008
- - **Methods** — `set(values)`, `setStatus(status, label?)`, `hasImage()`, `destroy()`.
1009
+ - **Agent activity** — `activity` draws what an agent is doing as a dot whose shape differs as
1010
+ well as its tone: solid success (working), solid info (thinking), solid warning (needs you), a
1011
+ danger square (blocked), a hollow ring (idle), and a dashed ring (offline). Its word ("Needs
1012
+ you", or `activityLabel`) joins the accessible name and the dot's tooltip, and the root carries
1013
+ `data-activity`. When both are given, `activity` wins over `status`. `animate: true` moves the
1014
+ avatar with its activity — idle breathes, thinking sways, working bobs, needs-you leans and
1015
+ blinks — in the one `requestAnimationFrame` loop every animated avatar on the page shares: only
1016
+ on screen, never while the page is hidden, and back at rest under reduced motion (the system's
1017
+ or a `data-zx-motion="reduced"` region). While it is on, the loop owns the root's `transform`. `phase` sets where in its activity's cycle the avatar moves, as a fraction from 0 up to 1
1018
+ (whole turns wrap): two avatars of one agent on the same screen — a roster and an inspector —
1019
+ at `phase: 0` and `phase: 0.5` move half a cycle apart. `null` derives the phase from the name
1020
+ (or the initials), so avatars of the same agent without a phase move in step.
1021
+ - **Methods** — `set(values)` (any option above, `phase` included, applied while the avatar moves), `setStatus(status, label?)`,
1022
+ `setActivity(activity, label?)`, `getActivity()`, `hasImage()`, `destroy()`.
1009
1023
  - **Accessibility** — set `label` only when the avatar stands alone. Presence is supplementary
1010
1024
  status, not the account's accessible name; supply `statusLabel` when it conveys information.
1011
1025
  <!-- /doc -->
@@ -3278,6 +3292,445 @@ bar.setBadge('mail', 8);
3278
3292
  `--zx-control-height` resizes the bar; a coarse pointer keeps a 40px target.
3279
3293
  <!-- /doc -->
3280
3294
 
3295
+ ### Agents — the conversation model
3296
+
3297
+ The agent components draw a conversation with one or more AI agents from **plain JSON**: no
3298
+ functions and no DOM nodes in the data, so an agent can produce it, an application can store and
3299
+ replay it, and a component can render it. Three rules hold for every agent component:
3300
+
3301
+ 1. **The application owns transport and state.** No agent component fetches anything. The
3302
+ application feeds them (`upsert`, `patch`, `appendText`) and acts on the intents they emit
3303
+ (`send`, `stop`, `approve`, `regenerate`, …).
3304
+ 2. **Model text is data.** Every string an agent wrote reaches the page as text. Inside a text run
3305
+ the whole grammar is `**bold**`, `` `code` `` and `[n]` citations (a backslash makes a marker
3306
+ literal); there are no links, no HTML, and no images in answer text.
3307
+ 3. **Consequence comes from the application.** Whether an action needs a confirmation — and which
3308
+ — is decided by the application from the tool the action triggers, never taken from model
3309
+ output.
3310
+
3311
+ A thread is a list of items, each `{id, type, at?, author?, …}`, where `author` is a key into
3312
+ the thread's `authors` (`{name, kind: 'person'|'agent'|'model', initials?, tone?, activity?, via?}`):
3313
+
3314
+ ```json
3315
+ [
3316
+ {"id": "ask", "type": "user", "text": "Reconcile September and draft reminders.", "files": [{"name": "Policy.pdf", "size": 188416}]},
3317
+ {"id": "note", "type": "text", "author": "finance", "text": "I’ll check the bank feed first."},
3318
+ {"id": "work", "type": "trace", "author": "finance", "steps": [
3319
+ {"id": "q", "kind": "query", "label": "Queried invoices", "count": "42 rows", "ms": 800, "tool": "invoices.search", "args": "{\"month\": \"2026-09\"}", "result": "42 invoices"}
3320
+ ]},
3321
+ {"id": "a1", "type": "answer", "author": "finance", "blocks": [
3322
+ {"type": "p", "text": "Three invoices are more than **14 days** late [1]."},
3323
+ {"type": "figures", "rows": [["Late", "3 invoices", "€19,375.50"]]}
3324
+ ], "sources": [{"id": "inv", "title": "Invoices · September", "kind": "call", "call": "q"}]},
3325
+ {"id": "ok", "type": "approval", "author": "finance", "title": "Send 3 reminder emails?", "status": "pending"},
3326
+ {"id": "n1", "type": "notice", "text": "The bank feed timed out; retried once.", "tone": "warning"}
3327
+ ]
3328
+ ```
3329
+
3330
+ - **Blocks** — `p`, `quote`, `heading` (`level: 2|3`), `list` (`ordered`), `code` (`language`),
3331
+ `table` (`columns`, `rows`, `align`), `figures` (`rows` of `[label, detail, value]` or
3332
+ `{label, detail?, value, call?}`), `callout` (`tone`, `title`), `artifact` (`id`, `title`,
3333
+ `kind: 'document'|'code'`, `versions`).
3334
+ - **Steps** — `{id, kind: 'search'|'read'|'query'|'write'|'run'|'call'|'handoff'|'think', label,
3335
+ status, doing?, detail?, ms?, count?, sources?, tool?, args?, result?, error?, retryOf?, actor?,
3336
+ to?, at?}`. A retry names the step it repeats with `retryOf`; a hand-off names `actor` and `to`.
3337
+ - **States** — runs and steps are `queued`, `running`, `waiting`, `paused`, `done`, `failed`,
3338
+ `stopped`, or `skipped`; an agent's activity is `idle`, `thinking`, `working`, `needs-you`,
3339
+ `blocked`, or `offline`. Each is always drawn as a glyph and a word, never by colour or motion
3340
+ alone.
3341
+
3342
+ <!-- doc:block-view -->
3343
+ ### BlockView — `new BlockView(target, options)` / `renderBlocks(blocks, options)`
3344
+
3345
+ An answer an agent wrote, drawn block by block as semantic elements inside `.zx-prose`, and
3346
+ written to as it streams. Finished blocks are never redrawn: `append()` and `appendText()` touch
3347
+ only the last block, so a reader's selection or focus in an earlier paragraph survives the rest of
3348
+ the answer arriving.
3349
+
3350
+ - **Options** — `blocks: []`, `headingLevel: 3` (the element level of a level-2 `heading` block;
3351
+ set it one below the heading that names the answer), `size: 'sm'|'md'` (interface or reading
3352
+ size), `streaming: false`, `sources: null` (names the citation buttons by title), `msg`.
3353
+ - **Methods** — `setBlocks(blocks, {streaming?})`, `append(block)`, `appendText(text)` (continues
3354
+ the last paragraph, or opens one; a blank line in the text starts a new paragraph; a marker split
3355
+ across two chunks resolves when its close arrives), `end()`, `stop()` (adds "Stopped here."),
3356
+ `setSources(sources)`, `setArtifactState(id, {expanded, controls})` (reflects whether the
3357
+ application has the artifact open somewhere), `getBlocks()`, `isStreaming()`, `toText()`,
3358
+ `toMarkdown()`, `destroy()`. A single line break in model text is kept (an address, a sign-off); a
3359
+ blank line starts a new paragraph.
3360
+ - **Events** — `cite {n, source}` from a citation button, `artifact {id}` from an artifact card,
3361
+ `end` when a streamed answer is marked finished.
3362
+ - **Rendering** — code is a figure with its language, a copy button and a focusable `<pre>`
3363
+ (`lines: true` on a code block numbers its lines and wraps long ones under their own indent, for
3364
+ code read at length in an inspector),
3365
+ coloured for js, ts, json, sql, python, shell and css (anything else stays plain); a wide table
3366
+ scrolls inside the answer and becomes a named, focusable region only while it overflows; figures
3367
+ are a `<dl>` with tabular numbers; a callout uses `.zx-callout` with its tone as `data-kind`.
3368
+ - **Static** — `renderBlocks(blocks, options)` returns a `DocumentFragment` for a transcript or a
3369
+ print view: citations are plain superscripts and artifacts plain cards. `blocksToMarkdown(blocks)`
3370
+ and `blocksToText(blocks)` export an answer for copying and search.
3371
+ - **State** — `data-state` is `streaming`, `done` or `stopped`; the root is `aria-busy` while it
3372
+ streams. Streamed text is never inside a live region.
3373
+ <!-- /doc -->
3374
+
3375
+ <!-- doc:agent-thread -->
3376
+ ### AgentThread
3377
+
3378
+ A conversation with one or more agents, drawn from the items above: the person's messages, the
3379
+ agents' answers as they stream (`BlockView` with a `SourceList`), the steps a run took
3380
+ (`RunTrace`), the approvals that hold it (`ApprovalCard`), and one-line notices.
3381
+
3382
+ - **Options** — `items: []`, `authors: {}`, `me: 'me'` (the reader's author key; an item without
3383
+ `author` is the reader's when it is a `user` item), `label` (the feed's name, "Conversation"),
3384
+ `headingLevel: 3`, `emptyState: null` (`emptyState()` options shown while empty),
3385
+ `followOutput: true`, `scroller: null` (the element that scrolls; the nearest scrolling ancestor
3386
+ when null), `answerActions: ['copy', 'regenerate', 'branch']` (add `'rate'` for helpful / not
3387
+ helpful), `userActions: []` (`'edit'`, `'copy'` on the reader's own messages, revealed while the
3388
+ message is pointed at or holds focus), `icons` (glyphs for `regenerate`, `branch`, `rateUp`,
3389
+ `rateDown`, `edit`), `traceIcons` (handed to every `RunTrace` it draws), `now: null` (the clock
3390
+ "today" is measured against, for a world on fixed dates), `formatTime`, `locale`, `msg`.
3391
+ - **Item extras** — any item's `refs: [{id, label, icon?, entity?}]` draws links to the
3392
+ application's own things after its content (`open {item, ref}`); a `user` item's `mentions`
3393
+ (names, or `{name, tone}`) marks each `@name` in its text; an `answer`'s `steps` show the work it
3394
+ did inline above its text (`stepsOpen` opens them) and, like `stopped`, `rating` and `at`, follow
3395
+ its version (`versions[]`); a `trace`'s `title` replaces its summary (a plan:
3396
+ "Plan · 5 of 6 done"); a `notice` is named by its own text and may carry `action: {id, label}`
3397
+ (`action {item, action: id}`); an author with an `icon` is drawn as a tinted tile instead of
3398
+ initials (round for a `model`; `tone: 'accent'` for the accent's quiet fill); an `approval`'s
3399
+ `editedKeys` say which values the person changed. `setArtifactState()` is remembered for answers
3400
+ drawn later; `sourceIcons` is handed to every `SourceList`.
3401
+ - **Methods** — `setItems(items)`, `upsert(item)` (adds, or replaces in place by `id`),
3402
+ `patch(id, partial)` (an answer finishing, stopping or gaining sources, a trace's steps, an
3403
+ approval's status change in place; anything else redraws the item), `appendText(id, text)`
3404
+ (streams into an answer, creating it when the id is new), `appendBlock(id, block)` (adds a whole
3405
+ block — figures, a table — without redrawing the answer), `announce(text)` (says an outcome
3406
+ through the thread's polite status), `setArtifactState(id, {expanded, controls})` (whether an
3407
+ artifact is open in an inspector, on every card naming it), `remove(id)`, `get(id)`,
3408
+ `getItems()`, `getComponent(id)`, `reveal(target)` (`item:<id>`, `step:<id>`, `source:<n>`),
3409
+ `scrollToEnd()`, `destroy()`. The static `AgentThread.register(type, render)` draws an item type
3410
+ of the application's own; `render(item, {thread, author, own})` returns its content, and `own()`
3411
+ hands a component to the thread to destroy with the item.
3412
+ - **Events** — `action {item, action, value?}` (`copy`, `regenerate`, `branch`, `rate` with
3413
+ `up`/`down`/null, `version` with an index — preventable for `rate` and `version`; `edit` on the
3414
+ reader's message; a notice's action id), `open {item, ref, step?}` (an item's link, or a trace
3415
+ step's),
3416
+ `approve {item, values}`, `edit {item, values}`, `reject {item, reason}` (preventable: the card
3417
+ stays pending), `cite {item, n, source}` (preventable: by default the cited source is
3418
+ highlighted), `artifact {item, id}`, `reveal {target}`. Each reaches a listener on the thread's
3419
+ root once, as the thread's `zx-*` event: the cards, answers and traces inside it do not bubble
3420
+ their own copies past it. A source that names a `call` reveals that
3421
+ step in the trace.
3422
+ - **Turns** — consecutive items by the same agent read as one turn: the avatar and byline are drawn
3423
+ once, and the byline still names every article. The reader's own messages sit at the end as a
3424
+ bubble without an avatar.
3425
+ - **Following output** — while the reader is at the end, new output keeps the end in view;
3426
+ scrolled up, a "Jump to latest" button appears and the reader is never moved. While a streaming
3427
+ answer has nothing yet, a quiet line says who is writing.
3428
+ - **Narrow** — the thread is a size container; below 30rem the content takes the full width and
3429
+ the avatar stays beside the byline.
3430
+ - **Keyboard and semantics** — the APG feed pattern: each item is an `article` in a `role="feed"`
3431
+ with `aria-posinset`, `aria-setsize` and `aria-labelledby` its byline; PageDown and PageUp move
3432
+ between articles; Ctrl+End and Ctrl+Home move focus past the end or before the start of the feed.
3433
+ The feed is `aria-busy` while an answer streams. One polite status says when an agent starts
3434
+ writing, answers, needs approval, or is stopped — streamed text is never read aloud as it arrives.
3435
+ <!-- /doc -->
3436
+
3437
+ <!-- doc:run-status -->
3438
+ ### RunStatus
3439
+
3440
+ Where an agent's run stands, for a run panel or a narrow header: the state as a glyph and a word,
3441
+ one sentence on what is happening, the steps as a progressbar, when it started and how long the
3442
+ agent has worked, the tokens, and the cost against a budget. It draws the values it is given and
3443
+ announces nothing itself; the thread the run belongs to announces its milestones.
3444
+
3445
+ - **Options** — `state` (a run state: `queued`, `running`, `waiting`, `paused`, `blocked`, `done`,
3446
+ `failed`, `stopped`, `skipped`; default `'queued'`, reflected as `data-state`), `summary` (one
3447
+ sentence, text only), `steps: {done, total}|null`, `started`, `finished` and `waitingSince`
3448
+ (local ISO date-time strings or `Date`s), `workMs` (milliseconds worked; the row shows only when
3449
+ it is a number), `tokens: [in, out]|number|null` (the pair, or the total as one number),
3450
+ `tokenBudget: number|null`, `cost: {amount, budget?, currency}|null`, `model`,
3451
+ `actions: [{label, kind?, icon?, onclick?}]`, `ticking: true`, `compact: false|true|'icon'`,
3452
+ `now: (() => Date)|null`, `locale`, and `msg` (the `agent.status.*` words and the `runStatus.*`
3453
+ labels).
3454
+ - **Rendering** — the state line; the summary; a `role="progressbar"` whose `aria-valuetext` reads
3455
+ "3 of 6 steps"; the actions as small buttons; and a `<dl>` of Started, Working time, Waiting
3456
+ since (while `waiting`) or Blocked since (while `blocked`), Finished / Failed at / Stopped at
3457
+ (once the run is over), Model, Tokens ("18,420 in · 1,236 out", or "22,840" for a total) and
3458
+ Cost. With a `budget` the cost is a `role="meter"` reading "€0.14 of €2.00" whose `data-level`
3459
+ is `warning` from 80% and `danger` at 100%. With a `tokenBudget` the tokens are a meter the same
3460
+ way, in the locale's compact figures (`Intl.NumberFormat` `notation: 'compact'`): "22.8K of 60K
3461
+ tokens"; without one they stay text. A time on another day than today shows its date too.
3462
+ - **Blocked** — `blocked` is a glyph and the word "Blocked" in the danger tone, and the steps bar
3463
+ takes the danger tone. A blocked run is not over: it shows "Blocked since" from `waitingSince`
3464
+ and never a finished time.
3465
+ - **Compact** — `compact: true` (reflected as `data-compact`) draws only the state, glyph and
3466
+ word, as a pill for a header too narrow for the panel. `compact: 'icon'`
3467
+ (`data-compact="icon"`) draws the glyph alone, for a list row: the word stays in the pill,
3468
+ visually hidden, as its accessible text, and is the pill's `title` tooltip.
3469
+ - **Ticking** — while `state` is `running` and `ticking` is on, the working time counts on once a
3470
+ second from `workMs` and the moment of the last `update()`, through one interval that sleeps
3471
+ while the page is hidden. Leaving `running` freezes the clock where it stands. `now` replaces
3472
+ the clock, both for that count and for deciding whether a time is today; a fixed `now` makes the
3473
+ panel deterministic for screenshots and tests. It is fixed at construction.
3474
+ - **Focus** — `update()` keeps focus where it was: an action row whose labels, kinds, and icons did
3475
+ not change is kept as it is, so the focused button never leaves the DOM; otherwise focus goes to
3476
+ the action at the same index, or the nearest one left. When no action is left the panel itself
3477
+ holds focus (`tabindex="-1"`, removed again once focus moves on).
3478
+ - **Methods** — `update(values)` merges new values and redraws (the clock carries on unless the
3479
+ update brings a new `workMs`; `locale`, `msg`, `now`, and `onaction` are fixed), `getState()`
3480
+ (the values as copies, `tokenBudget` included, `workMs` counted up to now), `destroy()`.
3481
+ - **Events** — `action {index, action}`, after the descriptor's own `onclick`.
3482
+ <!-- /doc -->
3483
+
3484
+ <!-- doc:composer -->
3485
+ ### Composer — the message box of an agent conversation
3486
+
3487
+ A text that grows with what is written, Send (Stop while the agent works), attachments, `@`
3488
+ mentions, `/` commands, extra tools and removable context chips. It keeps only the unsent message:
3489
+ `send` hands the text, files, mentions and context to the application, which owns the conversation
3490
+ and the transport.
3491
+
3492
+ - **Constructor** — `new Composer(null, options)` creates its own root; `new Composer(element,
3493
+ options)` takes over an element and restores it on `destroy()`.
3494
+ - **Options** — `label` (accessible name of the text and of the `role="group"` root, English
3495
+ `Message`), `placeholder`, `value`, `submitKey: 'enter'|'mod+enter'`, `busy: false`,
3496
+ `disabled: false`, `attachments: false`, `accept: ''` (the `<input type="file">` syntax),
3497
+ `maxFiles: 10`, `mentions: null|{trigger: '@', items}` where `items` is `[{id, label,
3498
+ description?, icon?}]` or `(query) => items | Promise<items>`, `commands: null|LauncherItem[]`,
3499
+ `tools: []` (`[{id, label, icon, pressed?, expanded?, controls?, disabled?}]` — `pressed` makes a
3500
+ toggle, `expanded`/`controls` a disclosure; see Tools), `icons: {}` (`attach`, `commands` glyphs),
3501
+ `context: [{id, label,
3502
+ icon?, ref?}]`, `hint` (quiet text beside Send), `note` (a quiet line under the composer, also
3503
+ its description), `sendLabel: null` (visible text on Send, see Send), `draftKey: null`,
3504
+ `minRows: 1` (the text never shrinks below it, even empty; capped at `maxRows`), `maxRows: 10`
3505
+ (it scrolls beyond), `msg`.
3506
+ - **Methods** — `focus()`, `getValue()`, `setValue(text)`, `insertText(text)` (types at the caret
3507
+ as the person would — text ending in `@` opens the suggestions), `clear()` (text, files and draft;
3508
+ context stays), `setBusy(busy)`, `isBusy()`, `setDisabled(disabled)`, `setHint(text)`,
3509
+ `setNote(text)` (an empty text hides either), `update(partial)`, `setTools(tools)`,
3510
+ `setToolPressed(id, pressed)`, `addFiles(files)`, `getFiles()`, `addContext(chip)` (replaces a
3511
+ chip with the same id), `removeContext(id)`, `getContext()`, `destroy()`. The setters emit
3512
+ nothing.
3513
+ - **update(partial)** — changes `label`, `placeholder`, `hint`, `note`, `submitKey`, `sendLabel`,
3514
+ `disabled` and `busy` in place; a key left out or `undefined` is kept, other keys are ignored.
3515
+ The text, its caret and selection, the focus, the attachments, the context chips and the draft
3516
+ all stay, so a placeholder that names the chosen model follows the model picker without
3517
+ recreating the composer: `composer.update({placeholder: 'Message Halden 3 Deep'})`.
3518
+ `label: null` returns to `composer.label`; an empty `placeholder` removes it.
3519
+ - **Events** — `send {text, files, mentions, context}` is preventable: unless prevented, the text,
3520
+ files and draft clear; it never fires with an empty text and no files, nor while busy. `text` is
3521
+ trimmed; `mentions` are the picked items whose `@<label>` is still in the text. `stop`,
3522
+ `input {text}`, `attach {files}` (preventable, before the files are added), `remove {kind:
3523
+ 'file'|'context', id, file?, chip?}` (after the reader removes one), `mention {item}`,
3524
+ `command {item}` (the application's own item), `tool {id, tool}` (a copy of the tool as it
3525
+ stands, `pressed` included), `historyprevious`.
3526
+ - **Keyboard** — `submitKey: 'enter'`: Enter sends, Shift+Enter breaks the line;
3527
+ `'mod+enter'`: Cmd+Enter (Ctrl+Enter elsewhere) sends, Enter breaks the line. A key during an IME
3528
+ composition never sends. Escape closes the suggestions, otherwise emits `stop` while busy (and is
3529
+ left alone when idle, so a surrounding dialog can close). ArrowUp on an empty text emits
3530
+ `historyprevious`; `/` on an empty text opens the commands. In the suggestions, Up and Down move,
3531
+ Enter or Tab picks, Escape closes. Tools are ordinary buttons in the tab order (Enter or Space).
3532
+ No key is bound on the document.
3533
+ - **Tools** — icon buttons in the bar after Attach and Commands, each named by its `label` (also
3534
+ its `title` tooltip). A boolean `pressed` makes a toggle with `aria-pressed`, drawn with the
3535
+ neutral current fill and an edge; without it the tool is a plain button. Pressing one emits
3536
+ `tool`; the composer never changes `pressed` itself — call `setToolPressed(id, !tool.pressed)`.
3537
+ `setTools(tools)` redraws them, keeping the focus on the tool with the same id (on the text when
3538
+ that tool is gone or disabled). An entry without `id`, `label` or `icon` is left out, as is a
3539
+ repeated id; other fields on a tool are handed back in `tool`. `icon` is a built-in glyph name or
3540
+ one the application registered with `registerIcons()`. Tools are disabled with the composer.
3541
+ - **Send** — one button that swaps its glyph, name and `aria-keyshortcuts` between Send and Stop.
3542
+ With `sendLabel` (`'Start task'`) it shows the glyph and that text, which is also its accessible
3543
+ name; while busy it reads `composer.stop` ("Stop"). In a composer narrower than 24rem (a phone, a
3544
+ side column) the text is visually hidden and Send is the square glyph again — the text stays its
3545
+ accessible name and its tooltip.
3546
+ - **Mentions** — the query is the text after the trigger up to the caret, with no whitespace;
3547
+ picking writes `@<label> `. An array is filtered by label prefix, word prefix, label substring,
3548
+ then id prefix or a word of the description, ignoring case and accents. A function answers the
3549
+ query itself; a stale Promise is ignored.
3550
+ - **Commands** — opened in a `Launcher` the composer creates on first use and destroys with
3551
+ itself; an item with `items` opens a page. The commands keep the order given. A Commands button
3552
+ in the bar opens the same list for pointer and touch.
3553
+ - **Files** — the Attach button, pasting files, and dropping files on the composer (the root shows
3554
+ `data-state="dropping"` and a drop label meanwhile) add attachments, filtered by `accept` and
3555
+ capped by `maxFiles`.
3556
+ - **Accessibility** — the `<textarea>` keeps its textbox role. While suggestions show it carries
3557
+ `aria-autocomplete="list"`, `aria-controls` (the listbox) and `aria-activedescendant` (the
3558
+ highlighted `role="option"`), and a polite status says how many there are. Attachments and
3559
+ context chips are labelled lists, each chip with a button named "Remove <name>". Send is never
3560
+ disabled while the composer is live (it is `aria-disabled` when there is nothing to send), so
3561
+ the focus it holds survives a run ending. A toggled tool states itself with `aria-pressed`, not
3562
+ colour alone.
3563
+ - **Draft** — with `draftKey`, the unsent text is kept through `storage('composer')`, restored
3564
+ when the composer is created without a `value`, and cleared on send and `clear()`.
3565
+ <!-- /doc -->
3566
+
3567
+ <!-- doc:approval-card -->
3568
+ ### ApprovalCard
3569
+
3570
+ A request that holds an agent's run until a person answers it: what the agent wants to do, what
3571
+ will happen, a preview of what it produces, and Approve, Edit, and Reject. Answered, it freezes
3572
+ into the record of what was decided, by whom, and when. The card never acts on its own — it emits
3573
+ the answer, and the application carries it out.
3574
+
3575
+ - **Options** — `title`, `description`, `icon: null` (an icon name for the tinted tile), `tone:
3576
+ 'blue'` (`slate|blue|teal|green|amber|orange|red|pink|violet`), `headingLevel: 3`,
3577
+ `status: 'pending'|'approved'|'rejected'|'expired'`, `details: Node|Block[]|null` (recipients,
3578
+ amounts, records), `preview: {label, content: Node|Block[]}|null` (behind a disclosure; `blocks`
3579
+ is accepted for `content`, as the thread model spells it), `fields: Record<string,
3580
+ FieldOptions>|null` (the Edit form — no fields, no Edit), `values: {}`, `confirmText: null`,
3581
+ `reason: 'optional'|'required'|'none'` (whether Reject asks why), `answeredBy: null` (the verdict's
3582
+ "you" when null), `answeredAt: null` (local ISO date-time or Date), `edited: false`,
3583
+ `editedKeys: null` and `rejectReason: null` (for a card restored from a record), `now: null`
3584
+ (a `() => Date` clock), `keys: true`, and `msg`.
3585
+ - **Edited values** — `edited: true` lists every field under "Edited by you"; `editedKeys:
3586
+ ['subject']` lists only those (in field order) and on its own marks the card edited. The card's
3587
+ own Edit flow keeps `editedKeys` as the union of every save so far, so a restored card and a
3588
+ card edited in place list the same thing.
3589
+ - **Events** — `approve {values}`, `edit {values, changed, editedKeys}`, `reject {reason}`, all
3590
+ **preventable** (on the component or on the bubbling `zx-*` event). Unless `approve` or `reject`
3591
+ is prevented the card moves to its answered state; a saved `edit` keeps it pending and adopts
3592
+ the values. `changed` names the fields this save changed. `editedKeys` is the union the card
3593
+ will list (null when it lists every field), so the application can store it with the record.
3594
+ Prevent an answer to refuse or defer it, then settle the card with `setStatus()`.
3595
+ - **Methods** — `update(partial)` changes any of `title`, `description`, `icon`, `tone`,
3596
+ `details`, `preview`, `fields`, `values`, `confirmText`, `reason`, `edited`, `editedKeys` in
3597
+ place (see below); `setStatus(status, {by?, at?, reason?})` (emits nothing; `at` defaults to
3598
+ now; closes any of the card's open dialogs), `getStatus()`, `getValues()` (a copy, edits
3599
+ included), `getEditedKeys()` (`[]` when not edited, `null` when every field is listed),
3600
+ `focus()` (the root is `tabindex="-1"`, so a thread can move focus to a request when a run
3601
+ starts waiting), `handleKey(event)` → `boolean`, and `destroy()` (also destroys the card's
3602
+ dialogs, including an open confirmation).
3603
+ - **Update in place** — `update()` is for a request the agent revises while it waits, or a record
3604
+ that changed. It redraws only what changed: values equal to what is drawn (compared by content,
3605
+ so a fresh copy of the same blocks or fields counts as equal) are left alone, and focus stays
3606
+ where it was. When the focused control goes away (Edit when `fields` go, the preview toggle when
3607
+ `preview` goes), focus moves to the card. A change closes a dialog only when the dialog no
3608
+ longer applies: new `fields` close the Edit form, a new `reason` closes the Reject dialog, a new
3609
+ `confirmText` closes the typed confirmation without approving. An open Edit form stays open over
3610
+ new `values`. Status goes through `setStatus()`. `update()` emits nothing.
3611
+ - **Approve** — with `confirmText`, Approve first opens `Dialog.confirm({confirmText, danger:
3612
+ true})` titled with the card's title; only a confirmed approval emits `approve`.
3613
+ - **Reject** — `reason: 'optional'` asks in a dialog with a textarea and accepts an empty answer;
3614
+ `'required'` keeps the Reject button disabled until the reason is non-empty; `'none'` rejects at
3615
+ once with `reason: ''`. Mod+Enter submits the Reject and Edit dialogs.
3616
+ - **Answered state** — no actions; the line under the title becomes the verdict ("Approved by you
3617
+ at 10:31"; the date is added when it is not today, by the `now` clock); the edited values and
3618
+ the reason (as a quote) stay. An answer given on the card, or a `setStatus()` without `at`,
3619
+ takes its time from `now`. `data-state` is the status, and the state pill is a `statusIcon()`
3620
+ glyph plus its word (waiting, done, skipped, stopped glyphs for pending, approved, rejected,
3621
+ expired).
3622
+ - **Keyboard** — A approves, E edits, R rejects, only while focus is inside the pending card, not
3623
+ in a text control, with no modifier held, and while none of the card's dialogs is open. The card
3624
+ binds no document key: an application that wants them from elsewhere forwards the event to
3625
+ `handleKey(event)`, which returns true and prevents the default when it used the key.
3626
+ `keys: false` stops the card listening on itself (and drops the key hints on its buttons).
3627
+ - **Accessibility** — `role="group"` labelled by the title heading and described by the
3628
+ description and the state line; a pending card says "The run is paused until you answer."
3629
+ (message `approvalCard.paused`). The preview toggle follows the APG Disclosure pattern.
3630
+ - **Consequence comes from the application** — whether an action needs `confirmText` (or
3631
+ `reason: 'required'`) is decided by the application from the tool the action triggers. It is
3632
+ never taken from model output: an agent that could set its own confirmation could also waive it.
3633
+ <!-- /doc -->
3634
+
3635
+ <!-- doc:run-trace -->
3636
+ ### RunTrace
3637
+
3638
+ What an agent did during a run: a one-line summary ("Worked for 41 s · 5 tool calls · 9 sources ·
3639
+ 1 retry") that opens into a timeline of its steps. A tool call opens to the arguments it was made
3640
+ with and what came back; a retry is drawn under the call it repeats; a hand-off shows both agents.
3641
+ The same component draws a plan: `task` steps under a `label` of the plan's own, the people's
3642
+ `ask` and `decision` steps among them, chosen one at a time with `selectable`. The trace changes
3643
+ only when the application calls `setSteps()`, `upsert()` or `setLabel()`.
3644
+
3645
+ - **Options** — `steps: []` (`TraceStep[]`, in the order they started), `open: false` (the step
3646
+ list starts open), `label: null` (text the summary reads instead of the computed line — "Close
3647
+ September · 2 of 5 done"; every state but done still follows it as a word, "· Running"),
3648
+ `authors: {}` (who the steps' `actor` and `to` keys name), `showArguments: true`,
3649
+ `maxResult: 4000` (characters of a result shown before a "Show all" button; 0 shows every
3650
+ result whole), `summary: true` (false: no summary line, the list always shows — for a run panel
3651
+ whose state is told beside it), `kindIcons: null` (whether a step leads with its kind's glyph;
3652
+ null hides them for a plan whose steps are all `task`s), `selectable: false` (every step can be chosen, see Events), `ticking: false`
3653
+ (a running step that has `at` counts its time once a second, on from its `ms` when it was
3654
+ resumed), `now: null` (`() => Date`, the
3655
+ clock `ticking` counts against, for an application whose world is fixed on another date; real
3656
+ time when null), `formatTime: null` (`(at) => string`, how a step's start time is written;
3657
+ "10:31:05" when null), `icons: {}` (glyph per step kind over the built-in `search`→search,
3658
+ `read`→file, `query`→table, `write`→type, `run`→code, `call`→gear, `handoff`→link-2,
3659
+ `think`→dots, `task`→list, `ask`→mail, `decision`→check), `msg` (`runTrace.*` and the
3660
+ `agent.status.*` words).
3661
+ - **Methods** — `setSteps(steps)` (open steps stay open, focus stays on its step),
3662
+ `upsert(step)` (replaces the step with the same `id` and redraws only that step, keeping its
3663
+ retries, its open state, and focus on its row or links; a new step is appended, under the step
3664
+ it repeats when it has `retryOf`), `setLabel(text|null)` (null or `''` goes back to the computed
3665
+ line), `expand(id?)` (opens the list, and that step), `collapse(id?)` (closes the list, or only
3666
+ that step), `reveal(id)` (opens the list and the step, scrolls to it, focuses its row and marks
3667
+ it `data-state="revealed"` for 2 s; the scroll jumps under reduced motion), `getSteps()`,
3668
+ `isOpen()`, `destroy()` (also stops the clock).
3669
+ - **Events** — `toggle {id, open}` whenever the list (`id: null`) or a step opens or closes, from a
3670
+ click or a method; `reveal {id}`; `open {step, ref}` when one of a step's links is activated
3671
+ (copies; the application opens what the `ref` names); `select {id}` in a `selectable` trace when
3672
+ the reader activates a row with nothing to open, or opens a step's disclosure (not from
3673
+ `expand()` or `reveal()`, so an application can answer `select` with them).
3674
+ - **Rendering** — while a step runs the summary reads "Working…" with the step's `doing` line, and
3675
+ the step shows "Reading the policy…"; with `ticking` and an `at`, its end shows how long it has
3676
+ run ("41 s", "1 min 42 s"). A waiting or blocked run says so and names the step ("Blocked after
3677
+ 12 s · 3 tool calls"); paused, stopped and failed runs say so first ("Failed after 12 s · 3
3678
+ tool calls"); a run no step of which has started reads "Not started · 6 steps". Counts are left
3679
+ out at zero, and `think`, `handoff`, `task`, `ask` and `decision` steps are not tool calls. Each
3680
+ step's muted meta line follows its label and wraps under it only when narrow: the `count`, a
3681
+ search's `sources`, the actor's name, the start time (`<time>`, tabular figures) and the
3682
+ `tokens` it used ("912 tokens"), each only when present. A step's `refs` (`ItemRef[]`, `{id,
3683
+ label, icon?, entity?}`) are quiet underlined link buttons under its words, with the glyph when
3684
+ `icon` is set. A step with `args`, `result`, `error` or `detail` is a disclosure holding the tool
3685
+ name (mono), the detail, the arguments (pretty-printed when they parse as JSON, verbatim
3686
+ otherwise) and the result or the error, each in a focusable `<pre>` with a copy button. A
3687
+ `handoff` step reads "Finance agent handed over to Collections agent" beside both authors'
3688
+ avatars joined by a dotted line — round for a `person`, a rounded square for an agent or a
3689
+ model — and its own label moves to the meta line.
3690
+ - **Accessibility** — the summary and every step with content follow the APG Disclosure pattern
3691
+ (`aria-expanded`, `aria-controls`); in a `selectable` trace a step without content is a plain
3692
+ `<button>`. A step's links are buttons beside its row, never inside it, so no control holds
3693
+ another; each is reached with Tab. The running step carries `aria-current="step"`. Every state
3694
+ is a glyph and a word: visible for waiting, blocked, failed, stopped, skipped and queued steps
3695
+ (blocked and failed in the danger tone), visually hidden beside a finished step's duration and a
3696
+ running step's "…ing" line. The running glyph pulses only without a reduced-motion preference.
3697
+ The clock is one interval for the whole trace, running only while a counting step is in the open
3698
+ list and the page is visible. The trace has no live region; the thread it sits in announces
3699
+ milestones.
3700
+ - **State** — the root's `data-state` is the run's state (`running`, `waiting`, `blocked`,
3701
+ `paused`, `stopped`, `failed`, `queued`, `done`), and it is hidden while it has no steps. Each
3702
+ step's `<li>` carries `data-kind` and `data-status`.
3703
+ <!-- /doc -->
3704
+
3705
+ <!-- doc:source-list -->
3706
+ ### SourceList
3707
+
3708
+ The sources an answer cites: a numbered chip (or row) for each, naming its site or title, with a
3709
+ card of its title, where it is, and the passage used on hover and focus. It never loads a favicon,
3710
+ a thumbnail, or any other remote resource.
3711
+
3712
+ - **Options** — `sources: []` (`Source[]`, numbered in order as the answer's `[n]` markers are),
3713
+ `label: 'Sources'` (the visible label naming the list; `''` drops it and names the list with
3714
+ the `sourceList.label` message), `layout: 'chips'|'list'` (`list` gives each source a row with
3715
+ its title and site), `numbered: true`, `icons: {}` (glyph per kind over the built-in
3716
+ `web`→link-2, `file`→file, `record`→table, `call`→gear), `msg`.
3717
+ - **Methods** — `setSources(sources)` (focus stays on the same source), `highlight(n)` (a number is
3718
+ the 1-based position, a string an `id`: scrolls to it, focuses it, and marks it
3719
+ `data-state="highlighted"` for 2 s — the answer to a BlockView `cite`), `getSources()`,
3720
+ `destroy()`.
3721
+ - **Events** — `select {source, n}`, **preventable** (on the component or on the bubbling
3722
+ `zx-select`). Unprevented, a `web` source opens its `href` in a new tab with
3723
+ `noopener,noreferrer`, and only when `safeHref()` accepts it and it is an absolute `https:` URL;
3724
+ the card shows that host. Every other kind is the application's to act on, for example
3725
+ `runTrace.reveal(source.call)`.
3726
+ - **Accessibility** — each source is a native `<button>` named "Source 1: bank.example" (the
3727
+ visible number and name, plus visually hidden words); its card is a `Tooltip`, so it is the
3728
+ button's description while open. The list is an `<ol>` labelled by the visible label. It is not
3729
+ a landmark, so a thread with many answers does not repeat a "Sources" region.
3730
+ - **Privacy** — the pure `sourceHref(source)` returns the only address a source may open, or null;
3731
+ nothing is fetched to draw a source.
3732
+ <!-- /doc -->
3733
+
3281
3734
  <!-- doc:kernel -->
3282
3735
  ### Core helpers
3283
3736
 
package/docs/llms.txt CHANGED
@@ -66,7 +66,8 @@ exports and as `window.zx.*`.
66
66
  metric with optional delta, sparkline, and loading state), `AppIcon` (generic tile geometry;
67
67
  circular `zeyosAppIcon()` application presets and compact `moduleChip()` identities),
68
68
  `Aurora` (one- to four-colour ambient
69
- canvas light; shared material roles govern chrome and overlays), `Avatar`, `Panel` (header/footer action
69
+ canvas light; shared material roles govern chrome and overlays), `Avatar` (person presence, or an
70
+ agent's `activity` with an opt-in shared presence animation), `Panel` (header/footer action
70
71
  buttons), `MasterPanel`, `Tabbox`
71
72
  (`variant: 'divided'|'bracket'|'line'|'segmented'`), `NavigationBar`, `AppSidebar` (expanded and
72
73
  minimized vertical states plus horizontal rail layouts; sections; a modules layout), `ModuleBar`
@@ -76,6 +77,14 @@ exports and as `window.zx.*`.
76
77
  `Toolbar` (APG toolbar with overflow menu), `SplitView`, `Dock`
77
78
  (collapsible resizable pane stack; tab groups, regions, adopts a `Sheet`), `Stepper`,
78
79
  `Breadcrumb`, `emptyState()`.
80
+ - Agents: `AgentThread` (a conversation with agents as an APG feed: messages, streamed answers, run traces,
81
+ approvals, notices; plain-JSON items, the application owns transport), `BlockView`/`renderBlocks()` (an
82
+ answer drawn block by block as prose, appended to as it streams; model text is never HTML),
83
+ `RunTrace` (the steps a run took: tool calls with arguments and results, retries, hand-offs),
84
+ `ApprovalCard` (a request that holds a run: approve, edit, reject, typed confirmation),
85
+ `SourceList` (cited sources with a card each; nothing remote is loaded), `Composer` (the message
86
+ box: mentions, `/` commands, attachments, context chips, Send that becomes Stop), `RunStatus` (a
87
+ run's state, steps, working time, tokens, and a cost meter against a budget).
79
88
  - Core: `Component`, `h`/`__`/`icon`, `position`, `breakpoints`/`breakpointOf`/`matchBreakpoint`/`onBreakpoint` (named width bands, observed on an element or the window), `Http`/`zeyosService`, i18n, date utils, `defineElements` (declarative `<zx-*>` custom elements).
80
89
  - Helpers: `formatNumber`/`formatCurrency`/`formatPercent`/`formatFileSize`/`formatRelativeTime` (locale-aware, cached `Intl`), `debounce`/`throttle`, `groupBy`/`sortBy`/`uniqueBy`, `escapeRegExp`/`highlightMatch`, `storage()` (namespaced JSON, degrades to memory), `toCsv`/`downloadBlob`/`copyToClipboard`, `truncate()`/`isTruncated()` (line clamp with the full value on hover).
81
90
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@zeyos/zx",
3
- "version": "5.5.0",
3
+ "version": "5.6.0",
4
4
  "description": "Dependency-free JavaScript implementation of the Xenon Design System.",
5
5
  "type": "module",
6
6
  "license": "MIT",