@bevel-software/platform-core-frontend 0.25.2 → 0.27.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 (193) hide show
  1. package/package.json +2 -2
  2. package/src/core/CoreAppShell.tsx +87 -25
  3. package/src/core/ProductName.tsx +49 -0
  4. package/src/core/__tests__/ShellRoutes.test.tsx +22 -0
  5. package/src/core/__tests__/core-contributions.test.ts +16 -0
  6. package/src/core/core-contributions.ts +17 -0
  7. package/src/core/registry.ts +51 -1
  8. package/src/index.css +23 -5
  9. package/src/index.ts +5 -0
  10. package/src/modules/access/__tests__/ManageAccessDialog.proposal.test.tsx +1 -1
  11. package/src/modules/access/components/ManageAccessDialog.tsx +1 -1
  12. package/src/modules/admin/__tests__/RolesCorruptedBanner.test.tsx +70 -0
  13. package/src/modules/admin/components/RolesCorruptedBanner.tsx +9 -4
  14. package/src/modules/auth/components/LoginScreen.tsx +4 -1
  15. package/src/modules/auth/services/account.api.ts +28 -1
  16. package/src/modules/auth/services/sso.ts +1 -2
  17. package/src/modules/change-requests/__tests__/ChangeRequestDialog.sync-banner.test.tsx +176 -0
  18. package/src/modules/change-requests/__tests__/ChangeRequestDialog.unreadable.test.tsx +68 -0
  19. package/src/modules/change-requests/__tests__/ChangeRequestLink.test.tsx +182 -0
  20. package/src/modules/change-requests/__tests__/FileChangeBoxes.test.tsx +1 -1
  21. package/src/modules/change-requests/__tests__/readFileOnBranch.test.ts +79 -0
  22. package/src/modules/change-requests/components/ChangeBox.tsx +6 -1
  23. package/src/modules/change-requests/components/ChangeRequestDialog.tsx +45 -15
  24. package/src/modules/change-requests/components/ChangeRequestLink.tsx +151 -0
  25. package/src/modules/change-requests/components/CrFileTree.tsx +2 -1
  26. package/src/modules/change-requests/components/FileChangeBoxes.tsx +4 -2
  27. package/src/modules/change-requests/hooks/useApplyChangeRequest.ts +6 -3
  28. package/src/modules/change-requests/services/change-requests.api.ts +15 -2
  29. package/src/modules/change-requests/utils/readFailure.ts +22 -0
  30. package/src/modules/embed/__tests__/EmbedLinkPage.test.tsx +74 -0
  31. package/src/modules/embed/__tests__/EmbedView.test.tsx +473 -0
  32. package/src/modules/embed/__tests__/embed-config.test.ts +128 -0
  33. package/src/modules/embed/__tests__/embed-host.test.ts +111 -0
  34. package/src/modules/embed/__tests__/mcp-app-view.test.ts +295 -0
  35. package/src/modules/embed/__tests__/mount.test.tsx +157 -0
  36. package/src/modules/embed/components/EmbedLinkPage.tsx +109 -0
  37. package/src/modules/embed/components/EmbedView.tsx +545 -0
  38. package/src/modules/embed/embed-config.ts +132 -0
  39. package/src/modules/embed/embed-host.ts +120 -0
  40. package/src/modules/embed/mount.tsx +80 -0
  41. package/src/modules/embed/services/embed-token.ts +22 -0
  42. package/src/modules/embed/services/embed.api.ts +158 -0
  43. package/src/modules/git/__tests__/BranchSwitcher.test.tsx +202 -4
  44. package/src/modules/git/__tests__/GitSyncFailedBanner.test.tsx +59 -1
  45. package/src/modules/git/__tests__/PullNeededBanner.test.tsx +39 -22
  46. package/src/modules/git/__tests__/useAutoPullUpdates.test.tsx +7 -2
  47. package/src/modules/git/branch-delete-menu-item.tsx +24 -0
  48. package/src/modules/git/components/BranchSwitcher.tsx +29 -5
  49. package/src/modules/git/components/GitSyncFailedBanner.tsx +53 -15
  50. package/src/modules/git/components/HistoryVersionPreview.tsx +5 -3
  51. package/src/modules/git/components/PullNeededBanner.tsx +15 -49
  52. package/src/modules/git/hooks/useAutoPullUpdates.ts +9 -5
  53. package/src/modules/git/index.ts +15 -0
  54. package/src/modules/git/services/__tests__/error-messages.test.ts +67 -0
  55. package/src/modules/git/services/__tests__/pull-failure.test.ts +36 -0
  56. package/src/modules/git/services/error-messages.ts +58 -1
  57. package/src/modules/git/services/pull-failure.ts +68 -0
  58. package/src/modules/git/state/branch-delete-confirm.ts +46 -0
  59. package/src/modules/layout/__tests__/HeaderAlignment.test.tsx +1 -0
  60. package/src/modules/layout/__tests__/breakpoints.test.ts +7 -1
  61. package/src/modules/layout/breakpoints.ts +8 -0
  62. package/src/modules/library/__tests__/PluginExtras.test.tsx +9 -9
  63. package/src/modules/library/__tests__/PluginPage.test.tsx +8 -1
  64. package/src/modules/library/__tests__/SkillsTree.test.tsx +13 -4
  65. package/src/modules/library/__tests__/ToolPage.test.tsx +53 -0
  66. package/src/modules/library/components/LibraryPage.tsx +22 -0
  67. package/src/modules/library/components/PluginExtras.tsx +23 -6
  68. package/src/modules/library/components/PluginPage.tsx +6 -1
  69. package/src/modules/library/components/tool-page/ToolPage.tsx +45 -1
  70. package/src/modules/library/routes/LibraryRoutes.tsx +8 -7
  71. package/src/modules/library/services/plugins.api.ts +4 -1
  72. package/src/modules/library/services/tools.api.ts +27 -0
  73. package/src/modules/library/state/plugins-revision.ts +28 -0
  74. package/src/modules/onboarding/__tests__/agent-connection-api.test.ts +55 -0
  75. package/src/modules/onboarding/__tests__/creator-welcome.test.tsx +87 -82
  76. package/src/modules/onboarding/__tests__/first-page-prompt.test.ts +109 -0
  77. package/src/modules/onboarding/__tests__/get-started-column.test.tsx +1001 -0
  78. package/src/modules/onboarding/__tests__/invite-dialog.test.tsx +392 -0
  79. package/src/modules/onboarding/__tests__/onboarding.test.tsx +226 -193
  80. package/src/modules/onboarding/__tests__/starter-pack-card.test.tsx +136 -0
  81. package/src/modules/onboarding/components/CreatorWelcomePage.tsx +7 -11
  82. package/src/modules/onboarding/components/EmailChipsInput.tsx +138 -0
  83. package/src/modules/onboarding/components/GetStartedColumn.tsx +651 -0
  84. package/src/modules/onboarding/components/InviteButton.tsx +35 -0
  85. package/src/modules/onboarding/components/InviteDialog.tsx +424 -0
  86. package/src/modules/onboarding/components/RootLanding.tsx +8 -24
  87. package/src/modules/onboarding/components/StarterPackCard.tsx +98 -0
  88. package/src/modules/onboarding/components/WelcomePage.tsx +65 -154
  89. package/src/modules/onboarding/first-page-prompt.ts +89 -0
  90. package/src/modules/onboarding/invite-emails.ts +175 -0
  91. package/src/modules/onboarding/services/agent-connection.api.ts +53 -0
  92. package/src/modules/onboarding/services/starter-packs.api.ts +83 -0
  93. package/src/modules/onboarding/state/agent-connection.ts +167 -0
  94. package/src/modules/onboarding/state/invite-dialog.context.ts +32 -0
  95. package/src/modules/onboarding/state/invite-dialog.tsx +31 -0
  96. package/src/modules/onboarding/state/onboarding.ts +133 -59
  97. package/src/modules/onboarding/state/starter-packs.ts +169 -0
  98. package/src/modules/settings/settings-nav-items.tsx +8 -3
  99. package/src/modules/setup/__tests__/setup.first-run-storage.test.tsx +389 -0
  100. package/src/modules/setup/__tests__/setup.github.test.tsx +5 -5
  101. package/src/modules/setup/__tests__/setup.kept-draft.test.tsx +1 -1
  102. package/src/modules/setup/__tests__/setup.repository-change.test.tsx +1 -1
  103. package/src/modules/setup/__tests__/setup.repository.test.tsx +21 -21
  104. package/src/modules/setup/__tests__/setup.test.tsx +65 -81
  105. package/src/modules/setup/__tests__/useConnectionProbe.test.tsx +123 -0
  106. package/src/modules/setup/components/FirstRunStorage.tsx +560 -0
  107. package/src/modules/setup/components/SetupGate.tsx +46 -1
  108. package/src/modules/setup/components/SetupScreen.tsx +92 -152
  109. package/src/modules/setup/hooks/useConnectionProbe.ts +93 -0
  110. package/src/modules/setup/services/setup.api.ts +3 -3
  111. package/src/modules/setup/utils/suggested-branch.ts +27 -0
  112. package/src/modules/toolbar/commands/__tests__/actions.test.tsx +210 -0
  113. package/src/modules/toolbar/commands/actions.tsx +324 -0
  114. package/src/modules/toolbar/commands/command-menu.ts +44 -0
  115. package/src/modules/toolbar/commands/useCommandActions.ts +69 -0
  116. package/src/modules/toolbar/commands/useCommandShortcuts.ts +121 -0
  117. package/src/modules/toolbar/components/AppSwitcher.tsx +106 -22
  118. package/src/modules/toolbar/components/ExternalAgentAccessPage.tsx +1 -1
  119. package/src/modules/toolbar/components/ProfileMenu.tsx +9 -4
  120. package/src/modules/toolbar/components/SearchPalette.tsx +540 -0
  121. package/src/modules/toolbar/components/Toolbar.tsx +10 -0
  122. package/src/modules/toolbar/components/__tests__/AppSwitcher.test.tsx +187 -54
  123. package/src/modules/toolbar/components/__tests__/ExternalAgentAccessPage.test.tsx +4 -4
  124. package/src/modules/toolbar/components/__tests__/ProfileMenu.test.tsx +64 -0
  125. package/src/modules/toolbar/components/__tests__/SearchPalette.test.tsx +832 -0
  126. package/src/modules/toolbar/components/__tests__/Toolbar.test.tsx +57 -2
  127. package/src/modules/toolbar/search/__tests__/rank.test.ts +93 -0
  128. package/src/modules/toolbar/search/__tests__/sources.test.ts +131 -0
  129. package/src/modules/toolbar/search/rank.ts +111 -0
  130. package/src/modules/toolbar/search/sources.ts +169 -0
  131. package/src/modules/workflow/hooks/useFileLock.ts +10 -7
  132. package/src/modules/workflow/services/__tests__/lock.api.test.ts +41 -0
  133. package/src/modules/workflow/services/lock.api.ts +17 -2
  134. package/src/modules/workspace/__tests__/useWorkspaceState.test.ts +49 -1
  135. package/src/modules/workspace/components/EditorTabs.tsx +39 -15
  136. package/src/modules/workspace/components/FileExplorer.tsx +39 -6
  137. package/src/modules/workspace/components/FilePaneCard.tsx +6 -2
  138. package/src/modules/workspace/components/FileRoute.tsx +12 -7
  139. package/src/modules/workspace/components/FileViewer.tsx +271 -74
  140. package/src/modules/workspace/components/KbPageHeader.tsx +13 -6
  141. package/src/modules/workspace/components/__tests__/EditorTabs.test.tsx +88 -21
  142. package/src/modules/workspace/components/__tests__/FileExplorer.test.tsx +101 -11
  143. package/src/modules/workspace/components/__tests__/FileRoute.test.tsx +23 -3
  144. package/src/modules/workspace/components/__tests__/FileViewer.test.tsx +330 -6
  145. package/src/modules/workspace/components/__tests__/KbPageHeader.test.tsx +17 -2
  146. package/src/modules/workspace/components/renderers/DocxRenderer.tsx +11 -16
  147. package/src/modules/workspace/components/renderers/DownloadFileButton.tsx +6 -0
  148. package/src/modules/workspace/components/renderers/EmailRenderer.tsx +23 -21
  149. package/src/modules/workspace/components/renderers/ImageRenderer.tsx +13 -29
  150. package/src/modules/workspace/components/renderers/KbMarkdownView.tsx +9 -2
  151. package/src/modules/workspace/components/renderers/MarkdownRenderer.tsx +8 -0
  152. package/src/modules/workspace/components/renderers/PdfRenderer.tsx +14 -19
  153. package/src/modules/workspace/components/renderers/PptxRenderer.tsx +11 -17
  154. package/src/modules/workspace/components/renderers/ToolRenderer.tsx +35 -7
  155. package/src/modules/workspace/components/renderers/XlsxRenderer.tsx +11 -17
  156. package/src/modules/workspace/components/renderers/__tests__/EmailRenderer.links.test.tsx +73 -0
  157. package/src/modules/workspace/components/renderers/__tests__/ToolRenderer.scaffold.test.tsx +64 -0
  158. package/src/modules/workspace/components/renderers/__tests__/ToolRenderer.surface.test.tsx +82 -0
  159. package/src/modules/workspace/components/renderers/__tests__/bridgeHarness.ts +99 -0
  160. package/src/modules/workspace/components/renderers/__tests__/htmlSandbox.test.ts +129 -35
  161. package/src/modules/workspace/components/renderers/__tests__/htmlViewsGuide.test.ts +149 -0
  162. package/src/modules/workspace/components/renderers/__tests__/kbMarkdownLinkPolicy.test.tsx +100 -0
  163. package/src/modules/workspace/components/renderers/htmlSandbox.ts +76 -20
  164. package/src/modules/workspace/components/renderers/index.ts +26 -0
  165. package/src/modules/workspace/components/renderers/kbMarkdownPipeline.tsx +51 -1
  166. package/src/modules/workspace/components/renderers/rendererRawRead.ts +53 -0
  167. package/src/modules/workspace/components/renderers/rendererSurface.ts +109 -0
  168. package/src/modules/workspace/components/renderers/rendererWorkspace.ts +8 -2
  169. package/src/modules/workspace/hooks/__tests__/useWorkspaceState.test.tsx +126 -21
  170. package/src/modules/workspace/hooks/useCreatePage.ts +116 -0
  171. package/src/modules/workspace/hooks/useWorkspaceImageResolver.ts +24 -7
  172. package/src/modules/workspace/hooks/useWorkspaceState.ts +42 -8
  173. package/src/modules/workspace/routing/__tests__/kb-routes.test.tsx +10 -0
  174. package/src/modules/workspace/routing/__tests__/md-links-parity.test.tsx +113 -0
  175. package/src/modules/workspace/routing/kb-routes.ts +66 -12
  176. package/src/modules/workspace/state/editable-page.ts +42 -0
  177. package/src/modules/workspace/state/workspace.context.ts +13 -4
  178. package/src/modules/workspace/utils/__tests__/display-file-name.test.ts +60 -0
  179. package/src/modules/workspace/utils/__tests__/fileTree.test.ts +75 -0
  180. package/src/modules/workspace/utils/__tests__/treeConfirm.test.ts +26 -14
  181. package/src/modules/workspace/utils/display-file-name.ts +102 -0
  182. package/src/modules/workspace/utils/fileTree.ts +49 -14
  183. package/src/modules/workspace/utils/treeConfirm.ts +22 -5
  184. package/src/shared/__tests__/no-builtin-confirm.test.ts +102 -0
  185. package/src/shared/components/ConfirmProvider.tsx +156 -0
  186. package/src/shared/components/Dialog.tsx +7 -0
  187. package/src/shared/components/__tests__/ConfirmProvider.test.tsx +198 -0
  188. package/src/shared/components/confirm-context.ts +94 -0
  189. package/src/shared/components/index.ts +3 -0
  190. package/src/shared/mcp/__tests__/connect-snippets.test.ts +2 -2
  191. package/src/shared/mcp/connect-snippets.ts +8 -5
  192. package/src/modules/onboarding/components/WelcomeRoute.tsx +0 -57
  193. package/src/modules/onboarding/welcome-state.ts +0 -36
@@ -1,4 +1,4 @@
1
- import { useEffect, useLayoutEffect, useRef, useState } from 'react';
1
+ import { useEffect, useRef, useState } from 'react';
2
2
  import { useNavigate } from 'react-router-dom';
3
3
  import { Check, Copy, X } from 'lucide-react';
4
4
  import { cn } from '../../../lib/utils';
@@ -9,29 +9,28 @@ import { copyToClipboard, COPY_FAILED_TOAST } from '../../library/utils/clipboar
9
9
  import { pathForLibraryFilter } from '../../library/routes/library-paths';
10
10
  import { useAppRegistry } from '../../../core/registry';
11
11
  import { displayFirstName } from '../../library/utils/personal-plugin';
12
- import { setSidebarCollapsed } from '../../layout/state/sidebar';
13
12
  import { ChatGptInstallLink, ClaudeInstallLink, mcpEndpointUrl } from '../../../shared/mcp';
14
13
  import { AGENT_CLIENTS, type AgentClient } from '../agent-clients';
15
14
  import { useOnboarding } from '../state/onboarding';
16
- import { useWelcomeRouteState } from '../welcome-state';
15
+ import { useAgentConnection } from '../state/agent-connection';
17
16
 
18
17
  /**
19
- * The welcome page — the first thing a new account sees, once.
18
+ * The welcome page: how to connect your agent.
20
19
  *
21
20
  * Three beats and nothing else (prototype `renderWelcome`): your name (so the
22
21
  * page is addressed, not broadcast), one sentence of what this place is, and
23
- * the single action the account still needs. It arrives in two movements —
24
- * the greeting, then everything else — and the client picker re-renders in
25
- * place, so neither ever replays as blinking.
22
+ * the single action the account still needs. The client picker re-renders in
23
+ * place.
26
24
  *
27
- * Mounting marks `welcomed`: the auto-redirect here happens on the FIRST
28
- * sign-in only. The page itself stays reachable forever — the sidebar pill
29
- * and a typed URL both land here — but the app never drags anyone back.
25
+ * Nobody is sent here: `/` lands on Knowledge (see `RootLanding`), so every
26
+ * arrival is a visit — no entrance to play, no sidebar to fold away, no
27
+ * carried link to honour. The page is reached from the sidebar pill, the Get
28
+ * set up list and by URL, and stays reachable after the onboarding is done.
30
29
  *
31
30
  * "Done" concludes; it does not copy. A button whose word and act disagree
32
31
  * teaches people not to read buttons — the copy lives ON the snippet block,
33
32
  * and "Go to your skills →" is the honest exit for someone who leaves
34
- * without connecting (it ends the redirect, never the pill).
33
+ * without connecting (it concludes nothing; the pill stays).
35
34
  */
36
35
  export function WelcomePage() {
37
36
  const { user } = useAuth();
@@ -40,115 +39,6 @@ export function WelcomePage() {
40
39
  const navigate = useNavigate();
41
40
  const [clientId, setClientId] = useState<AgentClient['id']>('claude');
42
41
 
43
- // Once, on arrival — this is what makes the welcome redirect one-time.
44
- const { markWelcomed } = onboarding;
45
- useEffect(() => {
46
- markWelcomed();
47
- // eslint-disable-next-line react-hooks/exhaustive-deps -- identity changes per render (bound closure); the act is idempotent per account
48
- }, []);
49
-
50
- /**
51
- * How you got here, and where you were going — read through the shared
52
- * parser, so this page and `WelcomeRoute` cannot drift apart about what an
53
- * arrival carries (see `welcome-state`).
54
- *
55
- * `greeting` is what everything ceremonial on this page hangs off.
56
- * `returnTo` is the deep link that survived the SSO round-trip, and it
57
- * retargets both exits: a welcome that concluded by discarding the page
58
- * someone was sent is a greeting that cost them the reason they came.
59
- */
60
- const { greeting, returnTo } = useWelcomeRouteState();
61
-
62
- /**
63
- * The entrance — and it belongs to the greeting alone.
64
- *
65
- * Being welcomed happens once. Opening the same page later from the pill is
66
- * a visit, and a 2.6s arrival every time you check your MCP snippet is a
67
- * page you learn to dread. So anyone who did not arrive by the sign-in
68
- * redirect starts ENTERED: no hold, no fade, the page simply exists.
69
- *
70
- * When it DOES play, it waits for a frame the browser actually paints. A CSS
71
- * animation runs on the document timeline, which advances in wall clock time
72
- * whether or not frames are being produced. This page mounts at the end of a
73
- * cold boot — the auth round trip, the router, the library shell — and if the
74
- * main thread is still busy when React inserts this DOM, the whole 2.2s can
75
- * elapse before the first paint. The animation does not look fast, it is
76
- * simply over by the time anyone sees it, and the page "just appears". No
77
- * timing value can be tuned out of that; the animation has to START on a
78
- * live frame.
79
- *
80
- * Two frames, not one: the first proves the browser is rendering again, the
81
- * second is the one the animation begins on. Until then the content is held
82
- * invisible, so the first painted state is the animation's own first state
83
- * rather than a flash of the finished page.
84
- *
85
- * Reduced motion also starts entered — the `motion-safe:` animations are
86
- * inert for them anyway, so a hold would be a blank page and nothing else.
87
- * `matchMedia` is optional-chained because jsdom has none.
88
- */
89
- const [entered, setEntered] = useState(
90
- () => !greeting || (window.matchMedia?.('(prefers-reduced-motion: reduce)').matches ?? false),
91
- );
92
- useEffect(() => {
93
- if (entered) return;
94
- let inner = 0;
95
- const outer = requestAnimationFrame(() => {
96
- inner = requestAnimationFrame(() => setEntered(true));
97
- });
98
- return () => {
99
- cancelAnimationFrame(outer);
100
- cancelAnimationFrame(inner);
101
- };
102
- // eslint-disable-next-line react-hooks/exhaustive-deps -- an arrival-time decision, settled at mount
103
- }, []);
104
- /**
105
- * An INLINE STYLE, not a `motion-safe:opacity-0` utility — and the reason is
106
- * scar tissue. Tailwind scans this package through a node_modules symlink
107
- * (`apps/web/src/index.css`), and a class first written mid-session is not
108
- * always compiled, so the hold silently did nothing and the page painted
109
- * fully formed. An entrance animation must not be hostage to whether the
110
- * stylesheet noticed a new class name.
111
- */
112
- const hold = entered ? undefined : ({ opacity: 0 } as const);
113
- /**
114
- * The animation classes go on ONLY for the greeting. `entered` alone is not
115
- * enough: a pill visit starts entered, so carrying the class would replay
116
- * the whole arrival on a page somebody deliberately navigated to.
117
- */
118
- const arriving = greeting && entered;
119
-
120
- /**
121
- * The nav gets out of the way for the greeting — and STAYS out.
122
- *
123
- * There is no restore, and that is the decision rather than an omission.
124
- * Putting it back on the way out meant Done handed you a page you did not
125
- * ask to have rearranged: you left a screen with no nav and arrived at one
126
- * where the nav had opened itself. Whether the sidebar is showing is a thing
127
- * you say with the toolbar toggle, and after the greeting it says whatever
128
- * it said last — collapsed, unless you opened it yourself while you were
129
- * here, in which case it stays open and this code never touches it again.
130
- *
131
- * Only for the greeting, so opening this page from the pill later never
132
- * rearranges the window around a page you deliberately navigated to.
133
- *
134
- * A LAYOUT effect, and that is the whole difference between "the nav is not
135
- * here" and "the nav flinched". `useEffect` runs after the browser paints,
136
- * so the first frame showed a full sidebar and the second began folding it
137
- * away — a flash of a thing you were never meant to see. Layout effects run
138
- * before paint: React re-renders synchronously, and the sidebar's width is
139
- * already zero in the only frame that is ever drawn. `instant` covers the
140
- * rest: there is nothing to transition from, and nobody gestured at it.
141
- *
142
- * The layout and this page mount in the same commit (`LibraryRoutes` — the
143
- * welcome route is a child of `LibraryLayout`, and neither is lazy), which
144
- * is what makes "before paint" mean before the sidebar's first paint too.
145
- */
146
- useLayoutEffect(() => {
147
- if (!greeting) return;
148
- setSidebarCollapsed(true, true);
149
- // eslint-disable-next-line react-hooks/exhaustive-deps -- an arrival-time decision: how you got here cannot change while you are here
150
- }, []);
151
-
152
42
  const client = AGENT_CLIENTS.find((c) => c.id === clientId) ?? AGENT_CLIENTS[0]!;
153
43
  // The deployment's own address, not the browser's — see `shared/mcp`.
154
44
  const mcpUrl = mcpEndpointUrl();
@@ -191,8 +81,7 @@ export function WelcomePage() {
191
81
 
192
82
  // Both exits land in the same place. Whether you connected an agent or
193
83
  // walked past it, where you want to be next is somewhere you can start —
194
- // by default your own shelf, not the whole company's catalog. A deep link
195
- // still outranks it: someone who followed a link is owed that link.
84
+ // by default your own shelf, not the whole company's catalog.
196
85
  //
197
86
  // `welcomeExit` lets a distribution move that destination, because WHERE a
198
87
  // new person should start is a property of the product. A deployment built
@@ -202,7 +91,31 @@ export function WelcomePage() {
202
91
  const { welcomeExit } = useAppRegistry();
203
92
  const defaultExit = { path: pathForLibraryFilter({ kind: 'ungrouped' }), label: 'Go to your skills' };
204
93
  const exit = welcomeExit ?? defaultExit;
205
- const exitTo = returnTo ?? exit.path;
94
+
95
+ /**
96
+ * The answer to "did it work?", without having to go and check.
97
+ *
98
+ * The server says so the moment an agent makes its first call — which
99
+ * every client does on connecting — through the `agent-connected` event
100
+ * this page listens for; it asks once on arrival, and again on a return to
101
+ * the tab, never on a timer. Connecting IS the onboarding, so it concludes
102
+ * it: the pill goes and the Get set up step ticks, without asking for Done
103
+ * as well. Once per visit — `markDone` drops its optimism again when the
104
+ * server refuses, and a refusal must not turn into a request on every
105
+ * render.
106
+ *
107
+ * Only while the onboarding is open: someone who finished it and came back
108
+ * to copy a snippet is waiting on nothing. A connection this session has
109
+ * already seen still shows.
110
+ */
111
+ const { showPill, markDone } = onboarding;
112
+ const agent = useAgentConnection({ enabled: showPill });
113
+ const concluded = useRef(false);
114
+ useEffect(() => {
115
+ if (!agent.connected || concluded.current) return;
116
+ concluded.current = true;
117
+ if (showPill) markDone();
118
+ }, [agent.connected, showPill, markDone]);
206
119
 
207
120
  /**
208
121
  * Conclude the onboarding and leave. The toast says where the setup went,
@@ -212,33 +125,13 @@ export function WelcomePage() {
212
125
  function done() {
213
126
  onboarding.markDone();
214
127
  toast('Done. Reopen the setup any time from your profile menu → External agent access.');
215
- navigate(exitTo);
128
+ navigate(exit.path);
216
129
  }
217
130
 
218
131
  return (
219
- /* Two beats, not one. The greeting arrives on its own and is allowed to be
220
- read; the rest of the page follows once it has landed. A single fade over
221
- everything made the name and the setup instructions one event, and the
222
- name is the point of the page. Both timings live in `index.css` — see
223
- the note there on why they are named rather than arbitrary values.
224
-
225
- On the ELEMENTS rather than the page, because the page re-renders every
226
- time the client picker changes: a CSS animation on a surviving element
227
- does not restart, so the beats play once, on arrival, and switching
228
- between Claude and Cursor never reads as blinking. `motion-safe:` means
229
- `prefers-reduced-motion` gets both beats at once, immediately — `both`
230
- fill is what keeps them visible when the animation never runs. */
231
132
  <div className="mx-auto mt-[11vh] max-w-[440px]">
232
- <h1
233
- className={cn(
234
- 'text-display font-bold',
235
- arriving && 'motion-safe:animate-onboarding-greeting',
236
- )}
237
- style={hold}
238
- >
239
- Welcome, {firstName}
240
- </h1>
241
- <div className={cn(arriving && 'motion-safe:animate-onboarding-body')} style={hold}>
133
+ <h1 className="text-display font-bold">Welcome, {firstName}</h1>
134
+ <div>
242
135
  <p className="mt-3 text-lede text-ink-muted">
243
136
  This is your company’s shared library of the skills, tools and knowledge your AI
244
137
  agents work from. Connect your agent once and access the skills and tools you need in
@@ -317,7 +210,27 @@ export function WelcomePage() {
317
210
  linger on the next option's snippet. */}
318
211
  <SnippetBlock key={client.id} value={snippet} copyLabel="Copy" className="mt-3.5" />
319
212
 
320
- <div className="mt-5 flex items-center gap-4">
213
+ {/* Quiet while it waits — a dot and a line, not a spinner demanding
214
+ attention while someone is busy in another window — and plain
215
+ about it when the agent arrives. Empty until the first answer is
216
+ in, so someone already connected never sees "Waiting" flash past.
217
+ The region exists from the start: a live region that appears
218
+ together with its text is often not announced at all. */}
219
+ <p role="status" aria-live="polite" className="mt-3.5 flex min-h-5 items-center gap-2 text-detail">
220
+ {agent.connected ? (
221
+ <>
222
+ <Check size={13} aria-hidden className="flex-none text-ok" />
223
+ <span className="text-ok">Connected. Your agent reached this knowledge base.</span>
224
+ </>
225
+ ) : agent.settled ? (
226
+ <>
227
+ <span aria-hidden className="size-1.5 flex-none rounded-full bg-wait-dot motion-safe:animate-pulse" />
228
+ <span className="text-ink-faint">Waiting for your agent…</span>
229
+ </>
230
+ ) : null}
231
+ </p>
232
+
233
+ <div className="mt-4 flex items-center gap-4">
321
234
  <Button
322
235
  variant="primary"
323
236
  onClick={done}
@@ -326,17 +239,15 @@ export function WelcomePage() {
326
239
  Done
327
240
  </Button>
328
241
  {/* The same destination Done goes to — one value drives both exits,
329
- so they cannot drift apart. Ordinarily that is wherever the
330
- deployment says a new person should start (core: your own shelf
331
- — "your skills" over "your library", since the library is the
332
- whole company's); when a deep link brought you here, both exits
333
- keep its promise instead, and the label says so. */}
242
+ so they cannot drift apart: wherever the deployment says a new
243
+ person should start (core: your own shelf — "your skills" over
244
+ "your library", since the library is the whole company's). */}
334
245
  <button
335
246
  type="button"
336
- onClick={() => navigate(exitTo)}
247
+ onClick={() => navigate(exit.path)}
337
248
  className="text-detail text-ink-faint transition-colors hover:text-ink"
338
249
  >
339
- {returnTo ? 'Continue to your link →' : `${exit.label} →`}
250
+ {exit.label} →
340
251
  </button>
341
252
  </div>
342
253
  </div>
@@ -0,0 +1,89 @@
1
+ /**
2
+ * The one-click first prompt behind "Write your first page": a request a
3
+ * connected agent can act on straight away, and the links that open it in a
4
+ * new chat already typed.
5
+ *
6
+ * Short on purpose. It travels in a URL, and a page about the company is the
7
+ * one every knowledge base needs and every new person can answer for — the
8
+ * agent asks for what it cannot find rather than inventing it.
9
+ */
10
+ export const FIRST_PAGE_PROMPT =
11
+ "Using our Hexis knowledge base, write a page in Knowledge about our company: what we do, who we work with, and our main products. Ask me for anything you don't know, then save it.";
12
+
13
+ /**
14
+ * The request for the team that answered "What does your team do?": its
15
+ * starter pack's own (`firstPagePrompt` — for Sales, "fill in the Customers
16
+ * page…"), else the generic one above. Trimmed: a pack writes it as a YAML
17
+ * block, which ends in a newline nobody wants in a URL.
18
+ */
19
+ export function firstPagePromptFor(pack: { firstPagePrompt: string } | null | undefined): string {
20
+ return pack?.firstPagePrompt.trim() || FIRST_PAGE_PROMPT;
21
+ }
22
+
23
+ /** A new Claude chat with `prompt` typed into it (claude.ai's `q` parameter prefills; the person still sends). */
24
+ export function claudePromptUrl(prompt: string): string {
25
+ return `https://claude.ai/new?q=${encodeURIComponent(prompt)}`;
26
+ }
27
+
28
+ /** The same for ChatGPT, whose `q` parameter prefills a new chat. */
29
+ export function chatGptPromptUrl(prompt: string): string {
30
+ return `https://chatgpt.com/?q=${encodeURIComponent(prompt)}`;
31
+ }
32
+
33
+ /**
34
+ * Which of the prompt's ways in leads, for the agent that connected.
35
+ *
36
+ * - `claude`: the claude.ai link. Only for a connection claude.ai or Claude
37
+ * Desktop made with the hosted address — a custom connector added there is
38
+ * on both, so a new chat at claude.ai can reach the knowledge base.
39
+ * - `chatgpt`: the chatgpt.com link, for ChatGPT's connector.
40
+ * - `copy`: the prompt itself, for everything else — Claude Code, Cursor,
41
+ * any agent on the local server, any connection key, a name we do not
42
+ * know. None of them can be opened from a link, and pointing someone at a
43
+ * web chat that cannot see their knowledge base is a dead end.
44
+ */
45
+ export type FirstPagePrimary = 'claude' | 'chatgpt' | 'copy';
46
+
47
+ export interface FirstPageRoute {
48
+ primary: FirstPagePrimary;
49
+ /**
50
+ * The agent as a person names it, for "Paste it into …": the part before
51
+ * the local server's " · local server on <machine>", and null when the
52
+ * server only knows it as an unnamed or unknown agent — or by a connection
53
+ * key's label, which names the key rather than the app holding it.
54
+ */
55
+ agentName: string | null;
56
+ }
57
+
58
+ /** The local server registers as "<agent> · local server on <machine>" (`hexis-mcp` `registrationName`). */
59
+ const LOCAL_SERVER_SUFFIX = /\s*·\s*local server on\b.*$/i;
60
+
61
+ /** What claude.ai and Claude Desktop call themselves, folded. "Claude Code" is deliberately absent. */
62
+ const CLAUDE_WEB_NAMES = new Set(['claude', 'claude.ai', 'claude-ai', 'claude ai', 'claude desktop', 'claude-desktop']);
63
+
64
+ /**
65
+ * Reads the connection answer's `client` into the step's leading action.
66
+ * Only an OAuth connection's (`kind: 'agent'`) name is the app's own: a
67
+ * connection key's label is whatever its owner typed, so a key called
68
+ * "ChatGPT CLI" says nothing about ChatGPT being able to use it, and a key —
69
+ * or an answer that does not say which it is — always leads with `copy`.
70
+ * Case-insensitive, and anything it does not recognise falls back to `copy`,
71
+ * which works with every agent.
72
+ */
73
+ export function firstPageRoute(
74
+ client: string | null | undefined,
75
+ kind: 'agent' | 'key' | null | undefined,
76
+ ): FirstPageRoute {
77
+ if (kind !== 'agent') return { primary: 'copy', agentName: null };
78
+ const raw = (client ?? '').trim();
79
+ const local = LOCAL_SERVER_SUFFIX.test(raw);
80
+ const name = raw.replace(LOCAL_SERVER_SUFFIX, '').trim();
81
+ const folded = name.toLowerCase();
82
+ const agentName = !name || /^(unnamed|unknown) agent$/i.test(name) ? null : name;
83
+ // A local-server connection lives in that app's config file, not in the
84
+ // web chat a link would open — even when the app is Claude Desktop.
85
+ if (local) return { primary: 'copy', agentName };
86
+ if (/\bchatgpt\b/.test(folded)) return { primary: 'chatgpt', agentName };
87
+ if (CLAUDE_WEB_NAMES.has(folded)) return { primary: 'claude', agentName };
88
+ return { primary: 'copy', agentName };
89
+ }
@@ -0,0 +1,175 @@
1
+ import { EMAIL_RE } from '../../lib/email';
2
+
3
+ /** Commas, semicolons and any whitespace separate; lower-cased, empty parts dropped. */
4
+ function tokens(text: string): string[] {
5
+ return text
6
+ .split(/[\s,;]+/)
7
+ .map((part) => part.trim().toLowerCase())
8
+ .filter(Boolean);
9
+ }
10
+
11
+ /**
12
+ * Split typed or pasted text into addresses. Commas, semicolons and any
13
+ * whitespace separate; a `Name <address>` entry — what a mail client puts on
14
+ * the clipboard when you copy a recipient list — contributes its address.
15
+ * Lower-cased, because the server treats addresses that way and a chip for
16
+ * `Juan@` beside one for `juan@` would be one person invited twice.
17
+ *
18
+ * A display name can hold the very separators the list uses: Outlook copies
19
+ * `Doe, Jane <jane@example.com>`, others quote it (`"Doe, Jane" <…>`). So a
20
+ * quoted name goes first, and the text before an angle-bracketed address is
21
+ * read as its name — only the parts of it that are addresses themselves (a
22
+ * bare one earlier in the list) survive. Text after the last bracketed entry
23
+ * names nothing, so it splits as typed, a mistyped address included, and
24
+ * shows as the invalid chip it is.
25
+ */
26
+ export function splitEmails(text: string): string[] {
27
+ const unquoted = text.replace(/"[^"]*"/g, ' ');
28
+ const out: string[] = [];
29
+ let rest = 0;
30
+ for (const entry of unquoted.matchAll(/<([^<>]*)>/g)) {
31
+ out.push(...tokens(unquoted.slice(rest, entry.index)).filter((part) => part.includes('@')));
32
+ out.push(...tokens(entry[1] ?? ''));
33
+ rest = entry.index + entry[0].length;
34
+ }
35
+ out.push(...tokens(unquoted.slice(rest)));
36
+ return out;
37
+ }
38
+
39
+ export function isValidEmail(value: string): boolean {
40
+ return EMAIL_RE.test(value);
41
+ }
42
+
43
+ export type InviteRole = 'member' | 'admin';
44
+
45
+ /** The Admin role's canonical name in `roles.yaml` (the backend's `ADMIN_CANONICAL`). */
46
+ const ADMIN_ROLE = 'admin';
47
+
48
+ /** What became of one address. */
49
+ export type InviteOutcome =
50
+ | { email: string; status: 'created'; role: InviteRole; roleError?: string }
51
+ /**
52
+ * Already had an account. Invited as Admin, they are made one too:
53
+ * `promoted` when this call did it, `alreadyAdmin` when they were one.
54
+ * `deactivated`: the account is switched off and cannot sign in until an
55
+ * admin switches it back on. Inviting does not do that — switching on asks
56
+ * the deployment for a seat, and is the User accounts page's decision.
57
+ */
58
+ | {
59
+ email: string;
60
+ status: 'existing';
61
+ promoted?: boolean;
62
+ alreadyAdmin?: boolean;
63
+ roleError?: string;
64
+ deactivated?: boolean;
65
+ }
66
+ /** The deployment's admission rules had no place for the account (a seat limit, say). */
67
+ | { email: string; status: 'no-seat'; message: string }
68
+ | { email: string; status: 'error'; message: string };
69
+
70
+ /** The address now has an account it can sign in to — new, or already there and switched on. */
71
+ export function isInvited(outcome: InviteOutcome): boolean {
72
+ return outcome.status === 'created' || (outcome.status === 'existing' && !outcome.deactivated);
73
+ }
74
+
75
+ /**
76
+ * Invite each address: an account with no password, waiting for that
77
+ * person's first single sign-on (`POST /api/admin/accounts`).
78
+ *
79
+ * One at a time, not in parallel. Each create asks the deployment's admission
80
+ * rules for a place, and a host that sells seats answers from a count —
81
+ * concurrent asks would race that count, and the order the admin typed is the
82
+ * order the seats should go in.
83
+ *
84
+ * The create endpoint is an upsert, so it cannot say "this person was already
85
+ * here". The account list read first can, and an address already on it is
86
+ * not created again: re-creating is not free (it asks for a seat again, and
87
+ * a full plan refuses somebody who already HAS one). A list that cannot be
88
+ * read just means every address is treated as new. The list holds
89
+ * switched-off accounts too, and those are reported as such rather than as
90
+ * able to sign in.
91
+ *
92
+ * Only a refusal the server marks as an admission refusal
93
+ * (`kind: 'admission'`) is "no seat left". Any other is an error in the
94
+ * server's own words — the route's admin check answers 403 as well, for an
95
+ * admin verdict gone stale in another tab.
96
+ *
97
+ * "Admin" is a role membership, not an account property, so it is a second
98
+ * write after the create. Somebody who already had an account is made an
99
+ * Admin too when invited as one: the admin asked for that person to be an
100
+ * Admin, and that they could already sign in does not change the request.
101
+ * The roster is read first so an existing Admin (including one the server
102
+ * configuration fixes) is reported as such rather than written again. A
103
+ * refused promotion leaves the account standing as it was and says so on
104
+ * the row.
105
+ */
106
+ export async function sendInvites(
107
+ emails: string[],
108
+ role: InviteRole,
109
+ api: {
110
+ listAccounts(): Promise<{ email: string; deactivatedAt?: string | null }[]>;
111
+ createAccount(email: string, name: string): Promise<void>;
112
+ addMember(canonical: string, email: string): Promise<unknown>;
113
+ fetchRoles(): Promise<{ canonical: string; members: string[]; fixedMembers?: string[] }[]>;
114
+ },
115
+ ): Promise<InviteOutcome[]> {
116
+ /** Every address with an account, and whether that account is switched off. Unreadable means none known. */
117
+ let existing: Map<string, boolean> | null = null;
118
+ try {
119
+ existing = new Map((await api.listAccounts()).map((a) => [a.email.toLowerCase(), Boolean(a.deactivatedAt)]));
120
+ } catch {
121
+ existing = null;
122
+ }
123
+ /** Who is an Admin already; asked only when someone is to be made one. Unreadable means unknown. */
124
+ let admins: Set<string> | null = null;
125
+ if (role === 'admin') {
126
+ try {
127
+ const entry = (await api.fetchRoles()).find((r) => r.canonical === ADMIN_ROLE);
128
+ admins = new Set([...(entry?.members ?? []), ...(entry?.fixedMembers ?? [])].map((e) => e.toLowerCase()));
129
+ } catch {
130
+ admins = null;
131
+ }
132
+ }
133
+ const outcomes: InviteOutcome[] = [];
134
+ for (const email of emails) {
135
+ if (existing?.has(email.toLowerCase())) {
136
+ const off = existing.get(email.toLowerCase()) ? { deactivated: true } : {};
137
+ if (role !== 'admin') {
138
+ outcomes.push({ email, status: 'existing', ...off });
139
+ } else if (admins?.has(email.toLowerCase())) {
140
+ outcomes.push({ email, status: 'existing', alreadyAdmin: true, ...off });
141
+ } else {
142
+ try {
143
+ await api.addMember(ADMIN_ROLE, email);
144
+ outcomes.push({ email, status: 'existing', promoted: true, ...off });
145
+ } catch (err) {
146
+ const roleError = err instanceof Error ? err.message : 'Could not make them an admin';
147
+ outcomes.push({ email, status: 'existing', roleError, ...off });
148
+ }
149
+ }
150
+ continue;
151
+ }
152
+ try {
153
+ await api.createAccount(email, '');
154
+ } catch (err) {
155
+ const message = err instanceof Error ? err.message : 'Could not create account';
156
+ const kind = (err as { kind?: unknown } | null)?.kind;
157
+ outcomes.push(
158
+ kind === 'admission' ? { email, status: 'no-seat', message } : { email, status: 'error', message },
159
+ );
160
+ continue;
161
+ }
162
+ if (role !== 'admin') {
163
+ outcomes.push({ email, status: 'created', role });
164
+ continue;
165
+ }
166
+ try {
167
+ await api.addMember(ADMIN_ROLE, email);
168
+ outcomes.push({ email, status: 'created', role: 'admin' });
169
+ } catch (err) {
170
+ const roleError = err instanceof Error ? err.message : 'Could not make them an admin';
171
+ outcomes.push({ email, status: 'created', role: 'member', roleError });
172
+ }
173
+ }
174
+ return outcomes;
175
+ }
@@ -0,0 +1,53 @@
1
+ import { authFetch } from '../../../lib/api';
2
+
3
+ /**
4
+ * Whether one of the signed-in person's agents has reached the platform —
5
+ * `GET /api/onboarding/agent-connection`. MIRRORS the backend's
6
+ * `AgentConnectionResponse` (`modules/audit/agent-connection.routes.ts`).
7
+ *
8
+ * "Connected" means an agent made an authenticated call with one of the
9
+ * person's live connections or keys, which every client does the moment it
10
+ * connects (it lists the tools) — not that it has used a tool yet.
11
+ */
12
+ export interface AgentConnection {
13
+ connected: boolean;
14
+ /** The agent's most recent call, ISO 8601. Present once connected. */
15
+ at?: string;
16
+ /** The agent's registered client name ("Claude"), or the connection key's label. */
17
+ client?: string;
18
+ /**
19
+ * Which of the two `client` is: `agent` for an OAuth connection's
20
+ * registered name, `key` for a connection key's free-text label.
21
+ */
22
+ kind?: 'agent' | 'key';
23
+ }
24
+
25
+ function optionalString(value: unknown): value is string | undefined {
26
+ return value === undefined || typeof value === 'string';
27
+ }
28
+
29
+ /**
30
+ * Throws on a refusal or a malformed body; callers read any failure as "not
31
+ * yet". Checked field by field rather than cast: a body that is not the
32
+ * documented shape is a failure, not a quiet "not connected" — and a
33
+ * "connected" with a stray `client` or `kind` must not steer the first-page
34
+ * step's links.
35
+ */
36
+ export async function fetchAgentConnection(): Promise<AgentConnection> {
37
+ const res = await authFetch('/api/onboarding/agent-connection');
38
+ if (!res.ok) throw new Error(`agent-connection: ${res.status}`);
39
+ const body: unknown = await res.json();
40
+ if (typeof body !== 'object' || body === null || typeof (body as { connected?: unknown }).connected !== 'boolean') {
41
+ throw new Error('agent-connection: malformed body');
42
+ }
43
+ const { connected, at, client, kind } = body as Record<string, unknown>;
44
+ if (connected === false) return { connected: false };
45
+ if (
46
+ !optionalString(at) ||
47
+ !optionalString(client) ||
48
+ (kind !== undefined && kind !== 'agent' && kind !== 'key')
49
+ ) {
50
+ throw new Error('agent-connection: malformed body');
51
+ }
52
+ return { connected: true, at, client, kind };
53
+ }