@zeyos/zx 5.7.0 → 5.8.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 (330) hide show
  1. package/CHANGELOG.md +330 -0
  2. package/README.md +47 -9
  3. package/dist/types/components/activity-item/activity-item.d.ts +14 -3
  4. package/dist/types/components/agent-avatar/agent-avatar.d.ts +165 -0
  5. package/dist/types/components/agent-avatar/agent-face.d.ts +93 -0
  6. package/dist/types/components/agent-thread/ag-ui.d.ts +21 -9
  7. package/dist/types/components/agent-thread/agent-thread.d.ts +26 -0
  8. package/dist/types/components/agent-thread/ui-message-stream.d.ts +3 -1
  9. package/dist/types/components/approval-card/approval-card.d.ts +31 -2
  10. package/dist/types/components/aurora/aurora.d.ts +31 -5
  11. package/dist/types/components/calendar/calendar.d.ts +39 -26
  12. package/dist/types/components/chart/chart.d.ts +250 -20
  13. package/dist/types/components/chart/color.d.ts +66 -0
  14. package/dist/types/components/chart/svg-adapter.d.ts +103 -0
  15. package/dist/types/components/chart/svg-geometry.d.ts +203 -0
  16. package/dist/types/components/check-button/check-button.d.ts +1 -4
  17. package/dist/types/components/checklist/checklist.d.ts +48 -5
  18. package/dist/types/components/code-editor/code-editor.d.ts +55 -1
  19. package/dist/types/components/composer/composer.d.ts +41 -6
  20. package/dist/types/components/context-menu/context-menu.d.ts +36 -8
  21. package/dist/types/components/copy/copy-button.d.ts +6 -0
  22. package/dist/types/components/copy/copy-input.d.ts +1 -0
  23. package/dist/types/components/date-picker/date-picker.d.ts +14 -0
  24. package/dist/types/components/date-picker/time-picker.d.ts +26 -17
  25. package/dist/types/components/datebox/datebox.d.ts +8 -4
  26. package/dist/types/components/dialog/dialog.d.ts +15 -4
  27. package/dist/types/components/empty-state/empty-state.d.ts +10 -1
  28. package/dist/types/components/field/field.d.ts +4 -2
  29. package/dist/types/components/form/form.d.ts +2 -1
  30. package/dist/types/components/kanban-view/kanban-card.d.ts +7 -0
  31. package/dist/types/components/kanban-view/kanban-view.d.ts +15 -3
  32. package/dist/types/components/launcher/launcher.d.ts +26 -0
  33. package/dist/types/components/master-panel/master-panel.d.ts +9 -4
  34. package/dist/types/components/menu-button/menu-button.d.ts +29 -5
  35. package/dist/types/components/message/message.d.ts +308 -5
  36. package/dist/types/components/modal/modal.d.ts +45 -8
  37. package/dist/types/components/modal/native-dialog.d.ts +40 -0
  38. package/dist/types/components/module-bar/module-bar.d.ts +9 -2
  39. package/dist/types/components/multi-value-editor/multi-value-editor.d.ts +5 -4
  40. package/dist/types/components/number-field/number-field.d.ts +31 -1
  41. package/dist/types/components/pagination/pagination.d.ts +341 -19
  42. package/dist/types/components/run-status/run-status.d.ts +26 -0
  43. package/dist/types/components/run-trace/run-trace.d.ts +10 -6
  44. package/dist/types/components/search/search.d.ts +16 -4
  45. package/dist/types/components/select/select.d.ts +19 -1
  46. package/dist/types/components/sheet/sheet.d.ts +20 -6
  47. package/dist/types/components/slider/slider.d.ts +2 -1
  48. package/dist/types/components/stat-tile/stat-tile.d.ts +20 -3
  49. package/dist/types/components/stepper/stepper.d.ts +17 -4
  50. package/dist/types/components/surface/catalog.d.ts +61 -17
  51. package/dist/types/components/surface/surface.d.ts +6 -4
  52. package/dist/types/components/table/table.d.ts +207 -5
  53. package/dist/types/components/table/window.d.ts +25 -1
  54. package/dist/types/components/toggle/toggle.d.ts +38 -6
  55. package/dist/types/components/tooltip/tooltip.d.ts +5 -4
  56. package/dist/types/components/tree/tree.d.ts +43 -6
  57. package/dist/types/components/truncate/truncate.d.ts +4 -2
  58. package/dist/types/components/value-list/value-list.d.ts +9 -2
  59. package/dist/types/core/date.d.ts +2 -1
  60. package/dist/types/core/dom.d.ts +14 -0
  61. package/dist/types/core/drag-axis.d.ts +10 -5
  62. package/dist/types/core/export.d.ts +2 -2
  63. package/dist/types/core/format.d.ts +3 -1
  64. package/dist/types/core/icons.d.ts +36 -3
  65. package/dist/types/core/keyboard.d.ts +7 -3
  66. package/dist/types/core/messages.d.ts +3 -0
  67. package/dist/types/core/storage.d.ts +4 -3
  68. package/dist/types/core/util.d.ts +3 -1
  69. package/dist/types/elements/define.d.ts +5 -2
  70. package/dist/types/index.d.ts +6 -4
  71. package/dist/types/internal/agent-model.d.ts +99 -0
  72. package/dist/types/internal/app-rail.d.ts +37 -2
  73. package/dist/types/internal/collections.d.ts +18 -0
  74. package/dist/types/internal/menu-items.d.ts +27 -0
  75. package/dist/types/internal/overlay-content.d.ts +23 -0
  76. package/dist/types/internal/presence-loop.d.ts +5 -2
  77. package/dist/types/locales/index.d.ts +3 -0
  78. package/dist/types/zeyos/calendar.d.ts +43 -7
  79. package/dist/types/zeyos/connect.d.ts +4 -0
  80. package/dist/types/zeyos/form.d.ts +13 -5
  81. package/dist/types/zeyos/select.d.ts +5 -2
  82. package/dist/types/zeyos/table.d.ts +16 -8
  83. package/dist/types/zeyos/view.d.ts +2 -1
  84. package/dist/zx-zeyos.esm.js +3161 -515
  85. package/dist/zx-zeyos.esm.min.js +4 -4
  86. package/dist/zx.core.css +4 -0
  87. package/dist/zx.core.min.css +1 -1
  88. package/dist/zx.css +970 -57
  89. package/dist/zx.esm.js +6405 -2249
  90. package/dist/zx.esm.min.js +26 -26
  91. package/dist/zx.global.js +6405 -2249
  92. package/dist/zx.global.min.js +26 -26
  93. package/dist/zx.layered.css +972 -57
  94. package/dist/zx.layered.min.css +1 -1
  95. package/dist/zx.min.css +1 -1
  96. package/docs/agent-catalog.json +159 -1
  97. package/docs/agent-surfaces.md +21 -21
  98. package/docs/api.json +3154 -518
  99. package/docs/components/account-menu.md +24 -0
  100. package/docs/components/activity-item.md +23 -0
  101. package/docs/components/activity-list.md +28 -0
  102. package/docs/components/agent-avatar.md +59 -0
  103. package/docs/components/agent-thread.md +275 -0
  104. package/docs/components/app-icon.md +36 -0
  105. package/docs/components/app-sidebar.md +92 -0
  106. package/docs/components/approval-card.md +71 -0
  107. package/docs/components/aurora.md +34 -0
  108. package/docs/components/avatar.md +37 -0
  109. package/docs/components/badge.md +36 -0
  110. package/docs/components/block-view.md +34 -0
  111. package/docs/components/breadcrumb.md +20 -0
  112. package/docs/components/button.md +23 -0
  113. package/docs/components/calendar.md +68 -0
  114. package/docs/components/card-view.md +73 -0
  115. package/docs/components/card.md +25 -0
  116. package/docs/components/chart.md +109 -0
  117. package/docs/components/check-button.md +16 -0
  118. package/docs/components/checklist.md +19 -0
  119. package/docs/components/code-editor.md +38 -0
  120. package/docs/components/composer.md +107 -0
  121. package/docs/components/context-menu.md +32 -0
  122. package/docs/components/copy.md +37 -0
  123. package/docs/components/data-filter.md +16 -0
  124. package/docs/components/date-picker.md +31 -0
  125. package/docs/components/date-range.md +21 -0
  126. package/docs/components/datebox.md +31 -0
  127. package/docs/components/dialog.md +25 -0
  128. package/docs/components/dock.md +57 -0
  129. package/docs/components/dropdown.md +39 -0
  130. package/docs/components/elements.md +63 -0
  131. package/docs/components/empty-state.md +17 -0
  132. package/docs/components/entity-ref.md +26 -0
  133. package/docs/components/field-upload.md +18 -0
  134. package/docs/components/file-item.md +27 -0
  135. package/docs/components/file-list.md +23 -0
  136. package/docs/components/filter-panel.md +45 -0
  137. package/docs/components/filter.md +47 -0
  138. package/docs/components/finder.md +25 -0
  139. package/docs/components/form-widgets.md +42 -0
  140. package/docs/components/form.md +80 -0
  141. package/docs/components/grid.md +26 -0
  142. package/docs/components/groupbox.md +11 -0
  143. package/docs/components/helpers.md +359 -0
  144. package/docs/components/icons.md +87 -0
  145. package/docs/components/index.md +99 -0
  146. package/docs/components/kanban-view.md +42 -0
  147. package/docs/components/kbd.md +23 -0
  148. package/docs/components/kernel.md +41 -0
  149. package/docs/components/launcher.md +66 -0
  150. package/docs/components/layout.md +33 -0
  151. package/docs/components/list-toolbar.md +38 -0
  152. package/docs/components/loading.md +48 -0
  153. package/docs/components/menu-button.md +47 -0
  154. package/docs/components/message.md +76 -0
  155. package/docs/components/modal.md +27 -0
  156. package/docs/components/module-bar.md +71 -0
  157. package/docs/components/multi-value-editor.md +16 -0
  158. package/docs/components/navigation-bar.md +22 -0
  159. package/docs/components/number-field.md +34 -0
  160. package/docs/components/pagination.md +73 -0
  161. package/docs/components/panel.md +28 -0
  162. package/docs/components/prompt-starters.md +40 -0
  163. package/docs/components/prose.md +38 -0
  164. package/docs/components/questionnaire.md +115 -0
  165. package/docs/components/rating.md +19 -0
  166. package/docs/components/run-status.md +50 -0
  167. package/docs/components/run-trace.md +72 -0
  168. package/docs/components/search.md +11 -0
  169. package/docs/components/select.md +129 -0
  170. package/docs/components/sheet-stack.md +39 -0
  171. package/docs/components/sheet.md +77 -0
  172. package/docs/components/skeleton.md +27 -0
  173. package/docs/components/slider.md +29 -0
  174. package/docs/components/sort-control.md +21 -0
  175. package/docs/components/source-list.md +30 -0
  176. package/docs/components/split-view.md +12 -0
  177. package/docs/components/stat-tile.md +49 -0
  178. package/docs/components/stepper.md +27 -0
  179. package/docs/components/surface.md +152 -0
  180. package/docs/components/tabbox.md +33 -0
  181. package/docs/components/table-view.md +43 -0
  182. package/docs/components/table.md +232 -0
  183. package/docs/components/tag-picker.md +39 -0
  184. package/docs/components/timebox.md +16 -0
  185. package/docs/components/toggle.md +21 -0
  186. package/docs/components/tokens.md +82 -0
  187. package/docs/components/toolbar.md +26 -0
  188. package/docs/components/tooltip.md +16 -0
  189. package/docs/components/tree.md +48 -0
  190. package/docs/components/truncate.md +21 -0
  191. package/docs/components/value-list.md +14 -0
  192. package/docs/components/view-settings.md +56 -0
  193. package/docs/components/workspace-switcher.md +42 -0
  194. package/docs/components/zeyos.md +196 -0
  195. package/docs/llms-small.txt +299 -0
  196. package/docs/llms.md +725 -109
  197. package/docs/llms.txt +46 -19
  198. package/package.json +9 -4
  199. package/src/components/activity-item/activity-item.js +21 -2
  200. package/src/components/agent-avatar/agent-avatar.css +195 -0
  201. package/src/components/agent-avatar/agent-avatar.js +333 -0
  202. package/src/components/agent-avatar/agent-face.js +292 -0
  203. package/src/components/agent-thread/ag-ui.js +44 -11
  204. package/src/components/agent-thread/agent-thread.js +103 -11
  205. package/src/components/agent-thread/ui-message-stream.js +3 -1
  206. package/src/components/app-rail/app-rail.css +5 -0
  207. package/src/components/app-sidebar/app-sidebar.css +3 -0
  208. package/src/components/app-sidebar/app-sidebar.js +4 -3
  209. package/src/components/approval-card/approval-card.css +6 -0
  210. package/src/components/approval-card/approval-card.js +55 -7
  211. package/src/components/aurora/aurora.css +149 -14
  212. package/src/components/aurora/aurora.js +49 -6
  213. package/src/components/button/button.css +24 -11
  214. package/src/components/calendar/calendar.css +6 -2
  215. package/src/components/calendar/calendar.js +127 -47
  216. package/src/components/card-view/card-view.js +5 -6
  217. package/src/components/chart/chart.css +159 -1
  218. package/src/components/chart/chart.js +450 -62
  219. package/src/components/chart/color.js +297 -0
  220. package/src/components/chart/svg-adapter.js +576 -0
  221. package/src/components/chart/svg-geometry.js +323 -0
  222. package/src/components/check-button/check-button.js +3 -18
  223. package/src/components/checklist/checklist.css +9 -1
  224. package/src/components/checklist/checklist.js +105 -20
  225. package/src/components/checklist/field-adapter.js +6 -12
  226. package/src/components/code-editor/code-editor.css +33 -0
  227. package/src/components/code-editor/code-editor.js +97 -8
  228. package/src/components/code-editor/field-adapter.js +3 -0
  229. package/src/components/composer/composer.css +3 -0
  230. package/src/components/composer/composer.js +100 -22
  231. package/src/components/context-menu/context-menu.js +41 -5
  232. package/src/components/copy/copy-button.js +9 -1
  233. package/src/components/copy/copy-input.js +5 -0
  234. package/src/components/data-filter/filter-core.js +0 -1
  235. package/src/components/date-picker/date-picker.css +8 -0
  236. package/src/components/date-picker/date-picker.js +47 -8
  237. package/src/components/date-picker/date-range-picker.js +1 -1
  238. package/src/components/date-picker/month-picker.js +19 -3
  239. package/src/components/date-picker/time-picker.js +54 -19
  240. package/src/components/datebox/date-range-box.js +7 -3
  241. package/src/components/datebox/datebox.js +32 -6
  242. package/src/components/dialog/dialog.css +6 -0
  243. package/src/components/dialog/dialog.js +24 -33
  244. package/src/components/dropdown/dropdown.js +1 -18
  245. package/src/components/empty-state/empty-state.js +21 -2
  246. package/src/components/field/field.js +19 -3
  247. package/src/components/fieldset/fieldset.js +3 -1
  248. package/src/components/filter/filter.js +9 -0
  249. package/src/components/form/form.js +19 -2
  250. package/src/components/kanban-view/kanban-card.js +15 -2
  251. package/src/components/kanban-view/kanban-view.css +21 -0
  252. package/src/components/kanban-view/kanban-view.js +29 -16
  253. package/src/components/launcher/launcher.css +14 -0
  254. package/src/components/launcher/launcher.js +54 -9
  255. package/src/components/master-panel/master-panel.js +24 -22
  256. package/src/components/menu-button/menu-button.js +26 -4
  257. package/src/components/message/message.css +228 -29
  258. package/src/components/message/message.js +664 -30
  259. package/src/components/modal/modal.js +129 -30
  260. package/src/components/modal/native-dialog.js +91 -0
  261. package/src/components/module-bar/module-bar.css +3 -0
  262. package/src/components/module-bar/module-bar.js +17 -4
  263. package/src/components/multi-value-editor/multi-value-editor.css +7 -2
  264. package/src/components/multi-value-editor/multi-value-editor.js +3 -2
  265. package/src/components/navigation-bar/navigation-bar.js +13 -1
  266. package/src/components/number-field/field-adapter.js +3 -0
  267. package/src/components/number-field/number-field.js +70 -16
  268. package/src/components/pagination/pagination.css +26 -2
  269. package/src/components/pagination/pagination.js +551 -65
  270. package/src/components/prose/prose.js +7 -1
  271. package/src/components/rating/field-adapter.js +3 -0
  272. package/src/components/run-status/run-status.js +43 -3
  273. package/src/components/run-trace/run-trace.js +15 -7
  274. package/src/components/search/search.js +3 -18
  275. package/src/components/select/field-adapter.js +8 -1
  276. package/src/components/select/select.js +68 -13
  277. package/src/components/sheet/sheet.js +39 -13
  278. package/src/components/slider/field-adapter.js +3 -0
  279. package/src/components/slider/slider.js +4 -6
  280. package/src/components/stat-tile/stat-tile.js +24 -9
  281. package/src/components/stepper/stepper.css +15 -0
  282. package/src/components/stepper/stepper.js +34 -2
  283. package/src/components/surface/catalog.js +185 -28
  284. package/src/components/surface/surface.js +10 -5
  285. package/src/components/tabbox/tabbox.js +13 -1
  286. package/src/components/table/table.css +160 -2
  287. package/src/components/table/table.js +479 -52
  288. package/src/components/table/window.js +46 -4
  289. package/src/components/table-view/table-view.js +1 -10
  290. package/src/components/tag-picker/field-adapter.js +3 -0
  291. package/src/components/tag-picker/tag-picker.js +2 -0
  292. package/src/components/timebox/field-adapter.js +3 -0
  293. package/src/components/toggle/toggle.js +51 -27
  294. package/src/components/tooltip/tooltip.js +21 -14
  295. package/src/components/tree/tree.js +87 -14
  296. package/src/components/truncate/truncate.js +21 -5
  297. package/src/components/value-list/value-list.js +37 -9
  298. package/src/components/view-settings/view-settings.js +1 -5
  299. package/src/core/component.js +34 -2
  300. package/src/core/date.js +5 -4
  301. package/src/core/dom.js +45 -2
  302. package/src/core/drag-axis.js +24 -7
  303. package/src/core/export.js +4 -4
  304. package/src/core/fontawesome.js +34 -3
  305. package/src/core/format.js +3 -1
  306. package/src/core/http.js +23 -11
  307. package/src/core/icons.js +60 -8
  308. package/src/core/keyboard.js +83 -9
  309. package/src/core/messages.js +3 -0
  310. package/src/core/position.js +4 -3
  311. package/src/core/storage.js +80 -31
  312. package/src/core/util.js +16 -5
  313. package/src/elements/define.js +82 -47
  314. package/src/elements/kit.js +46 -35
  315. package/src/index.js +8 -4
  316. package/src/internal/agent-model.js +152 -0
  317. package/src/internal/app-rail.js +53 -2
  318. package/src/internal/collections.js +25 -0
  319. package/src/internal/menu-items.js +59 -0
  320. package/src/internal/overlay-content.js +35 -0
  321. package/src/internal/presence-loop.js +61 -14
  322. package/src/locales/de.js +3 -0
  323. package/src/zeyos/calendar.js +81 -19
  324. package/src/zeyos/connect.js +5 -1
  325. package/src/zeyos/form.js +29 -10
  326. package/src/zeyos/select.js +36 -12
  327. package/src/zeyos/table.js +43 -11
  328. package/src/zeyos/view.js +2 -1
  329. package/styles/tokens/semantic.css +7 -1
  330. package/styles/zx.css +1 -0
@@ -0,0 +1,333 @@
1
+ // @ts-check
2
+ import { Component } from '../../core/component.js';
3
+ import { h, restoreTarget, snapshotTarget } from '../../core/dom.js';
4
+ import { ACTIVITY, AGENT_MESSAGES, normalizeActivity } from '../../internal/agent-model.js';
5
+ import { normalizePhase, presencePhase, trackPresence } from '../../internal/presence-loop.js';
6
+ import { AGENT_PRESET_PX, agentFace, agentTraits } from './agent-face.js';
7
+
8
+ export { AGENT_BODIES, AGENT_EYES, agentFace, agentTraits } from './agent-face.js';
9
+
10
+ /** @typedef {import('./agent-face.js').AgentBody} AgentBody */
11
+ /** @typedef {import('./agent-face.js').AgentEyes} AgentEyes */
12
+ /** @typedef {import('./agent-face.js').AgentTraits} AgentTraits */
13
+ /** @typedef {import('./agent-face.js').AgentShape} AgentShape */
14
+ /** @typedef {import('../avatar/avatar.js').AvatarTone} AvatarTone */
15
+ /** @typedef {import('../../internal/agent-model.js').AgentActivity} AgentActivity */
16
+ /** @typedef {'flat'|'soft'} AgentMaterial */
17
+
18
+ /**
19
+ * @typedef {Object} AgentAvatarOptions
20
+ * @property {string|null} [seed=null] The agent's stable identity — an id. Every trait is derived
21
+ * from it, so renaming an agent does not change its face. `null` uses `name`.
22
+ * @property {string} [name=''] The agent's name; the seed when `seed` is null.
23
+ * @property {AvatarTone|null} [tone=null] Colour from the tone palette; `null` derives it from the
24
+ * seed with `avatarTone()`, so the face matches an initials tile keyed the same way.
25
+ * @property {AgentBody|null} [body=null] The silhouette, instead of the derived one: one of the
26
+ * fourteen in {@link AGENT_BODIES}.
27
+ * @property {AgentEyes|null} [eyes=null] The eye shape, instead of the derived one.
28
+ * @property {0|1|2|null} [spacing=null] How far apart the eyes sit — narrow, middle, wide —
29
+ * instead of the derived spacing. With `tone`, `body` and `eyes` it gives back a look kept from
30
+ * {@link AgentAvatar#getTraits}.
31
+ * @property {AgentMaterial} [material='flat'] How the body is painted. `flat` is the tone's solid
32
+ * fill; `soft` adds a quiet vertical ramp — a touch lighter at the top, deeper at the foot, the plain
33
+ * tone across the eyes — from 28px up. Below 28px, when offline, in print and in forced colours a
34
+ * soft body is drawn flat.
35
+ * @property {string|number} [size='md'] Preset — `sm` 24px, `md` 32px, `lg` 40px at the default
36
+ * spacing unit — or a pixel size. Small sizes draw less: no pupils below 20px, larger eyes at 24px
37
+ * and below.
38
+ * @property {string|null} [label=null] Accessible label; null makes the avatar decorative.
39
+ * @property {AgentActivity|null} [activity=null] What the agent is doing. The eyes take the
40
+ * activity's expression, the activity dot shows it, and its word joins the accessible name.
41
+ * @property {string|null} [activityLabel=null] The activity's word, when the default is not the one
42
+ * to show.
43
+ * @property {boolean} [indicator=true] Whether to draw the activity dot. Without it, show the
44
+ * activity's word nearby: the expression alone is a weaker signal.
45
+ * @property {boolean} [animate=false] Moves the avatar with its activity in the shared presence loop
46
+ * (as Avatar does) and lets its eyes blink, drift and scan. Motion is never the only signal and
47
+ * stops under reduced motion. While it is on, the root's `transform` belongs to the loop.
48
+ * @property {number|null} [phase=null] Where in its activity's cycle the avatar moves, as a fraction
49
+ * from 0 up to 1. `null` derives one from the seed.
50
+ * @property {Record<string, string>|Record<string, Record<string, string>>} [msg] Localized
51
+ * messages: the activity words, `agent.activity.<activity>`.
52
+ */
53
+
54
+ const SVG_NS = 'http://www.w3.org/2000/svg';
55
+
56
+ /** The values `set()` accepts. */
57
+ const SETTABLE = Object.freeze(['seed', 'name', 'tone', 'body', 'eyes', 'spacing', 'material', 'size', 'label',
58
+ 'activity', 'activityLabel', 'indicator', 'animate', 'phase']);
59
+
60
+ /** How long one blink cycle takes, in seconds; the phase offsets the eyes within it. */
61
+ const BLINK_PERIOD = 5.2;
62
+
63
+ /** The smallest rendered size a soft body is drawn at; below it the ramp is too small to read. */
64
+ const SOFT_MIN_PX = 28;
65
+
66
+ /**
67
+ * The soft ramp's stops, top to bottom: offset and the part that colours it in the stylesheet.
68
+ * The light stop sits above the eye row and the plain tone across it, so white eyes keep the
69
+ * contrast they have on the flat fill.
70
+ * @type {ReadonlyArray<readonly [number, string]>}
71
+ */
72
+ const SOFT_STOPS = Object.freeze([[0, 'stop-lit'], [0.3, 'stop-base'], [0.5, 'stop-base'], [1, 'stop-shade']]);
73
+
74
+ /**
75
+ * A generated face for an agent without a picture: a coloured geometric silhouette with eyes that
76
+ * take the agent's activity, deterministic from the agent's seed.
77
+ * @extends {Component<AgentAvatarOptions>}
78
+ */
79
+ export class AgentAvatar extends Component {
80
+ static cssName = 'agent-avatar';
81
+
82
+ /** @type {Readonly<AgentAvatarOptions>} */
83
+ static defaults = {
84
+ seed: null,
85
+ name: '',
86
+ tone: null,
87
+ body: null,
88
+ eyes: null,
89
+ spacing: null,
90
+ material: 'flat',
91
+ size: 'md',
92
+ label: null,
93
+ activity: null,
94
+ activityLabel: null,
95
+ indicator: true,
96
+ animate: false,
97
+ phase: null,
98
+ msg: AGENT_MESSAGES
99
+ };
100
+
101
+ /** @returns {HTMLElement} */
102
+ render() {
103
+ this._createdRoot = this.el === null;
104
+ const root = /** @type {HTMLElement} */ (this.el ?? h('span'));
105
+ this.el = root;
106
+ this._original = this._createdRoot ? null : snapshotTarget(root);
107
+ /** @type {Record<string, any>} */
108
+ this._state = {};
109
+ for (const key of SETTABLE) this._state[key] = this.options[key] ?? AgentAvatar.defaults[key];
110
+ /** @type {AgentTraits|null} */
111
+ this._traits = null;
112
+ /** A document-unique id for the soft ramp, so two avatars never share a paint server. */
113
+ this._paintId = `zx-agent-avatar-soft-${uniqueSuffix()}`;
114
+ this._destroyed = false;
115
+ /** @type {import('../../internal/presence-loop.js').PresenceHandle|null} */
116
+ this._presence = null;
117
+
118
+ const face = document.createElementNS(SVG_NS, 'svg');
119
+ face.setAttribute('class', 'zx-agent-avatar__face');
120
+ face.setAttribute('viewBox', '0 0 64 64');
121
+ face.setAttribute('aria-hidden', 'true');
122
+ face.setAttribute('focusable', 'false');
123
+ this.refs.face = face;
124
+ const dot = h('span', { ref: 'activity', class: 'zx-agent-avatar__activity', ariaHidden: 'true', hidden: true });
125
+ root.replaceChildren(face, dot);
126
+ this._sync();
127
+ return root;
128
+ }
129
+
130
+ /**
131
+ * Replaces identity and presentation values: any option but `msg`.
132
+ * @param {Partial<AgentAvatarOptions>} values New values.
133
+ * @returns {this}
134
+ */
135
+ set(values = {}) {
136
+ if (!values || typeof values !== 'object') return this;
137
+ for (const key of SETTABLE) {
138
+ if (Object.hasOwn(values, key)) this._state[key] = values[key];
139
+ }
140
+ this._sync();
141
+ return this;
142
+ }
143
+
144
+ /**
145
+ * Sets what the agent is doing and, optionally, the word for it. `null` clears the activity.
146
+ * @param {AgentActivity|null} activity
147
+ * @param {string|null} [label=null] The word, when the default is not the one to show.
148
+ * @returns {this}
149
+ */
150
+ setActivity(activity, label = null) {
151
+ this._state.activity = activity;
152
+ this._state.activityLabel = label;
153
+ this._sync();
154
+ return this;
155
+ }
156
+
157
+ /**
158
+ * What the agent is doing.
159
+ * @returns {AgentActivity|null} The activity, or null without one.
160
+ */
161
+ getActivity() {
162
+ return normalizeActivity(this._state.activity);
163
+ }
164
+
165
+ /**
166
+ * The localized word for the current activity — `activityLabel` when set — or null without an
167
+ * activity. A host that draws the avatar inside a control of its own adds it to that control's
168
+ * name, as AppSidebar and ModuleBar do.
169
+ * @returns {string|null}
170
+ */
171
+ getActivityWord() {
172
+ return this._activityWord();
173
+ }
174
+
175
+ /**
176
+ * The traits the face is drawn from, so an application can store them — to keep a look across a
177
+ * rename, or to settle a collision between two agents once — and give them back as the `tone`,
178
+ * `body`, `eyes` and `spacing` options.
179
+ * @returns {AgentTraits}
180
+ */
181
+ getTraits() {
182
+ return { ...(this._traits ?? this._resolveTraits()) };
183
+ }
184
+
185
+ /**
186
+ * Leaves the presence loop and restores an enhanced target or removes an owned root. Safe to call
187
+ * more than once: only the first call restores, so a target its owner has reused is left alone.
188
+ * @returns {void}
189
+ */
190
+ destroy() {
191
+ if (this._destroyed) return;
192
+ this._destroyed = true;
193
+ this._presence?.untrack();
194
+ this._presence = null;
195
+ super.destroy();
196
+ if (!this._createdRoot) restoreTarget(this.el, this._original);
197
+ }
198
+
199
+ /** @returns {AgentTraits} */
200
+ _resolveTraits() {
201
+ const { seed, name, tone, body, eyes, spacing } = this._state;
202
+ const key = seed == null || String(seed).trim() === '' ? name : seed;
203
+ return agentTraits(key, { tone, body, eyes, spacing });
204
+ }
205
+
206
+ /** @returns {number} The rendered size the level of detail is picked for. */
207
+ _px() {
208
+ const size = this._state.size;
209
+ if (typeof size === 'number' && Number.isFinite(size)) return Math.max(1, size);
210
+ return AGENT_PRESET_PX[/** @type {'sm'|'md'|'lg'} */ (size)] ?? AGENT_PRESET_PX.md;
211
+ }
212
+
213
+ /** @returns {void} */
214
+ _sync() {
215
+ const root = /** @type {HTMLElement} */ (this.el);
216
+ const { size } = this._state;
217
+ const traits = this._resolveTraits();
218
+ this._traits = traits;
219
+ const activity = normalizeActivity(this._state.activity);
220
+ root.dataset.tone = traits.tone;
221
+ root.dataset.size = typeof size === 'number' ? 'custom' : (['sm', 'md', 'lg'].includes(size) ? size : 'md');
222
+ if (typeof size === 'number' && Number.isFinite(size)) {
223
+ root.style.setProperty('--zx-agent-avatar-size', `${Math.max(1, size)}px`);
224
+ } else {
225
+ root.style.removeProperty('--zx-agent-avatar-size');
226
+ }
227
+ if (activity) root.dataset.activity = activity;
228
+ else delete root.dataset.activity;
229
+
230
+ const face = /** @type {SVGSVGElement} */ (this.refs.face);
231
+ const soft = this._state.material === 'soft' && this._px() >= SOFT_MIN_PX && activity !== 'offline';
232
+ face.replaceChildren(...agentFace(traits, activity, this._px()).map(drawShape));
233
+ if (soft) {
234
+ face.prepend(drawShape({
235
+ tag: 'defs', part: null, attrs: {}, children: [{
236
+ tag: 'linearGradient', part: null,
237
+ attrs: { id: this._paintId, gradientUnits: 'userSpaceOnUse', x1: 0, y1: 4, x2: 0, y2: 60 },
238
+ children: SOFT_STOPS.map(([offset, part]) => ({ tag: 'stop', part, attrs: { offset } }))
239
+ }]
240
+ }));
241
+ root.dataset.material = 'soft';
242
+ root.style.setProperty('--zx-agent-avatar-paint', `url("#${this._paintId}") var(--zx-agent-avatar-solid)`);
243
+ } else {
244
+ root.dataset.material = 'flat';
245
+ root.style.removeProperty('--zx-agent-avatar-paint');
246
+ }
247
+
248
+ const dot = /** @type {HTMLElement} */ (this.refs.activity);
249
+ const word = this._activityWord();
250
+ dot.hidden = !activity || !this._state.indicator;
251
+ if (word) dot.setAttribute('title', word);
252
+ else dot.removeAttribute('title');
253
+
254
+ const label = this._state.label;
255
+ if (label) {
256
+ root.setAttribute('role', 'img');
257
+ root.setAttribute('aria-label', [String(label), word].filter(Boolean).join(', '));
258
+ root.removeAttribute('aria-hidden');
259
+ } else {
260
+ root.removeAttribute('role');
261
+ root.removeAttribute('aria-label');
262
+ root.setAttribute('aria-hidden', 'true');
263
+ }
264
+ this._syncMotion(activity);
265
+ }
266
+
267
+ /** The word for the current activity, or null without one. @returns {string|null} */
268
+ _activityWord() {
269
+ const activity = normalizeActivity(this._state.activity);
270
+ if (!activity) return null;
271
+ return this._state.activityLabel ? String(this._state.activityLabel) : this.msg(ACTIVITY[activity].key);
272
+ }
273
+
274
+ /**
275
+ * Joins, follows, or leaves the shared presence loop, and offsets the eyes' own animations.
276
+ * @param {AgentActivity|null} activity
277
+ * @returns {void}
278
+ */
279
+ _syncMotion(activity) {
280
+ const root = /** @type {HTMLElement} */ (this.el);
281
+ const animate = Boolean(this._state.animate) && activity !== null;
282
+ const phase = normalizePhase(this._state.phase) ?? presencePhase(this._seedKey());
283
+ if (animate) {
284
+ root.dataset.animate = '';
285
+ root.style.setProperty('--zx-agent-avatar-delay', `${-(phase * BLINK_PERIOD).toFixed(2)}s`);
286
+ } else {
287
+ delete root.dataset.animate;
288
+ root.style.removeProperty('--zx-agent-avatar-delay');
289
+ }
290
+ if (!animate) {
291
+ this._presence?.untrack();
292
+ this._presence = null;
293
+ } else if (this._presence) {
294
+ this._presence.set(activity, { phase });
295
+ } else {
296
+ this._presence = trackPresence(root, activity, { phase });
297
+ }
298
+ }
299
+
300
+ /** @returns {string} */
301
+ _seedKey() {
302
+ const { seed, name } = this._state;
303
+ return seed == null || String(seed).trim() === '' ? String(name ?? '') : String(seed);
304
+ }
305
+ }
306
+
307
+ /**
308
+ * Builds one shape of {@link agentFace} as an SVG element.
309
+ * @param {AgentShape} shape
310
+ * @returns {SVGElement}
311
+ */
312
+ function drawShape(shape) {
313
+ const element = /** @type {SVGElement} */ (document.createElementNS(SVG_NS, shape.tag));
314
+ if (shape.part) element.setAttribute('class', `zx-agent-avatar__${shape.part}`);
315
+ for (const [name, value] of Object.entries(shape.attrs)) element.setAttribute(name, String(value));
316
+ if (shape.children) element.append(...shape.children.map(drawShape));
317
+ return element;
318
+ }
319
+
320
+ /**
321
+ * A random suffix for an element id: a whole UUID where the platform has one (secure contexts), else
322
+ * 128 bits from `getRandomValues`, else four `Math.random()` draws — never a short value that two
323
+ * of many avatars on one page could share.
324
+ * @returns {string}
325
+ */
326
+ function uniqueSuffix() {
327
+ const crypto = globalThis.crypto;
328
+ if (typeof crypto?.randomUUID === 'function') return crypto.randomUUID();
329
+ if (typeof crypto?.getRandomValues === 'function') {
330
+ return Array.from(crypto.getRandomValues(new Uint32Array(4)), (part) => part.toString(36)).join('-');
331
+ }
332
+ return Array.from({ length: 4 }, () => Math.random().toString(36).slice(2, 10)).join('-');
333
+ }
@@ -0,0 +1,292 @@
1
+ // @ts-check
2
+ /**
3
+ * The pure half of AgentAvatar: which face a seed gets ({@link agentTraits}) and the shapes that
4
+ * draw it in one activity at one size ({@link agentFace}). Nothing here touches the DOM, so the
5
+ * same seed gives the same face on a server, in a test, and on every screen.
6
+ *
7
+ * Every trait table below is contract, order and length included: the hash picks an index modulo
8
+ * the table's length, so reordering, inserting or even appending an entry re-faces agents that
9
+ * have already been drawn.
10
+ */
11
+ import { AVATAR_TONES, avatarTone } from '../avatar/avatar.js';
12
+
13
+ /** @typedef {import('../avatar/avatar.js').AvatarTone} AvatarTone */
14
+ /** @typedef {import('../../internal/agent-model.js').AgentActivity} AgentActivity */
15
+
16
+ /**
17
+ * @typedef {'circle'|'squircle'|'hexagon'|'triangle'|'drop'|'pill'|'clover'|'dome'
18
+ * |'wedge'|'pentagon'|'trapezoid'|'cross'|'diamond'|'octagon'} AgentBody
19
+ */
20
+ /** @typedef {'round'|'oval'|'square'} AgentEyes */
21
+
22
+ /**
23
+ * The traits a seed resolves to.
24
+ * @typedef {Object} AgentTraits
25
+ * @property {AvatarTone} tone
26
+ * @property {AgentBody} body
27
+ * @property {AgentEyes} eyes
28
+ * @property {0|1|2} spacing How far apart the eyes sit: narrow, middle, wide.
29
+ */
30
+
31
+ /**
32
+ * Single traits to fix instead of deriving them. An unknown value is ignored.
33
+ * @typedef {Object} AgentTraitOverrides
34
+ * @property {AvatarTone|null} [tone]
35
+ * @property {AgentBody|null} [body]
36
+ * @property {AgentEyes|null} [eyes]
37
+ * @property {0|1|2|null} [spacing] How far apart the eyes sit, as `AgentAvatar.getTraits()` reports it.
38
+ */
39
+
40
+ /**
41
+ * One shape to draw: an SVG element name, the part it plays (styled as `.zx-agent-avatar__<part>`),
42
+ * its attributes, and, for a group, its children.
43
+ * @typedef {Object} AgentShape
44
+ * @property {string} tag
45
+ * @property {string|null} part
46
+ * @property {Record<string, string|number>} attrs
47
+ * @property {AgentShape[]} [children]
48
+ */
49
+
50
+ /**
51
+ * The silhouettes, in hash order.
52
+ * @type {ReadonlyArray<AgentBody>}
53
+ */
54
+ export const AGENT_BODIES = Object.freeze(['circle', 'squircle', 'hexagon', 'triangle', 'drop', 'pill', 'clover', 'dome',
55
+ 'wedge', 'pentagon', 'trapezoid', 'cross', 'diamond', 'octagon']);
56
+
57
+ /** The eye shapes, in hash order. @type {ReadonlyArray<AgentEyes>} */
58
+ export const AGENT_EYES = Object.freeze(['round', 'oval', 'square']);
59
+
60
+ /** The rendered pixel size each preset stands for when picking the level of detail. */
61
+ export const AGENT_PRESET_PX = Object.freeze({ sm: 24, md: 32, lg: 40 });
62
+
63
+ /** The eye spacings, as factors of a body's middle spacing. */
64
+ const SPREAD = Object.freeze([0.85, 1, 1.15]);
65
+
66
+ /**
67
+ * Where the eyes sit on each silhouette (centre height, half-spacing at the middle spacing) and the
68
+ * shapes that draw it. Polygons round their corners with a stroke the colour of the fill.
69
+ * @type {Readonly<Record<AgentBody, {y: number, gap: number, shapes: AgentShape[]}>>}
70
+ */
71
+ const BODIES = Object.freeze({
72
+ circle: { y: 30, gap: 11, shapes: [shape('circle', 'body', { cx: 32, cy: 32, r: 28 })] },
73
+ squircle: { y: 29, gap: 11, shapes: [shape('rect', 'body', { x: 5, y: 5, width: 54, height: 54, rx: 20 })] },
74
+ hexagon: { y: 30, gap: 10, shapes: [shape('polygon', 'body', { points: '32,6 55,19 55,45 32,58 9,45 9,19', 'stroke-width': 8, 'stroke-linejoin': 'round' })] },
75
+ triangle: { y: 40, gap: 8, shapes: [shape('polygon', 'body', { points: '32,9 57,53 7,53', 'stroke-width': 9, 'stroke-linejoin': 'round' })] },
76
+ drop: { y: 32, gap: 11, shapes: [shape('path', 'body', { d: 'M32 5H59V32A27 27 0 1 1 32 5Z' })] },
77
+ pill: { y: 30, gap: 11, shapes: [shape('rect', 'body', { x: 4, y: 15, width: 56, height: 34, rx: 17, transform: 'rotate(-20 32 32)' })] },
78
+ clover: { y: 30, gap: 11, shapes: [
79
+ shape('circle', 'body', { cx: 21, cy: 21, r: 15 }), shape('circle', 'body', { cx: 43, cy: 21, r: 15 }),
80
+ shape('circle', 'body', { cx: 21, cy: 43, r: 15 }), shape('circle', 'body', { cx: 43, cy: 43, r: 15 }),
81
+ shape('rect', 'body', { x: 16, y: 16, width: 32, height: 32 })
82
+ ] },
83
+ dome: { y: 36, gap: 11, shapes: [shape('path', 'body', { d: 'M5 52V40A27 27 0 0 1 59 40V52Q59 56 55 56H9Q5 56 5 52Z' })] },
84
+ wedge: { y: 23, gap: 9.5, shapes: [shape('polygon', 'body', { points: '7,11 57,11 32,55', 'stroke-width': 9, 'stroke-linejoin': 'round' })] },
85
+ pentagon: { y: 31, gap: 10, shapes: [shape('polygon', 'body', { points: '32,7 57,25 48,55 16,55 7,25', 'stroke-width': 8, 'stroke-linejoin': 'round' })] },
86
+ trapezoid: { y: 31, gap: 10, shapes: [shape('polygon', 'body', { points: '17,11 47,11 58,53 6,53', 'stroke-width': 8, 'stroke-linejoin': 'round' })] },
87
+ cross: { y: 31, gap: 11, shapes: [shape('polygon', 'body', { points: '22,7 42,7 42,21 57,21 57,43 42,43 42,57 22,57 22,43 7,43 7,21 22,21', 'stroke-width': 6, 'stroke-linejoin': 'round' })] },
88
+ diamond: { y: 30, gap: 9.5, shapes: [shape('polygon', 'body', { points: '32,5 59,32 32,59 5,32', 'stroke-width': 8, 'stroke-linejoin': 'round' })] },
89
+ octagon: { y: 30, gap: 11, shapes: [shape('polygon', 'body', { points: '22,5 42,5 59,22 59,42 42,59 22,59 5,42 5,22', 'stroke-width': 6, 'stroke-linejoin': 'round' })] }
90
+ });
91
+
92
+ /**
93
+ * Resolves the face a seed gets. The tone is `avatarTone(seed)`, so an agent's initials Avatar and
94
+ * its face agree when they share a key; every other trait comes from FNV-1a over the same
95
+ * normalised key plus a per-trait salt, mixed, so traits are independent of the tone and of each
96
+ * other.
97
+ * @param {unknown} seed The agent's stable identity — an id, or its name.
98
+ * @param {AgentTraitOverrides} [overrides={}] Traits to fix instead of deriving them.
99
+ * @returns {AgentTraits}
100
+ */
101
+ export function agentTraits(seed, overrides = {}) {
102
+ const key = normaliseKey(seed);
103
+ const tone = AVATAR_TONES.includes(/** @type {AvatarTone} */ (overrides.tone))
104
+ ? /** @type {AvatarTone} */ (overrides.tone) : avatarTone(key);
105
+ const body = AGENT_BODIES.includes(/** @type {AgentBody} */ (overrides.body))
106
+ ? /** @type {AgentBody} */ (overrides.body) : pick(key, 'body', AGENT_BODIES);
107
+ const eyes = AGENT_EYES.includes(/** @type {AgentEyes} */ (overrides.eyes))
108
+ ? /** @type {AgentEyes} */ (overrides.eyes) : pick(key, 'eyes', AGENT_EYES);
109
+ const spacing = [0, 1, 2].includes(/** @type {number} */ (overrides.spacing))
110
+ ? /** @type {0|1|2} */ (overrides.spacing) : /** @type {0|1|2} */ (pick(key, 'spacing', [0, 1, 2]));
111
+ return { tone, body, eyes, spacing };
112
+ }
113
+
114
+ /**
115
+ * The shapes that draw a face in one activity at one rendered size, in a 64-unit view box, as
116
+ * plain data. The level of detail follows `px`: the pupils go below 20px, and at 24px and below the
117
+ * eyes grow and sit at the middle spacing.
118
+ * @param {AgentTraits} traits From {@link agentTraits}.
119
+ * @param {AgentActivity|string|null} [activity=null] What the agent is doing; unknown is idle.
120
+ * @param {number} [px=32] The rendered size in CSS pixels.
121
+ * @returns {AgentShape[]}
122
+ */
123
+ export function agentFace(traits, activity = null, px = 32) {
124
+ const state = activity ?? 'idle';
125
+ const small = px <= 24;
126
+ const body = BODIES[traits.body] ?? BODIES.circle;
127
+ const width = small ? 15 : 13;
128
+ const gap = body.gap * (small ? 0.95 : (SPREAD[traits.spacing] ?? 1));
129
+ return [
130
+ shape('g', 'shape', {}, body.shapes.map(copyShape)),
131
+ eyePair({
132
+ xs: [32 - gap, 32 + gap], y: body.y, w: width, h: traits.eyes === 'oval' ? width * 1.25 : width,
133
+ shape: traits.eyes, pupils: px >= 20, heavy: small
134
+ }, state)
135
+ ];
136
+ }
137
+
138
+ /**
139
+ * Two eyes with the activity's static expression. The `look` group is what drifts and scans, an
140
+ * `eye` group is what blinks, and a `gaze` group moves a pupil.
141
+ * @param {{xs: number[], y: number, w: number, h: number, shape: AgentEyes, pupils: boolean, heavy: boolean}} eye
142
+ * @param {string} activity
143
+ * @returns {AgentShape}
144
+ */
145
+ function eyePair(eye, activity) {
146
+ const { xs, y } = eye;
147
+ let { w, h } = eye;
148
+ /** @type {AgentShape[]} */
149
+ const eyes = [];
150
+ if (activity === 'blocked') {
151
+ const bar = eye.heavy ? 4 : 3.2;
152
+ for (const x of xs) eyes.push(shape('rect', 'sclera', { x: r(x - w * 0.6), y: r(y - bar / 2), width: r(w * 1.2), height: bar, rx: 1.4 }));
153
+ return shape('g', 'eyes', {}, [shape('g', 'look', {}, eyes)]);
154
+ }
155
+ if (activity === 'offline') {
156
+ for (const x of xs) {
157
+ eyes.push(shape('path', 'line', {
158
+ d: `M${r(x - w * 0.55)} ${r(y)}Q${r(x)} ${r(y + h * 0.45)} ${r(x + w * 0.55)} ${r(y)}`,
159
+ 'stroke-width': eye.heavy ? 3 : 2.2
160
+ }));
161
+ }
162
+ return shape('g', 'eyes', {}, [shape('g', 'look', {}, eyes)]);
163
+ }
164
+ let dx = 0; let dy = 0; let px = 0; let py = 0;
165
+ // The eye takes its final size first, so a pupil's offset is measured on the eye it sits in.
166
+ if (activity === 'working') h *= 0.62;
167
+ if (activity === 'needs-you') { w *= 1.2; h *= 1.2; }
168
+ if (activity === 'thinking') {
169
+ if (eye.pupils) { px = w * 0.2; py = -h * 0.22; } else { dx = 2.5; dy = -3; }
170
+ }
171
+ if (activity === 'working') {
172
+ if (eye.pupils) py = h * 0.2; else dy = 2;
173
+ }
174
+ xs.forEach((x, index) => {
175
+ const scale = activity === 'thinking' && !eye.pupils && index === 1 ? 0.85 : 1;
176
+ const ew = w * scale;
177
+ const eh = h * scale;
178
+ const cx = x + dx;
179
+ const cy = y + dy;
180
+ /** @type {AgentShape[]} */
181
+ const parts = [eyeShape(eye.shape, cx, cy, ew, eh)];
182
+ if (eye.pupils) {
183
+ const radius = Math.min(ew, eh) * (activity === 'needs-you' ? 0.36 : 0.3);
184
+ const [ox, oy] = fitPupil(eye.shape, ew, eh, radius, px, py);
185
+ parts.push(shape('g', 'gaze', {}, [shape('circle', 'pupil', { cx: r(cx + ox), cy: r(cy + oy), r: r(radius) })]));
186
+ }
187
+ eyes.push(shape('g', 'eye', {}, parts));
188
+ });
189
+ return shape('g', 'eyes', {}, [shape('g', 'look', {}, eyes)]);
190
+ }
191
+
192
+ /** The least clearance a pupil keeps from the edge of its eye, in view-box units. */
193
+ const PUPIL_CLEARANCE = 0.3;
194
+
195
+ /**
196
+ * A pupil's offset from the centre of its eye, drawn back toward the centre as far as it takes to
197
+ * keep the whole pupil inside the eye white that {@link eyeShape} draws, however the activity
198
+ * points it.
199
+ * @param {AgentEyes} name @param {number} w @param {number} h The eye as drawn.
200
+ * @param {number} radius The pupil's radius.
201
+ * @param {number} ox @param {number} oy The offset the activity asks for.
202
+ * @returns {[number, number]}
203
+ */
204
+ function fitPupil(name, w, h, radius, ox, oy) {
205
+ const a = name === 'oval' ? w * 0.42 : w / 2;
206
+ const b = h / 2;
207
+ const reach = radius + PUPIL_CLEARANCE;
208
+ /** @param {number} k @returns {boolean} Whether the pupil fits at `k` times the offset. */
209
+ const fits = (k) => {
210
+ const x = ox * k;
211
+ const y = oy * k;
212
+ // A square eye's corners round less than a pupil does, so its box is the limit.
213
+ if (name === 'square') return Math.abs(x) + reach <= a && Math.abs(y) + reach <= b;
214
+ for (let step = 0; step < 32; step += 1) {
215
+ const angle = (step * Math.PI) / 16;
216
+ const px = x + reach * Math.cos(angle);
217
+ const py = y + reach * Math.sin(angle);
218
+ if ((px / a) ** 2 + (py / b) ** 2 > 1) return false;
219
+ }
220
+ return true;
221
+ };
222
+ if (fits(1)) return [ox, oy];
223
+ let low = 0;
224
+ let high = 1;
225
+ for (let round = 0; round < 12; round += 1) {
226
+ const mid = (low + high) / 2;
227
+ if (fits(mid)) low = mid;
228
+ else high = mid;
229
+ }
230
+ return [ox * low, oy * low];
231
+ }
232
+
233
+ /**
234
+ * One open eye.
235
+ * @param {AgentEyes} name @param {number} x @param {number} y @param {number} w @param {number} h
236
+ * @returns {AgentShape}
237
+ */
238
+ function eyeShape(name, x, y, w, h) {
239
+ if (name === 'square') {
240
+ return shape('rect', 'sclera', { x: r(x - w / 2), y: r(y - h / 2), width: r(w), height: r(h), rx: r(Math.min(w, h) * 0.22) });
241
+ }
242
+ if (name === 'oval') return shape('ellipse', 'sclera', { cx: r(x), cy: r(y), rx: r(w * 0.42), ry: r(h / 2) });
243
+ return shape('ellipse', 'sclera', { cx: r(x), cy: r(y), rx: r(w / 2), ry: r(h / 2) });
244
+ }
245
+
246
+ /**
247
+ * @param {string} tag @param {string|null} part @param {Record<string, string|number>} attrs
248
+ * @param {AgentShape[]} [children]
249
+ * @returns {AgentShape}
250
+ */
251
+ function shape(tag, part, attrs, children) {
252
+ return children ? { tag, part, attrs, children } : { tag, part, attrs };
253
+ }
254
+
255
+ /** A copy, so a caller changing the drawing never changes the table. @param {AgentShape} source @returns {AgentShape} */
256
+ function copyShape(source) {
257
+ return shape(source.tag, source.part, { ...source.attrs }, source.children?.map(copyShape));
258
+ }
259
+
260
+ /** Rounds to two decimals so the drawing is stable text. @param {number} value @returns {number} */
261
+ function r(value) {
262
+ return Math.round(value * 100) / 100;
263
+ }
264
+
265
+ /** The key every trait hashes: trimmed, NFC-normalised, lower-cased — as `avatarTone()` does. @param {unknown} seed @returns {string} */
266
+ function normaliseKey(seed) {
267
+ return String(seed ?? '').trim().normalize('NFC').toLowerCase();
268
+ }
269
+
270
+ /**
271
+ * Picks from a table by FNV-1a over the key and a salt, finished with the MurmurHash3 mixer. FNV-1a
272
+ * alone will not do: its low bits depend only on the input's low bits, so a salted hash taken modulo
273
+ * a small table is a fixed function of the unsalted one — the tone — and every violet agent would get
274
+ * the same body. The mixer spreads every bit of the hash into the low ones.
275
+ * @template T
276
+ * @param {string} key @param {string} salt @param {ReadonlyArray<T>} table
277
+ * @returns {T}
278
+ */
279
+ function pick(key, salt, table) {
280
+ const text = `${key}\u0000${salt}`;
281
+ let hash = 0x811c9dc5;
282
+ for (let index = 0; index < text.length; index += 1) {
283
+ hash ^= text.charCodeAt(index);
284
+ hash = Math.imul(hash, 0x01000193);
285
+ }
286
+ hash ^= hash >>> 16;
287
+ hash = Math.imul(hash, 0x85ebca6b);
288
+ hash ^= hash >>> 13;
289
+ hash = Math.imul(hash, 0xc2b2ae35);
290
+ hash ^= hash >>> 16;
291
+ return table[(hash >>> 0) % table.length];
292
+ }