@bevel-software/platform-core-frontend 0.26.0 → 0.28.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 (206) 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__/ProductName.test.tsx +46 -0
  5. package/src/core/__tests__/ShellRoutes.test.tsx +22 -0
  6. package/src/core/__tests__/core-contributions.test.ts +16 -0
  7. package/src/core/core-contributions.ts +17 -0
  8. package/src/core/maker-url.ts +30 -0
  9. package/src/core/registry.ts +78 -1
  10. package/src/index.css +23 -5
  11. package/src/index.ts +5 -0
  12. package/src/lib/__tests__/latest-request.test.ts +48 -0
  13. package/src/lib/latest-request.ts +45 -0
  14. package/src/modules/access/__tests__/ManageAccessDialog.no-sso-invite.test.tsx +222 -0
  15. package/src/modules/access/__tests__/ManageAccessDialog.proposal.test.tsx +1 -1
  16. package/src/modules/access/api.ts +19 -3
  17. package/src/modules/access/components/ManageAccessDialog.tsx +61 -8
  18. package/src/modules/admin/__tests__/AdminRolesPage.fixed-admin.test.tsx +16 -1
  19. package/src/modules/admin/__tests__/RolesCorruptedBanner.test.tsx +70 -0
  20. package/src/modules/admin/__tests__/UserAccountsPage.test.tsx +284 -39
  21. package/src/modules/admin/components/AdminRolesPage.tsx +13 -14
  22. package/src/modules/admin/components/RolesCorruptedBanner.tsx +9 -4
  23. package/src/modules/admin/components/UserAccountsPage.tsx +91 -107
  24. package/src/modules/admin/services/roles.api.ts +14 -1
  25. package/src/modules/auth/__tests__/LoginScreen.test.tsx +80 -5
  26. package/src/modules/auth/__tests__/sso-strict-probe.test.ts +66 -0
  27. package/src/modules/auth/components/LoginScreen.tsx +101 -73
  28. package/src/modules/auth/services/account.api.ts +59 -3
  29. package/src/modules/auth/services/sso.ts +30 -10
  30. package/src/modules/auth/state/use-sign-in-methods.ts +41 -0
  31. package/src/modules/change-requests/__tests__/ChangeRequestDialog.sync-banner.test.tsx +176 -0
  32. package/src/modules/change-requests/__tests__/ChangeRequestDialog.unreadable.test.tsx +68 -0
  33. package/src/modules/change-requests/__tests__/ChangeRequestLink.test.tsx +182 -0
  34. package/src/modules/change-requests/__tests__/FileChangeBoxes.test.tsx +1 -1
  35. package/src/modules/change-requests/__tests__/readFileOnBranch.test.ts +79 -0
  36. package/src/modules/change-requests/components/ChangeBox.tsx +6 -1
  37. package/src/modules/change-requests/components/ChangeRequestDialog.tsx +45 -15
  38. package/src/modules/change-requests/components/ChangeRequestLink.tsx +151 -0
  39. package/src/modules/change-requests/components/CrFileTree.tsx +2 -1
  40. package/src/modules/change-requests/components/FileChangeBoxes.tsx +4 -2
  41. package/src/modules/change-requests/hooks/useApplyChangeRequest.ts +6 -3
  42. package/src/modules/change-requests/services/change-requests.api.ts +15 -2
  43. package/src/modules/change-requests/utils/readFailure.ts +22 -0
  44. package/src/modules/embed/__tests__/EmbedLinkPage.test.tsx +74 -0
  45. package/src/modules/embed/__tests__/EmbedView.test.tsx +473 -0
  46. package/src/modules/embed/__tests__/embed-config.test.ts +128 -0
  47. package/src/modules/embed/__tests__/embed-host.test.ts +111 -0
  48. package/src/modules/embed/__tests__/mcp-app-view.test.ts +295 -0
  49. package/src/modules/embed/__tests__/mount.test.tsx +157 -0
  50. package/src/modules/embed/components/EmbedLinkPage.tsx +109 -0
  51. package/src/modules/embed/components/EmbedView.tsx +545 -0
  52. package/src/modules/embed/embed-config.ts +132 -0
  53. package/src/modules/embed/embed-host.ts +120 -0
  54. package/src/modules/embed/mount.tsx +80 -0
  55. package/src/modules/embed/services/embed-token.ts +22 -0
  56. package/src/modules/embed/services/embed.api.ts +158 -0
  57. package/src/modules/git/__tests__/BranchSwitcher.test.tsx +202 -4
  58. package/src/modules/git/__tests__/GitSyncFailedBanner.test.tsx +59 -1
  59. package/src/modules/git/__tests__/PullNeededBanner.test.tsx +39 -22
  60. package/src/modules/git/__tests__/useAutoPullUpdates.test.tsx +7 -2
  61. package/src/modules/git/branch-delete-menu-item.tsx +24 -0
  62. package/src/modules/git/components/BranchSwitcher.tsx +29 -5
  63. package/src/modules/git/components/GitSyncFailedBanner.tsx +53 -15
  64. package/src/modules/git/components/HistoryVersionPreview.tsx +5 -3
  65. package/src/modules/git/components/PullNeededBanner.tsx +15 -49
  66. package/src/modules/git/hooks/useAutoPullUpdates.ts +9 -5
  67. package/src/modules/git/index.ts +15 -0
  68. package/src/modules/git/services/__tests__/error-messages.test.ts +67 -0
  69. package/src/modules/git/services/__tests__/pull-failure.test.ts +36 -0
  70. package/src/modules/git/services/error-messages.ts +58 -1
  71. package/src/modules/git/services/pull-failure.ts +68 -0
  72. package/src/modules/git/state/branch-delete-confirm.ts +46 -0
  73. package/src/modules/layout/__tests__/HeaderAlignment.test.tsx +1 -0
  74. package/src/modules/layout/__tests__/breakpoints.test.ts +7 -1
  75. package/src/modules/layout/breakpoints.ts +8 -0
  76. package/src/modules/library/__tests__/PluginExtras.test.tsx +9 -9
  77. package/src/modules/library/__tests__/PluginPage.test.tsx +8 -1
  78. package/src/modules/library/__tests__/SkillsTree.test.tsx +13 -4
  79. package/src/modules/library/components/LibraryPage.tsx +22 -0
  80. package/src/modules/library/components/PluginExtras.tsx +23 -6
  81. package/src/modules/library/components/PluginPage.tsx +6 -1
  82. package/src/modules/library/routes/LibraryRoutes.tsx +8 -7
  83. package/src/modules/library/services/plugins.api.ts +4 -1
  84. package/src/modules/library/state/plugins-revision.ts +28 -0
  85. package/src/modules/onboarding/__tests__/InviteButton.test.tsx +214 -0
  86. package/src/modules/onboarding/__tests__/agent-connection-api.test.ts +55 -0
  87. package/src/modules/onboarding/__tests__/creator-welcome.test.tsx +87 -82
  88. package/src/modules/onboarding/__tests__/first-page-prompt.test.ts +164 -0
  89. package/src/modules/onboarding/__tests__/get-started-column.test.tsx +1458 -0
  90. package/src/modules/onboarding/__tests__/invite-dialog.test.tsx +811 -0
  91. package/src/modules/onboarding/__tests__/invite-emails.test.ts +247 -0
  92. package/src/modules/onboarding/__tests__/onboarding.test.tsx +226 -193
  93. package/src/modules/onboarding/__tests__/starter-pack-card.test.tsx +136 -0
  94. package/src/modules/onboarding/components/CreatorWelcomePage.tsx +7 -11
  95. package/src/modules/onboarding/components/EmailChipsInput.tsx +138 -0
  96. package/src/modules/onboarding/components/GetStartedColumn.tsx +670 -0
  97. package/src/modules/onboarding/components/InviteButton.tsx +139 -0
  98. package/src/modules/onboarding/components/InviteDialog.tsx +741 -0
  99. package/src/modules/onboarding/components/RootLanding.tsx +8 -24
  100. package/src/modules/onboarding/components/StarterPackCard.tsx +98 -0
  101. package/src/modules/onboarding/components/WelcomePage.tsx +65 -154
  102. package/src/modules/onboarding/first-page-prompt.ts +123 -0
  103. package/src/modules/onboarding/invite-emails.ts +313 -0
  104. package/src/modules/onboarding/services/agent-connection.api.ts +53 -0
  105. package/src/modules/onboarding/services/starter-packs.api.ts +83 -0
  106. package/src/modules/onboarding/state/agent-connection.ts +167 -0
  107. package/src/modules/onboarding/state/invite-dialog.context.ts +35 -0
  108. package/src/modules/onboarding/state/invite-dialog.tsx +39 -0
  109. package/src/modules/onboarding/state/onboarding.ts +133 -59
  110. package/src/modules/onboarding/state/starter-packs.ts +169 -0
  111. package/src/modules/settings/settings-nav-items.tsx +8 -3
  112. package/src/modules/setup/__tests__/setup.first-run-storage.test.tsx +389 -0
  113. package/src/modules/setup/__tests__/setup.github.test.tsx +5 -5
  114. package/src/modules/setup/__tests__/setup.kept-draft.test.tsx +1 -1
  115. package/src/modules/setup/__tests__/setup.repository-change.test.tsx +1 -1
  116. package/src/modules/setup/__tests__/setup.repository.test.tsx +21 -21
  117. package/src/modules/setup/__tests__/setup.test.tsx +56 -15
  118. package/src/modules/setup/__tests__/useConnectionProbe.test.tsx +123 -0
  119. package/src/modules/setup/components/FirstRunStorage.tsx +560 -0
  120. package/src/modules/setup/components/SetupGate.tsx +46 -1
  121. package/src/modules/setup/components/SetupScreen.tsx +81 -84
  122. package/src/modules/setup/hooks/useConnectionProbe.ts +93 -0
  123. package/src/modules/setup/services/setup.api.ts +3 -3
  124. package/src/modules/setup/utils/suggested-branch.ts +27 -0
  125. package/src/modules/toolbar/commands/__tests__/actions.test.tsx +210 -0
  126. package/src/modules/toolbar/commands/actions.tsx +330 -0
  127. package/src/modules/toolbar/commands/command-menu.ts +44 -0
  128. package/src/modules/toolbar/commands/useCommandActions.ts +71 -0
  129. package/src/modules/toolbar/commands/useCommandShortcuts.ts +121 -0
  130. package/src/modules/toolbar/components/AppSwitcher.tsx +125 -22
  131. package/src/modules/toolbar/components/ExternalAgentAccessPage.tsx +1 -1
  132. package/src/modules/toolbar/components/ProfileMenu.tsx +9 -4
  133. package/src/modules/toolbar/components/SearchPalette.tsx +540 -0
  134. package/src/modules/toolbar/components/Toolbar.tsx +10 -0
  135. package/src/modules/toolbar/components/__tests__/AppSwitcher.test.tsx +230 -52
  136. package/src/modules/toolbar/components/__tests__/ProfileMenu.test.tsx +64 -0
  137. package/src/modules/toolbar/components/__tests__/SearchPalette.test.tsx +864 -0
  138. package/src/modules/toolbar/components/__tests__/Toolbar.test.tsx +57 -2
  139. package/src/modules/toolbar/search/__tests__/rank.test.ts +93 -0
  140. package/src/modules/toolbar/search/__tests__/sources.test.ts +131 -0
  141. package/src/modules/toolbar/search/rank.ts +111 -0
  142. package/src/modules/toolbar/search/sources.ts +169 -0
  143. package/src/modules/workflow/hooks/useFileLock.ts +10 -7
  144. package/src/modules/workflow/services/__tests__/lock.api.test.ts +41 -0
  145. package/src/modules/workflow/services/lock.api.ts +17 -2
  146. package/src/modules/workspace/__tests__/useWorkspaceState.test.ts +49 -1
  147. package/src/modules/workspace/components/EditorTabs.tsx +39 -15
  148. package/src/modules/workspace/components/FileExplorer.tsx +39 -6
  149. package/src/modules/workspace/components/FilePaneCard.tsx +6 -2
  150. package/src/modules/workspace/components/FileRoute.tsx +12 -7
  151. package/src/modules/workspace/components/FileViewer.tsx +271 -74
  152. package/src/modules/workspace/components/KbPageHeader.tsx +13 -6
  153. package/src/modules/workspace/components/__tests__/EditorTabs.test.tsx +88 -21
  154. package/src/modules/workspace/components/__tests__/FileExplorer.test.tsx +92 -4
  155. package/src/modules/workspace/components/__tests__/FileRoute.test.tsx +23 -3
  156. package/src/modules/workspace/components/__tests__/FileViewer.test.tsx +330 -6
  157. package/src/modules/workspace/components/__tests__/KbPageHeader.test.tsx +17 -2
  158. package/src/modules/workspace/components/renderers/DocxRenderer.tsx +11 -16
  159. package/src/modules/workspace/components/renderers/DownloadFileButton.tsx +6 -0
  160. package/src/modules/workspace/components/renderers/EmailRenderer.tsx +23 -21
  161. package/src/modules/workspace/components/renderers/ImageRenderer.tsx +13 -29
  162. package/src/modules/workspace/components/renderers/KbMarkdownView.tsx +9 -2
  163. package/src/modules/workspace/components/renderers/MarkdownRenderer.tsx +8 -0
  164. package/src/modules/workspace/components/renderers/PdfRenderer.tsx +14 -19
  165. package/src/modules/workspace/components/renderers/PptxRenderer.tsx +11 -17
  166. package/src/modules/workspace/components/renderers/ToolRenderer.tsx +35 -7
  167. package/src/modules/workspace/components/renderers/XlsxRenderer.tsx +11 -17
  168. package/src/modules/workspace/components/renderers/__tests__/EmailRenderer.links.test.tsx +73 -0
  169. package/src/modules/workspace/components/renderers/__tests__/ToolRenderer.scaffold.test.tsx +64 -0
  170. package/src/modules/workspace/components/renderers/__tests__/ToolRenderer.surface.test.tsx +82 -0
  171. package/src/modules/workspace/components/renderers/__tests__/bridgeHarness.ts +99 -0
  172. package/src/modules/workspace/components/renderers/__tests__/htmlSandbox.test.ts +129 -35
  173. package/src/modules/workspace/components/renderers/__tests__/htmlViewsGuide.test.ts +149 -0
  174. package/src/modules/workspace/components/renderers/__tests__/kbMarkdownLinkPolicy.test.tsx +100 -0
  175. package/src/modules/workspace/components/renderers/htmlSandbox.ts +76 -20
  176. package/src/modules/workspace/components/renderers/index.ts +26 -0
  177. package/src/modules/workspace/components/renderers/kbMarkdownPipeline.tsx +51 -1
  178. package/src/modules/workspace/components/renderers/rendererRawRead.ts +53 -0
  179. package/src/modules/workspace/components/renderers/rendererSurface.ts +109 -0
  180. package/src/modules/workspace/components/renderers/rendererWorkspace.ts +8 -2
  181. package/src/modules/workspace/hooks/__tests__/useCreatePage.test.ts +137 -0
  182. package/src/modules/workspace/hooks/__tests__/useKnowledgeWriteTarget.test.ts +302 -0
  183. package/src/modules/workspace/hooks/__tests__/useWorkspaceState.test.tsx +126 -21
  184. package/src/modules/workspace/hooks/useCreatePage.ts +206 -0
  185. package/src/modules/workspace/hooks/useKnowledgeWriteTarget.ts +238 -0
  186. package/src/modules/workspace/hooks/useWorkspaceImageResolver.ts +24 -7
  187. package/src/modules/workspace/hooks/useWorkspaceState.ts +42 -8
  188. package/src/modules/workspace/routing/__tests__/kb-routes.test.tsx +10 -0
  189. package/src/modules/workspace/routing/__tests__/md-links-parity.test.tsx +113 -0
  190. package/src/modules/workspace/routing/kb-routes.ts +66 -12
  191. package/src/modules/workspace/state/editable-page.ts +42 -0
  192. package/src/modules/workspace/state/workspace.context.ts +13 -4
  193. package/src/modules/workspace/utils/__tests__/display-file-name.test.ts +60 -0
  194. package/src/modules/workspace/utils/__tests__/fileTree.test.ts +75 -0
  195. package/src/modules/workspace/utils/__tests__/treeConfirm.test.ts +16 -0
  196. package/src/modules/workspace/utils/display-file-name.ts +102 -0
  197. package/src/modules/workspace/utils/fileTree.ts +49 -14
  198. package/src/modules/workspace/utils/treeConfirm.ts +15 -0
  199. package/src/shared/__tests__/no-builtin-confirm.test.ts +102 -0
  200. package/src/shared/components/ConfirmProvider.tsx +156 -0
  201. package/src/shared/components/Dialog.tsx +7 -0
  202. package/src/shared/components/__tests__/ConfirmProvider.test.tsx +198 -0
  203. package/src/shared/components/confirm-context.ts +94 -0
  204. package/src/shared/components/index.ts +3 -0
  205. package/src/modules/onboarding/components/WelcomeRoute.tsx +0 -57
  206. package/src/modules/onboarding/welcome-state.ts +0 -36
@@ -2,36 +2,22 @@ import { useEffect, useState } from 'react';
2
2
  import { Navigate } from 'react-router-dom';
3
3
  import { KB_ROUTE_PREFIX } from '../../workspace/routing/kb-routes';
4
4
  import { takePostLoginRedirect } from '../../auth/services/sso';
5
- import { useOnboarding } from '../state/onboarding';
6
- import { WELCOME_PATH } from '../paths';
7
5
 
8
6
  /**
9
- * Where `/` lands. For everyone, forever: Knowledge — except the ONE visit
10
- * where an account is brand new (`users.onboarding_done` false, and never
11
- * greeted in this browser), which lands on the welcome page instead.
7
+ * Where `/` lands: Knowledge, for everyone, brand-new accounts included.
12
8
  *
13
- * Deliberately only the root route: a deep link is an intention, and
14
- * onboarding must never hijack one. Whoever skips the welcome is reminded by
15
- * the sidebar pill, not by the router.
9
+ * There is no automatic welcome page. Choosing where the knowledge lives is
10
+ * the one step that has to come before the app (the setup gate asks it);
11
+ * connecting an agent can wait, and it waits in plain sight — the sidebar's
12
+ * Connect your agent pill and the Get set up list both lead to the welcome
13
+ * page, and neither takes over the screen on the way in.
16
14
  *
17
15
  * A deep link that came through SSO arrives HERE rather than at itself — the
18
16
  * OAuth round-trip returns to a fixed callback URL, which scrubs to `/`
19
17
  * (see `consumeSsoCallback`) — so the link's intention survives as the stash
20
- * `startSsoLogin` left behind. An existing account goes straight to it; a
21
- * brand-new one is still greeted first, and the welcome page's Done returns
22
- * to the link instead of the usual shelf (the `returnTo` state below).
23
- *
24
- * `useOnboarding` is provider-tolerant, so `ShellRoutes` stays renderable
25
- * without the full stack (its own documented property); providerless or
26
- * signed out this is exactly the old `<Navigate to={KB_ROUTE_PREFIX}>`.
27
- *
28
- * The redirect carries `greeting`, and it is the ONLY navigation that does:
29
- * arriving here because you just signed in is a different event from opening
30
- * the same page from the sidebar, and the page needs to tell them apart to
31
- * know whether it is a ceremony or a page. See `WelcomePage`.
18
+ * `startSsoLogin` left behind, and it outranks Knowledge.
32
19
  */
33
20
  export function RootLanding() {
34
- const { shouldWelcome } = useOnboarding();
35
21
  const [stash, setStash] = useState<{ returnTo: string | null } | null>(null);
36
22
 
37
23
  // Taken in an effect, not a state initializer: the take CLEARS the stash,
@@ -40,6 +26,7 @@ export function RootLanding() {
40
26
  // only the run that found something writes.
41
27
  useEffect(() => {
42
28
  const returnTo = takePostLoginRedirect();
29
+ // eslint-disable-next-line react-hooks/set-state-in-effect -- the one-shot take described above; it settles in one extra render
43
30
  setStash((s) => s ?? { returnTo });
44
31
  }, []);
45
32
 
@@ -47,8 +34,5 @@ export function RootLanding() {
47
34
  // after would put the wrong page in the history.
48
35
  if (stash === null) return null;
49
36
 
50
- if (shouldWelcome) {
51
- return <Navigate to={WELCOME_PATH} state={{ greeting: true, returnTo: stash.returnTo }} replace />;
52
- }
53
37
  return <Navigate to={stash.returnTo ?? KB_ROUTE_PREFIX} replace />;
54
38
  }
@@ -0,0 +1,98 @@
1
+ import { useState } from 'react';
2
+ import { Button } from '../../../shared/components';
3
+ import { useWorkspace } from '../../workspace/state/workspace.context';
4
+ import { useStarterPacks } from '../state/starter-packs';
5
+ import { SKIP_STARTER_PACK, type StarterPackApplied, type StarterPackSummary } from '../services/starter-packs.api';
6
+
7
+ /**
8
+ * "What does your team do?" — what a new knowledge base's admin sees where
9
+ * the reader's empty state would be, while the server still offers it (see
10
+ * `useStarterPacks`): one chip per starter pack, in the server's order, and a
11
+ * quiet way out.
12
+ *
13
+ * Choosing adds the pack in one commit; the tree is fetched again here rather
14
+ * than left to the change event, and BEFORE the shared answer retires the
15
+ * card, so the pages are in the tree by the time the ordinary empty state
16
+ * takes over and suggests them (should that fetch fail, the change event the
17
+ * commit sends brings the tree up to date). A refusal is said on the card
18
+ * itself, in the server's words: toasts speak only inside the Library, and
19
+ * "someone is editing the knowledge base right now" is exactly the sentence
20
+ * the admin needs to read. What is under way is said in a live region too:
21
+ * the buttons only change shape, and a screen reader would hear nothing
22
+ * until the result.
23
+ */
24
+ export function StarterPackCard({
25
+ packs,
26
+ onDone,
27
+ }: {
28
+ packs: StarterPackSummary[];
29
+ /** Called once the choice landed (a skip included), with what was added. */
30
+ onDone(applied: StarterPackApplied): void;
31
+ }) {
32
+ const { choose } = useStarterPacks();
33
+ const { refreshFileTree } = useWorkspace();
34
+ const [busy, setBusy] = useState<string | null>(null);
35
+ const [error, setError] = useState<string | null>(null);
36
+
37
+ async function pick(id: string) {
38
+ if (busy) return;
39
+ setBusy(id);
40
+ setError(null);
41
+ try {
42
+ const applied = await choose(id, (added) =>
43
+ added.pages + added.skills > 0 ? refreshFileTree() : Promise.resolve(null),
44
+ );
45
+ onDone(applied);
46
+ } catch (err) {
47
+ setError(err instanceof Error ? err.message : String(err));
48
+ setBusy(null);
49
+ }
50
+ }
51
+
52
+ const skipping = busy === SKIP_STARTER_PACK;
53
+ const adding = busy && !skipping ? packs.find((pack) => pack.id === busy) : undefined;
54
+ const underWay = adding ? `Adding starter pages and skills for ${adding.name}…` : skipping ? 'Skipping…' : '';
55
+
56
+ return (
57
+ <section aria-labelledby="starter-pack-title" className="text-center">
58
+ <h2 id="starter-pack-title" className="mb-2 text-head text-ink">
59
+ What does your team do?
60
+ </h2>
61
+ <p className="mb-6 text-ui text-ink-muted">We’ll add starter pages and skills that fit.</p>
62
+ <div role="group" aria-labelledby="starter-pack-title" className="flex flex-wrap justify-center gap-2">
63
+ {packs.map((pack) => (
64
+ <Button
65
+ key={pack.id}
66
+ size="md"
67
+ variant="outline"
68
+ title={pack.description}
69
+ disabled={busy !== null}
70
+ aria-busy={busy === pack.id}
71
+ onClick={() => void pick(pack.id)}
72
+ >
73
+ {busy === pack.id ? 'Adding…' : pack.name}
74
+ </Button>
75
+ ))}
76
+ </div>
77
+ {error && (
78
+ <p role="alert" className="mt-3 text-detail text-danger">
79
+ {error}
80
+ </p>
81
+ )}
82
+ <Button
83
+ size="sm"
84
+ variant="quiet"
85
+ className="mt-4"
86
+ disabled={busy !== null}
87
+ aria-busy={skipping}
88
+ onClick={() => void pick(SKIP_STARTER_PACK)}
89
+ >
90
+ {skipping ? 'Skipping…' : 'Skip, I’ll start from scratch'}
91
+ </Button>
92
+ {/* Always in the tree, so the region exists before it has something to say. */}
93
+ <span role="status" aria-live="polite" className="sr-only">
94
+ {underWay}
95
+ </span>
96
+ </section>
97
+ );
98
+ }
@@ -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,123 @@
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
+ /**
24
+ * Where a request names the Knowledge folder as the place to write: "in
25
+ * Knowledge", any case — the generic request's "write a page in Knowledge"
26
+ * and every built-in pack's "fill in the … page in Knowledge". Not a path
27
+ * already ("in Knowledge/Sales").
28
+ */
29
+ const IN_KNOWLEDGE = /\bin knowledge\b(?!\/)/gi;
30
+
31
+ /**
32
+ * What may follow "in Knowledge" when it is not the folder: "knowledge
33
+ * base", or a name that only starts with it ("Knowledge Management").
34
+ * Case-sensitive on purpose — " about our company" is the folder.
35
+ */
36
+ const NOT_THE_FOLDER = /^ (?:base\b|[A-Z])/;
37
+
38
+ /**
39
+ * The request pointed at `folder` — the path below the Knowledge folder New
40
+ * page would write in (`Sales`, `Sales/Team`) — so an agent writing as the
41
+ * person tries where they may write rather than the top, where they may not.
42
+ * No folder (the top of Knowledge) leaves the request as it is. The request's
43
+ * own "in Knowledge" becomes "in Knowledge/<folder>", in the request's own
44
+ * casing, so it names one place; one that never says where the page goes
45
+ * gets the place as a sentence of its own.
46
+ */
47
+ export function firstPagePromptInFolder(prompt: string, folder: string | null): string {
48
+ if (!folder) return prompt;
49
+ for (const match of prompt.matchAll(IN_KNOWLEDGE)) {
50
+ const end = match.index + match[0].length;
51
+ if (NOT_THE_FOLDER.test(prompt.slice(end))) continue;
52
+ return `${prompt.slice(0, end)}/${folder}${prompt.slice(end)}`;
53
+ }
54
+ return `${prompt} Save it in Knowledge/${folder}.`;
55
+ }
56
+
57
+ /** A new Claude chat with `prompt` typed into it (claude.ai's `q` parameter prefills; the person still sends). */
58
+ export function claudePromptUrl(prompt: string): string {
59
+ return `https://claude.ai/new?q=${encodeURIComponent(prompt)}`;
60
+ }
61
+
62
+ /** The same for ChatGPT, whose `q` parameter prefills a new chat. */
63
+ export function chatGptPromptUrl(prompt: string): string {
64
+ return `https://chatgpt.com/?q=${encodeURIComponent(prompt)}`;
65
+ }
66
+
67
+ /**
68
+ * Which of the prompt's ways in leads, for the agent that connected.
69
+ *
70
+ * - `claude`: the claude.ai link. Only for a connection claude.ai or Claude
71
+ * Desktop made with the hosted address — a custom connector added there is
72
+ * on both, so a new chat at claude.ai can reach the knowledge base.
73
+ * - `chatgpt`: the chatgpt.com link, for ChatGPT's connector.
74
+ * - `copy`: the prompt itself, for everything else — Claude Code, Cursor,
75
+ * any agent on the local server, any connection key, a name we do not
76
+ * know. None of them can be opened from a link, and pointing someone at a
77
+ * web chat that cannot see their knowledge base is a dead end.
78
+ */
79
+ export type FirstPagePrimary = 'claude' | 'chatgpt' | 'copy';
80
+
81
+ export interface FirstPageRoute {
82
+ primary: FirstPagePrimary;
83
+ /**
84
+ * The agent as a person names it, for "Paste it into …": the part before
85
+ * the local server's " · local server on <machine>", and null when the
86
+ * server only knows it as an unnamed or unknown agent — or by a connection
87
+ * key's label, which names the key rather than the app holding it.
88
+ */
89
+ agentName: string | null;
90
+ }
91
+
92
+ /** The local server registers as "<agent> · local server on <machine>" (`hexis-mcp` `registrationName`). */
93
+ const LOCAL_SERVER_SUFFIX = /\s*·\s*local server on\b.*$/i;
94
+
95
+ /** What claude.ai and Claude Desktop call themselves, folded. "Claude Code" is deliberately absent. */
96
+ const CLAUDE_WEB_NAMES = new Set(['claude', 'claude.ai', 'claude-ai', 'claude ai', 'claude desktop', 'claude-desktop']);
97
+
98
+ /**
99
+ * Reads the connection answer's `client` into the step's leading action.
100
+ * Only an OAuth connection's (`kind: 'agent'`) name is the app's own: a
101
+ * connection key's label is whatever its owner typed, so a key called
102
+ * "ChatGPT CLI" says nothing about ChatGPT being able to use it, and a key —
103
+ * or an answer that does not say which it is — always leads with `copy`.
104
+ * Case-insensitive, and anything it does not recognise falls back to `copy`,
105
+ * which works with every agent.
106
+ */
107
+ export function firstPageRoute(
108
+ client: string | null | undefined,
109
+ kind: 'agent' | 'key' | null | undefined,
110
+ ): FirstPageRoute {
111
+ if (kind !== 'agent') return { primary: 'copy', agentName: null };
112
+ const raw = (client ?? '').trim();
113
+ const local = LOCAL_SERVER_SUFFIX.test(raw);
114
+ const name = raw.replace(LOCAL_SERVER_SUFFIX, '').trim();
115
+ const folded = name.toLowerCase();
116
+ const agentName = !name || /^(unnamed|unknown) agent$/i.test(name) ? null : name;
117
+ // A local-server connection lives in that app's config file, not in the
118
+ // web chat a link would open — even when the app is Claude Desktop.
119
+ if (local) return { primary: 'copy', agentName };
120
+ if (/\bchatgpt\b/.test(folded)) return { primary: 'chatgpt', agentName };
121
+ if (CLAUDE_WEB_NAMES.has(folded)) return { primary: 'claude', agentName };
122
+ return { primary: 'copy', agentName };
123
+ }