@bevel-software/platform-core-frontend 0.8.0 → 0.9.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 (35) hide show
  1. package/package.json +2 -2
  2. package/src/core/registry.ts +16 -4
  3. package/src/modules/admin/state/admin.context.tsx +15 -0
  4. package/src/modules/library/__tests__/PluginPage.test.tsx +97 -6
  5. package/src/modules/library/__tests__/PluginsIndexPage.test.tsx +90 -10
  6. package/src/modules/library/__tests__/PluginsSidebar.contextmenu.test.tsx +1 -0
  7. package/src/modules/library/__tests__/PluginsSidebar.locked.test.tsx +1 -0
  8. package/src/modules/library/__tests__/PluginsSidebar.test.tsx +29 -0
  9. package/src/modules/library/__tests__/library-data.test.ts +82 -0
  10. package/src/modules/library/components/LibraryLayout.tsx +11 -2
  11. package/src/modules/library/components/NewSkillPanel.tsx +18 -0
  12. package/src/modules/library/components/PageActions.tsx +31 -8
  13. package/src/modules/library/components/PersonalPluginPage.tsx +14 -4
  14. package/src/modules/library/components/PluginJoinRequests.tsx +22 -1
  15. package/src/modules/library/components/PluginPage.tsx +42 -5
  16. package/src/modules/library/components/PluginsIndexPage.tsx +46 -3
  17. package/src/modules/library/components/PluginsSidebar.tsx +50 -0
  18. package/src/modules/library/components/plugin-page-parts.tsx +183 -3
  19. package/src/modules/library/routes/LibraryRoutes.tsx +2 -2
  20. package/src/modules/library/state/library-data.tsx +21 -0
  21. package/src/modules/onboarding/__tests__/creator-welcome.test.tsx +318 -0
  22. package/src/modules/onboarding/components/CreatorWelcomePage.tsx +143 -0
  23. package/src/modules/onboarding/components/WelcomePage.tsx +11 -14
  24. package/src/modules/onboarding/components/WelcomeRoute.tsx +57 -0
  25. package/src/modules/onboarding/welcome-state.ts +36 -0
  26. package/src/modules/setup/__tests__/setup.test.tsx +203 -0
  27. package/src/modules/setup/components/SetupScreen.tsx +235 -68
  28. package/src/modules/workspace/components/FileRoute.tsx +8 -1
  29. package/src/modules/workspace/components/FileViewer.tsx +95 -38
  30. package/src/modules/workspace/components/__tests__/FileRoute.test.tsx +20 -0
  31. package/src/modules/workspace/components/__tests__/FileViewer.test.tsx +227 -18
  32. package/src/modules/workspace/routing/__tests__/kb-routes.test.tsx +25 -0
  33. package/src/modules/workspace/routing/kb-routes.ts +23 -1
  34. package/src/modules/workspace/utils/fileTree.ts +51 -0
  35. package/src/shared/components/Surface.tsx +15 -0
@@ -38,8 +38,17 @@ export interface PageActionsProps {
38
38
  * editor with nothing to edit.
39
39
  */
40
40
  onShare?: () => void;
41
- /** Opens the add dialog. Never gated on role — see the note above. */
42
- onAdd(): void;
41
+ /**
42
+ * Opens the add dialog. Never gated on ROLE — see the note above; that is
43
+ * the whole point of this component.
44
+ *
45
+ * Omitted when there is nothing to add INTO, exactly as `onShare` is: the
46
+ * dialog needs the group's summary and its primary folder, so without them
47
+ * the button could only ever be a no-op. A control that is present and does
48
+ * nothing teaches people that buttons lie, which is worse than a control
49
+ * that is not there.
50
+ */
51
+ onAdd?: () => void;
43
52
  /** Copies a link to this page. Resolves false if the clipboard refused. */
44
53
  onCopyLink(): Promise<boolean>;
45
54
  /**
@@ -78,7 +87,7 @@ export function PageActions({
78
87
  }, [close, onCopyLink]);
79
88
 
80
89
  return (
81
- <div className="flex flex-none items-center gap-1.5">
90
+ <div className="relative flex flex-none items-center gap-1.5">
82
91
  {onShare && (
83
92
  <Button variant="outline" size="sm" onClick={onShare}>
84
93
  <Users size={13} />
@@ -86,9 +95,11 @@ export function PageActions({
86
95
  </Button>
87
96
  )}
88
97
 
89
- <IconButton aria-label={addLabel} title={addLabel} onClick={onAdd}>
90
- <Plus size={15} />
91
- </IconButton>
98
+ {onAdd && (
99
+ <IconButton aria-label={addLabel} title={addLabel} onClick={onAdd}>
100
+ <Plus size={15} />
101
+ </IconButton>
102
+ )}
92
103
 
93
104
  <div className="relative">
94
105
  <IconButton
@@ -139,12 +150,24 @@ export function PageActions({
139
150
 
140
151
  {/* The copy's answer, announced once. A clipboard write can be refused
141
152
  outright on a non-secure origin, and a silent no-op is the worst
142
- possible reply to "copy this". */}
153
+ possible reply to "copy this".
154
+
155
+ OUT of the flex flow, BELOW the row: in flow, the appearing text
156
+ widened the row and slid every button — including the `+` an empty
157
+ page's chalk arrow is aimed at — left for the 1.8s the answer shows.
158
+ A status is an annotation on the actions, not a fourth action, so it
159
+ must not move them.
160
+
161
+ Below rather than beside, because beside (`right-full`) reaches into
162
+ whatever shares the row — on a narrow column, or under a long group
163
+ name, that is the page title, and an answer that covers the heading
164
+ traded one layout bug for a worse one. Under the row it is clear of
165
+ every sibling at any width. */}
143
166
  <span
144
167
  role="status"
145
168
  aria-live="polite"
146
169
  className={cn(
147
- 'text-meta transition-opacity',
170
+ 'absolute right-0 top-full mt-1 whitespace-nowrap text-meta transition-opacity',
148
171
  copied ? 'opacity-100' : 'opacity-0',
149
172
  copied === 'fail' ? 'text-danger' : 'text-ink-faint',
150
173
  )}
@@ -6,7 +6,8 @@ import { useLibraryToast } from '../state/toast.context';
6
6
  import { urlForItemFile } from '../routes/library-paths';
7
7
  import { useWorkspace } from '../../workspace/state/workspace.context';
8
8
  import { personalPluginName } from '../utils/personal-plugin';
9
- import { PluginBreadcrumb, PluginItemSections, PageNote, RemoveLibraryItemDialog,
9
+ import { EmptySkillsNudge, PluginBreadcrumb, PluginItemSections, PageNote,
10
+ RemoveLibraryItemDialog,
10
11
  } from './plugin-page-parts';
11
12
  import { PageActions } from './PageActions';
12
13
  import { PersonalAddDialog } from './PersonalAddDialog';
@@ -95,9 +96,18 @@ export function PersonalPluginPage() {
95
96
  // per-path gate agrees, since your personal folder names you as owner.
96
97
  onRemove={setRemoving}
97
98
  // An empty room should say what to do in it, not explain its own filing
98
- // rule. "Anything your agent writes outside a plugin lands here" was
99
- // true and told nobody how to make the first thing appear.
100
- emptySkills="No skills of your own yet. Ask your agent to create skills."
99
+ // rule. The nudge's link opens the same add dialog the title row's `+`
100
+ // does, and its chalk arrow points at that `+` — the agent stays in the
101
+ // sentence as the other way a first skill appears.
102
+ emptySkills={
103
+ <EmptySkillsNudge
104
+ lead="No skills of your own yet."
105
+ actionLabel="Add the first skill"
106
+ tail=", or ask your agent to create one."
107
+ agentOnly="No skills of your own yet. Ask your agent to create skills."
108
+ onAction={() => setAddOpen(true)}
109
+ />
110
+ }
101
111
  emptyTools="No sign-ins of your own yet."
102
112
  />
103
113
 
@@ -1,4 +1,4 @@
1
- import { useEffect } from 'react';
1
+ import { useEffect, useLayoutEffect } from 'react';
2
2
  import { useJoinRequests } from '../hooks/useJoinRequests';
3
3
  import { AccessRequestsBanner } from './AccessRequestsBanner';
4
4
 
@@ -25,6 +25,13 @@ export interface PluginJoinRequestsProps {
25
25
  * next natural fetch.
26
26
  */
27
27
  reloadSignal?: number;
28
+ /**
29
+ * Told whether the banner is actually on screen (it renders nothing while
30
+ * no requests pend). The group page listens so the empty band's chalk
31
+ * arrow can stand down when this banner sits in its line of fire — the
32
+ * arrow's aim assumes nothing between the band and the title row.
33
+ */
34
+ onVisible?(visible: boolean): void;
28
35
  className?: string;
29
36
  }
30
37
 
@@ -33,6 +40,7 @@ export function PluginJoinRequests({
33
40
  folders,
34
41
  onManage,
35
42
  reloadSignal = 0,
43
+ onVisible,
36
44
  className,
37
45
  }: PluginJoinRequestsProps) {
38
46
  const requests = useJoinRequests(plugin, folders[0] ?? null);
@@ -42,6 +50,19 @@ export function PluginJoinRequests({
42
50
  if (reloadSignal > 0) reload();
43
51
  }, [reloadSignal, reload]);
44
52
 
53
+ const visible = requests.requests.length > 0;
54
+ // A LAYOUT effect, because the listener uses this to decide what to draw in
55
+ // the same frame. Requests arrive asynchronously; reported after paint, the
56
+ // banner and the empty band's arrow — which are meant to be mutually
57
+ // exclusive — would both be on screen for one frame. Before paint, the
58
+ // listener's re-render lands in the only frame that is ever drawn.
59
+ useLayoutEffect(() => {
60
+ onVisible?.(visible);
61
+ // Unmounting is the banner leaving the page — say so, or a listener keeps
62
+ // holding a "visible" that nothing on screen backs up.
63
+ return () => onVisible?.(false);
64
+ }, [visible, onVisible]);
65
+
45
66
  return (
46
67
  <AccessRequestsBanner
47
68
  plugin={plugin}
@@ -14,7 +14,8 @@ import { useWorkspace } from '../../workspace/state/workspace.context';
14
14
  import { ManifestButton, ClientExtensionsSection } from './PluginExtras';
15
15
  import { ManageAccessDialog } from '../../access/components/ManageAccessDialog';
16
16
  import { AddToPluginDialog } from './AddToPluginDialog';
17
- import { BandControls, PluginBreadcrumb, PluginItemSections, PageNote, RemoveLibraryItemDialog,
17
+ import { BandControls, EmptySkillsNudge, PluginBreadcrumb, PluginItemSections, PageNote,
18
+ RemoveLibraryItemDialog,
18
19
  } from './plugin-page-parts';
19
20
  import { DeletePluginDialog } from './DeletePluginDialog';
20
21
  import { PageActions } from './PageActions';
@@ -60,6 +61,13 @@ export function PluginPage() {
60
61
  const [accessRevision, setAccessRevision] = useState(0);
61
62
  /** The proposed skill being reviewed, if the reader opened one. */
62
63
  const [reviewing, setReviewing] = useState<LibraryItem | null>(null);
64
+ /**
65
+ * Whether the join-requests banner is actually on screen. The empty band's
66
+ * chalk arrow points a fixed distance up at the title row's `+`, so any
67
+ * banner between them turns the arrow into a lie — this is how the page
68
+ * knows to stand the arrow down (the sentence and its action stay).
69
+ */
70
+ const [joinRequestsShown, setJoinRequestsShown] = useState(false);
63
71
 
64
72
  /**
65
73
  * "Last updated just now" has to be TRUE.
@@ -235,7 +243,13 @@ export function PluginPage() {
235
243
  <ManifestButton kbDirName={kbDirName} folder={plugin} canWrite={summary?.canWrite === true} />
236
244
  <PageActions
237
245
  onShare={primaryFolder ? () => setManageFolder(primaryFolder) : undefined}
238
- onAdd={() => setAddOpen(true)}
246
+ // The dialog needs both to mount (`addOpen && summary &&
247
+ // primaryFolder`), so without them `+` could only ever be a
248
+ // no-op — it is omitted instead, the same way `Share` is when
249
+ // there is no folder to manage. The empty band's doorway checks
250
+ // the identical prerequisite, so the two ways to add always agree
251
+ // about whether adding is possible at all.
252
+ onAdd={summary && primaryFolder ? () => setAddOpen(true) : undefined}
239
253
  onCopyLink={() => copyToClipboard(window.location.href)}
240
254
  // The OWNER's verb — `isOwner` is the same verdict the DELETE
241
255
  // route enforces, so the item appears for exactly the people the
@@ -255,6 +269,7 @@ export function PluginPage() {
255
269
  folders={summary.folders}
256
270
  onManage={setManageFolder}
257
271
  reloadSignal={accessRevision}
272
+ onVisible={setJoinRequestsShown}
258
273
  className="mt-4"
259
274
  />
260
275
  )}
@@ -283,9 +298,31 @@ export function PluginPage() {
283
298
  // for real; this only decides who sees the affordance.
284
299
  onRemove={summary?.canWrite ? setRemoving : undefined}
285
300
  emptySkills={
286
- filterOn
287
- ? 'Nothing in this band needs you right now.'
288
- : `No skills yet. Add one, or ask your agent to write one for ${plugin}.`
301
+ filterOn ? (
302
+ 'Nothing in this band needs you right now.'
303
+ ) : summary && primaryFolder ? (
304
+ // A truly empty plugin is the one moment the page has to teach
305
+ // where "add" lives — the button opens the same dialog the title
306
+ // row's `+` does, and the nudge's arrow points at that `+`. The
307
+ // arrow stands down when a banner sits between the band and the
308
+ // title row (join requests, integration attention): its aim is a
309
+ // fixed offset, and pointing into a banner teaches the wrong spot.
310
+ <EmptySkillsNudge
311
+ lead="No skills yet."
312
+ actionLabel="Add the first skill"
313
+ tail={`, or ask your agent to write one for ${plugin}.`}
314
+ agentOnly={`No skills yet. Ask your agent to write one for ${plugin}.`}
315
+ arrow={attention === 0 && !joinRequestsShown}
316
+ onAction={() => setAddOpen(true)}
317
+ />
318
+ ) : (
319
+ // Degraded: the plugins endpoint failed, so the summary — and with
320
+ // it the folder the add dialog writes into — is missing. The
321
+ // dialog gated on both (`addOpen && summary && primaryFolder`)
322
+ // could not mount, so a doorway here would be a button that does
323
+ // nothing. State the fact and the one door that still works.
324
+ `No skills yet. Ask your agent to write one for ${plugin}.`
325
+ )
289
326
  }
290
327
  // The band fades its controls until you hover it, and `opacity`
291
328
  // composites — so "the filter stays lit when it is on" has to be said
@@ -1,15 +1,18 @@
1
- import { useMemo, type ReactNode } from 'react';
1
+ import { useMemo, useState, type ReactNode } from 'react';
2
2
  import { useNavigate } from 'react-router-dom';
3
3
  import { Badge, Banner } from '../../../shared/components';
4
4
  import { useAuth } from '../../auth/state/auth.context';
5
- import { attentionOf, useLibrary, type LibraryItem } from '../state/library-data';
5
+ import { useAdmin } from '../../admin/state/admin.context';
6
+ import { attentionOf, useLibrary, workspaceHasNoPlugins, type LibraryItem } from '../state/library-data';
6
7
  import { personalPluginName } from '../utils/personal-plugin';
7
8
  import { LIBRARY_ROOT, pathForPlugin } from '../routes/library-paths';
8
9
  import { ownersTextOf } from '../utils/plugin-summary';
9
10
  import type { PluginSummary } from '../services/plugins.api';
11
+ import { EmptyStateAction } from './plugin-page-parts';
10
12
  import { PluginIndexRow } from './PluginIndexRow';
11
13
  import { LockGlyph } from './LockGlyph';
12
14
  import { ManagedPluginRequests } from './ManagedPluginRequests';
15
+ import { NewPluginDialog } from './NewPluginDialog';
13
16
 
14
17
  /**
15
18
  * The all-plugins index — `/skills-and-tools`, where the Library opens.
@@ -38,9 +41,12 @@ interface IndexEntry {
38
41
  }
39
42
 
40
43
  export function PluginsIndexPage() {
41
- const { items, pluginSummaries, pluginsLoading, pluginsError, reloadPlugins } = useLibrary();
44
+ const lib = useLibrary();
45
+ const { items, pluginSummaries, pluginsLoading, pluginsError, reload, reloadPlugins } = lib;
42
46
  const navigate = useNavigate();
43
47
  const { user } = useAuth();
48
+ const { isAdmin } = useAdmin();
49
+ const [newPluginOpen, setNewPluginOpen] = useState(false);
44
50
 
45
51
  const personalName = personalPluginName(user?.name);
46
52
  const ungroupedSkills = countKind(items, null, 'skill');
@@ -114,6 +120,29 @@ export function PluginsIndexPage() {
114
120
  ) : (
115
121
  <>
116
122
  <SectionHead count={mine.length}>Your plugins</SectionHead>
123
+ {/* The one page a person with no plugins is guaranteed to land on —
124
+ the Library opens here — so it is where the app says how a plugin
125
+ comes to exist, instead of a blank section that reads as "not for
126
+ you". The sidebar's `+` does the same thing; this one is written
127
+ out because a newcomer has not found that `+` yet.
128
+
129
+ Same verdict as the nav's version, from the same shared
130
+ predicate — `workspaceHasNoPlugins` — so the two surfaces cannot
131
+ disagree about whether a workspace is untouched. It is false for
132
+ locked plugins too (`mine.length === 0` alone would promise "the
133
+ first plugin" to someone simply not added to the twenty that
134
+ exist), and false until both plugin witnesses settle
135
+ successfully: a catalog still loading, or a summaries call that
136
+ failed, is an unanswered question, not an untouched workspace. */}
137
+ {isAdmin && workspaceHasNoPlugins(lib) && (
138
+ <p className="text-ui text-ink-faint">
139
+ {"You're not in any plugins yet. "}
140
+ <EmptyStateAction onClick={() => setNewPluginOpen(true)}>
141
+ Create the first plugin
142
+ </EmptyStateAction>
143
+ {' to share skills and tools with your team.'}
144
+ </p>
145
+ )}
117
146
  <RowList>
118
147
  {mine.map((entry) => (
119
148
  <PluginIndexRow
@@ -174,6 +203,20 @@ export function PluginsIndexPage() {
174
203
  )}
175
204
  </>
176
205
  )}
206
+
207
+ {newPluginOpen && (
208
+ <NewPluginDialog
209
+ // Every name this page can see — summaries and catalog-derived rows
210
+ // alike. Locked-but-undiscoverable plugins are absent from both; the
211
+ // provisioning endpoint is the authority that catches those.
212
+ existing={entries.map((e) => e.name)}
213
+ onClose={() => setNewPluginOpen(false)}
214
+ onCreated={() => {
215
+ reload();
216
+ reloadPlugins();
217
+ }}
218
+ />
219
+ )}
177
220
  </div>
178
221
  );
179
222
  }
@@ -1,6 +1,7 @@
1
1
  import type { MouseEvent, ReactNode } from 'react';
2
2
  import { cn } from '../../../lib/utils';
3
3
  import type { LibraryFilter } from '../utils/status';
4
+ import { ChalkArrow } from './plugin-page-parts';
4
5
  import { LockGlyph } from './LockGlyph';
5
6
 
6
7
  /**
@@ -48,6 +49,25 @@ export interface PluginsSidebarProps {
48
49
  onFinishSetup(): void;
49
50
  /** Start a new plugin. The layout owns the dialog; this is only the intent. */
50
51
  onCreatePlugin(): void;
52
+ /**
53
+ * Whether to spell the first plugin out in words, with the chalk arrow. The
54
+ * hover-revealed `+` is unchanged for everyone; this is only the teaching
55
+ * mark, and it is an administrator's — see the empty-state block below.
56
+ *
57
+ * The caller passes a SETTLED verdict, not just a role: the layout derives
58
+ * it from `workspaceHasNoPlugins`, which stays false while plugin discovery
59
+ * is loading or has failed. Without that, an admin whose plugins were still
60
+ * arriving would briefly read "Create a plugin" over a workspace that has
61
+ * twenty. The empty-`plugins` check below is therefore structural (where the
62
+ * row may appear), while WHETHER it may appear is the caller's call.
63
+ *
64
+ * Optional, defaulting to OFF, for the same reason `isAdminLoading` is
65
+ * optional on the admin context: this props type is public, and a host
66
+ * application rendering the nav must stay source-compatible across the
67
+ * upgrade. Omitting it reproduces the nav exactly as it shipped, which had
68
+ * no written-out CTA at all.
69
+ */
70
+ canCreatePlugin?: boolean;
51
71
  /**
52
72
  * The all-plugins index is showing. Beside `filter` rather than inside it: the
53
73
  * index lists PLACES, not a filtered slice of the catalog, so it is not a
@@ -99,6 +119,7 @@ export function PluginsSidebar({
99
119
  attentionCount,
100
120
  onFinishSetup,
101
121
  onCreatePlugin,
122
+ canCreatePlugin = false,
102
123
  pluginsIndexActive,
103
124
  onOpenPluginsIndex,
104
125
  onContextMenu,
@@ -266,6 +287,35 @@ export function PluginsSidebar({
266
287
  attention > 0 ? 'pending' : 'count',
267
288
  ),
268
289
  )}
290
+ {/* The heading's `+` is hover-revealed, and a person with no plugins
291
+ yet is exactly the person who has not learned to hover it. While
292
+ the workspace holds no plugins AT ALL, the way to the first one is
293
+ said in words, as a row where it would sit — with a chalk arrow
294
+ from the empty space below, the same margin-note voice as the
295
+ empty plugin page. It stands down the moment any plugin exists,
296
+ readable or locked: a locked plugin means someone already created
297
+ one, and this is a doorway for an untouched workspace, not a
298
+ permanent duplicate of the `+`.
299
+
300
+ Administrators only. On an untouched workspace the first plugin is
301
+ theirs to make, and telling everyone else to make it points them
302
+ at a decision that is not theirs. The `+` above is untouched for
303
+ every caller — this is the teaching mark, not the affordance. */}
304
+ {canCreatePlugin && plugins.length === 0 && lockedPlugins.length === 0 && (
305
+ <div className="relative">
306
+ <button
307
+ type="button"
308
+ onClick={onCreatePlugin}
309
+ className="flex items-center gap-2 rounded-sm px-2.5 py-1.5 text-left text-ui text-ink-faint transition-colors hover:bg-hover hover:text-ink"
310
+ >
311
+ <span aria-hidden="true">+</span>
312
+ <span className="truncate">Create a plugin</span>
313
+ </button>
314
+ {/* Mirrored, so the tip points up-left at the row's words from
315
+ the room an empty nav is guaranteed to have beneath it. */}
316
+ <ChalkArrow className="pointer-events-none absolute left-[22px] top-[30px] h-[52px] w-[64px] -scale-x-100 text-ink-faint" />
317
+ </div>
318
+ )}
269
319
  {/* Locked plugins, after the prototype's 14px `.navgap`. The gap is the
270
320
  whole statement: these are in the same list because they are in the
271
321
  same workspace, and below a break because you are not in them. */}
@@ -1,6 +1,7 @@
1
- import { useState, type ReactNode } from 'react';
1
+ import { useId, useState, type ReactNode } from 'react';
2
2
  import { Link } from 'react-router-dom';
3
3
  import { Funnel, RotateCw, Trash2 } from 'lucide-react';
4
+ import { useAdmin } from '../../admin/state/admin.context';
4
5
  import { cn } from '../../../lib/utils';
5
6
  import { Banner, Button, Dialog, IconButton } from '../../../shared/components';
6
7
  import { pathForPluginsIndex } from '../routes/library-paths';
@@ -286,7 +287,13 @@ export function PluginItemSections({
286
287
  onOpen(item: LibraryItem): void;
287
288
  /** See {@link CardGrid} — present only when the caller manages this place. */
288
289
  onRemove?(item: LibraryItem): void;
289
- emptySkills: string;
290
+ /**
291
+ * A plain sentence, or an `EmptySkillsNudge`. A string still gets the band's
292
+ * standard paragraph; a node is trusted to bring its own — the nudge carries
293
+ * an absolutely-placed arrow, and wrapping it in a second `<p>` would nest
294
+ * flow content inside phrasing content.
295
+ */
296
+ emptySkills: ReactNode;
290
297
  emptyTools?: string;
291
298
  /**
292
299
  * Filter / refresh for the Skills band only. Tools deliberately gets none
@@ -316,7 +323,11 @@ export function PluginItemSections({
316
323
  controlsActive={skillControlsActive}
317
324
  >
318
325
  {skillItems.length === 0 ? (
319
- <p className="text-ui text-ink-faint">{emptySkills}</p>
326
+ typeof emptySkills === 'string' ? (
327
+ <p className="text-ui text-ink-faint">{emptySkills}</p>
328
+ ) : (
329
+ emptySkills
330
+ )
320
331
  ) : (
321
332
  <CardGrid items={skillItems} onOpen={onOpen} onRemove={onRemove} />
322
333
  )}
@@ -345,6 +356,175 @@ export function PageNote({ children }: { children: ReactNode }) {
345
356
  return <div className="py-16 text-center text-ui text-ink-faint">{children}</div>;
346
357
  }
347
358
 
359
+ /**
360
+ * A hand-drawn arrow, chalk on the wall — the mark an empty page makes toward
361
+ * the control that fills it. Decorative on purpose: the sentence beside it
362
+ * carries the meaning, so the drawing is `aria-hidden`, takes no pointer, and
363
+ * inherits `currentColor` so it stays as faint as the ink around it.
364
+ */
365
+ export function ChalkArrow({ className }: { className?: string }) {
366
+ // Colons stripped: `url(#…)` fragment references are unreliable with them.
367
+ const filterId = `chalk-${useId().replace(/[^a-zA-Z0-9_-]/g, '')}`;
368
+ return (
369
+ <svg
370
+ data-testid="chalk-arrow"
371
+ className={className}
372
+ aria-hidden="true"
373
+ focusable="false"
374
+ viewBox="0 0 88 72"
375
+ fill="none"
376
+ stroke="currentColor"
377
+ strokeLinecap="round"
378
+ strokeLinejoin="round"
379
+ >
380
+ <defs>
381
+ {/* What makes the line chalk instead of vector: a slow noise bends the
382
+ stroke the way a hand does, a fine noise frays its edge the way a
383
+ wall's tooth does, and a mid noise thins the ink where the chalk
384
+ skipped. Displacement can push ~2px past the paths, hence the
385
+ widened filter region. */}
386
+ <filter id={filterId} x="-15%" y="-15%" width="130%" height="130%">
387
+ <feTurbulence type="fractalNoise" baseFrequency="0.04" numOctaves="1" seed="3" result="wobble" />
388
+ <feDisplacementMap in="SourceGraphic" in2="wobble" scale="2.5" result="bent" />
389
+ <feTurbulence type="fractalNoise" baseFrequency="0.8" numOctaves="2" seed="11" result="grit" />
390
+ <feDisplacementMap in="bent" in2="grit" scale="1.4" result="rough" />
391
+ <feTurbulence type="fractalNoise" baseFrequency="0.3" numOctaves="3" seed="5" result="dust" />
392
+ <feColorMatrix
393
+ in="dust"
394
+ type="matrix"
395
+ values="0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0.7 0.55"
396
+ result="patch"
397
+ />
398
+ <feComposite in="rough" in2="patch" operator="in" />
399
+ </filter>
400
+ </defs>
401
+ <g filter={`url(#${filterId})`}>
402
+ {/* One loose curve from the words up toward the `+` — tip stays at
403
+ (76,11), which is what the call sites' offsets aim — plus a short
404
+ second pass beside the shaft, the stroke a hand goes over twice. */}
405
+ <path strokeWidth="2.5" d="M6 66 C 30 63, 53 51, 67 32 C 71 26, 74 19, 76 11" />
406
+ <path strokeWidth="1.5" opacity="0.5" d="M17 64 C 34 61, 49 52.5, 61 40" />
407
+ {/* The head as two separate flicks, not a joined V: drawn strokes
408
+ land past each other at the tip, they do not meet in a corner. */}
409
+ <path strokeWidth="2.5" d="M64 18 Q 70.5 14, 76.4 10.6" />
410
+ <path strokeWidth="2.5" d="M79.6 24.6 Q 78.1 17.5, 76 10.7" />
411
+ </g>
412
+ </svg>
413
+ );
414
+ }
415
+
416
+ /**
417
+ * The inline verb inside an empty state's sentence — underlined, ink-strong
418
+ * against the faint prose around it, and a real `<button>` because it acts
419
+ * rather than navigates. One component so every empty state's doorway looks
420
+ * like the same kind of doorway.
421
+ */
422
+ export function EmptyStateAction({
423
+ children,
424
+ onClick,
425
+ }: {
426
+ children: ReactNode;
427
+ onClick(): void;
428
+ }) {
429
+ return (
430
+ <button
431
+ type="button"
432
+ onClick={onClick}
433
+ // The same focus ring as `Button`/`IconButton`: an inline action is
434
+ // still a stop on the keyboard's path, and the underline alone does not
435
+ // say "you are here".
436
+ className="rounded-xs font-semibold text-ink underline underline-offset-2 hover:text-ink-muted focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-ink-muted"
437
+ >
438
+ {children}
439
+ </button>
440
+ );
441
+ }
442
+
443
+ /**
444
+ * Where the nudge's arrow sits so its TIP lands on the `+` icon-button's
445
+ * centre: from the column's right edge that centre sits behind the `⋯` button
446
+ * and two flex gaps (~54px), constant on every page that renders
447
+ * `PageActions` — Share sits on the far side of `+`, so its presence moves
448
+ * nothing.
449
+ *
450
+ * A named constant because these offsets are TUNED, together with the tip the
451
+ * `ChalkArrow` paths aim at (76,11 in its 88×72 viewBox): change the
452
+ * `PageActions` row — button size, gap, order — and this is the one place the
453
+ * aim gets re-tuned, rather than a magic literal scattered per call site.
454
+ */
455
+ const ARROW_AT_PAGE_ACTIONS_PLUS =
456
+ 'pointer-events-none absolute -top-[74px] right-[45px] h-[68px] w-[84px] text-ink-faint';
457
+
458
+ /**
459
+ * The empty Skills band as a doorway instead of a dead end. The sentence
460
+ * names the fact and hands over a button that DOES the thing — the same thing
461
+ * the title row's `+` does — while a chalk arrow points up at that `+`, so
462
+ * the page itself teaches where "add" lives. No separate tour, no overlay:
463
+ * the arrow exists only because this component only renders when the band is
464
+ * empty, and it leaves the moment the first skill arrives.
465
+ *
466
+ * The arrow overlaps the band heading on its way up. That is intended — it is
467
+ * background, not layout: absolutely placed, `pointer-events-none`, and faint
468
+ * enough to read as a margin note rather than a fourth piece of chrome.
469
+ */
470
+ export function EmptySkillsNudge({
471
+ lead,
472
+ actionLabel,
473
+ tail,
474
+ agentOnly,
475
+ arrow = true,
476
+ onAction,
477
+ }: {
478
+ /** The fact: "No skills yet." */
479
+ lead: string;
480
+ /** The doorway's words, e.g. "Add the first skill". */
481
+ actionLabel: string;
482
+ /** The rest of the sentence — usually pointing at the agent as the other door. */
483
+ tail: string;
484
+ /**
485
+ * The whole sentence a non-admin reads instead — same fact, agent door only.
486
+ * Written out rather than assembled from `lead` + `tail`, because `tail` is
487
+ * a continuation (", or ask your agent…") and cannot stand on its own.
488
+ */
489
+ agentOnly: string;
490
+ /**
491
+ * Whether the chalk arrow may be drawn. The arrow's aim is a fixed offset
492
+ * from THIS component to the title row's `+`, so it only tells the truth
493
+ * when nothing sits between them — a page that knows a banner intervenes
494
+ * (join requests, integration attention) passes false and keeps the
495
+ * sentence, which needs no geometry to be right.
496
+ */
497
+ arrow?: boolean;
498
+ /** Exactly what the title row's `+` does. One intent, two doors. */
499
+ onAction(): void;
500
+ }) {
501
+ const { isAdmin, isAdminLoading = false } = useAdmin();
502
+
503
+ // While the admin verdict is still in flight, say only the fact. Committing
504
+ // to either door — the inline action or "ask your agent" — would flip the
505
+ // sentence (and the arrow) in front of the reader the moment the verdict
506
+ // lands, and the fact is the one part that is true either way.
507
+ if (isAdminLoading) return <p className="text-ui text-ink-faint">{lead}</p>;
508
+
509
+ // Starting a skill in place is an administrator's affordance — the add
510
+ // dialogs already refuse the empty-file half to everyone else. So the
511
+ // doorway, link and chalk arrow both, is admin-only. The band still states
512
+ // the fact and names the agent, which IS the door a non-admin has: the
513
+ // title row's `+` stays where it was for them, just without a mark
514
+ // pointing at it.
515
+ if (!isAdmin) return <p className="text-ui text-ink-faint">{agentOnly}</p>;
516
+
517
+ return (
518
+ <div className="relative">
519
+ {arrow && <ChalkArrow className={ARROW_AT_PAGE_ACTIONS_PLUS} />}
520
+ <p className="text-ui text-ink-faint">
521
+ {lead} <EmptyStateAction onClick={onAction}>{actionLabel}</EmptyStateAction>
522
+ {tail}
523
+ </p>
524
+ </div>
525
+ );
526
+ }
527
+
348
528
  /**
349
529
  * Three nodes and the lines between them — the prototype's `SHARE_SVG`
350
530
  * (line 1640), unchanged. Inline for the same reason as `LockGlyph`: it
@@ -7,7 +7,7 @@ import { LibraryPage } from '../components/LibraryPage';
7
7
  import { PluginPage } from '../components/PluginPage';
8
8
  import { PluginsIndexPage } from '../components/PluginsIndexPage';
9
9
  import { PersonalPluginPage } from '../components/PersonalPluginPage';
10
- import { WelcomePage } from '../../onboarding/components/WelcomePage';
10
+ import { WelcomeRoute } from '../../onboarding/components/WelcomeRoute';
11
11
  import { WorkspaceItemRoute } from './WorkspaceItemRoute';
12
12
  import { decodePluginSegment, LIBRARY_ROOT, pathForPlugin, urlForItemFile, urlForSkillFile } from './library-paths';
13
13
 
@@ -45,7 +45,7 @@ export function LibraryRoutes() {
45
45
  sidebar (and the pill's selected state) is on screen with it.
46
46
  Auto-reached once, on first sign-in (see `RootLanding`);
47
47
  reachable forever through the pill and by URL. */}
48
- <Route path="welcome" element={<WelcomePage />} />
48
+ <Route path="welcome" element={<WelcomeRoute />} />
49
49
 
50
50
  <Route path="owned" element={<LibraryPage filter={{ kind: 'owned' }} />} />
51
51
 
@@ -206,6 +206,27 @@ export function useLibrary(): LibraryContextValue {
206
206
  return value;
207
207
  }
208
208
 
209
+ /**
210
+ * "This workspace holds no plugins at all" — settled, and from both witnesses.
211
+ *
212
+ * One predicate for every surface that offers to create the FIRST plugin (the
213
+ * nav's spelled-out row, the index's CTA), so the two cannot drift into
214
+ * disagreeing about whether a workspace is untouched. Deliberately false while
215
+ * either source is still loading or has failed: an unanswered question is not
216
+ * "no plugins", and a first-plugin doorway shown on a guess points somebody at
217
+ * a decision that may already be taken.
218
+ */
219
+ export function workspaceHasNoPlugins(lib: LibraryContextValue): boolean {
220
+ return (
221
+ !lib.loading &&
222
+ !lib.pluginsLoading &&
223
+ !lib.error &&
224
+ !lib.pluginsError &&
225
+ lib.pluginSummaries.length === 0 &&
226
+ lib.items.every((item) => item.plugin === null)
227
+ );
228
+ }
229
+
209
230
  /**
210
231
  * How many of a plugin's integrations need setup — the amber count on the
211
232
  * sidebar row and the plugin page's banner, computed from one place so the two