@deveye/types 0.25.5 → 0.26.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.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@deveye/types",
3
- "version": "0.25.5",
3
+ "version": "0.26.0",
4
4
  "description": "Shared contracts (types + zod schemas) for DevEye apps",
5
5
  "main": "src/index.ts",
6
6
  "types": "src/index.ts",
@@ -96,7 +96,22 @@ export const deviceSchema = z.object({
96
96
  * during deletion, so the UI can surface it and the deletion is aborted.
97
97
  * Null when there's no pending error.
98
98
  */
99
- deleteError: z.string().nullable().default(null)
99
+ deleteError: z.string().nullable().default(null),
100
+ /**
101
+ * The agent was paused (from the app, `deveye-agent pause` or the tray
102
+ * icon): it monitors nothing and takes no order until resumed. `until` is
103
+ * the unix second it resumes on its own, null for a pause that waits to be
104
+ * resumed; `reachable` says its control session is connected, so a resume
105
+ * ordered now reaches it. Null when the agent is not paused.
106
+ */
107
+ pause: z
108
+ .object({
109
+ since: z.number().int().nonnegative(),
110
+ until: z.number().int().nonnegative().nullable(),
111
+ reachable: z.boolean()
112
+ })
113
+ .nullable()
114
+ .default(null)
100
115
  });
101
116
 
102
117
  export type Device = z.infer<typeof deviceSchema>;
@@ -148,6 +163,10 @@ export interface DeviceRow {
148
163
  status_before_delete: string | null;
149
164
  /** Last self-destruct failure message (deletion aborted); null otherwise. */
150
165
  delete_error: string | null;
166
+ /** Unix second the agent reported itself paused; null when it is not. */
167
+ paused_at: number | null;
168
+ /** Unix second the pause ends on its own; null while paused without a deadline. */
169
+ paused_until: number | null;
151
170
  /** Rang chez lui ; celui des espaces qui ne font que le voir vit dans `item_shares`. */
152
171
  sort_order: number;
153
172
  }
@@ -330,6 +330,16 @@ export const FEATURE_REGISTRY: readonly (FeatureDescriptor & { id: WorkspaceFeat
330
330
  hasItems: false,
331
331
  shareTier: 'never'
332
332
  },
333
+ {
334
+ id: 'pdf',
335
+ label: 'PDF',
336
+ description:
337
+ 'Fusionner, trier, signer, annoter, remplir et protéger des PDF dans le navigateur, et les signatures gardées sur le compte. Rien ne passe par le serveur.',
338
+ icon: 'pdf',
339
+ notifies: false,
340
+ hasItems: false,
341
+ shareTier: 'never'
342
+ },
333
343
  {
334
344
  id: 'invoicing',
335
345
  label: 'Facturation',
@@ -362,6 +372,17 @@ export const FEATURE_REGISTRY: readonly (FeatureDescriptor & { id: WorkspaceFeat
362
372
  hasItems: true,
363
373
  itemNoun: 'lien',
364
374
  shareTier: 'open'
375
+ },
376
+ {
377
+ id: 'whiteboard',
378
+ label: 'Tableau blanc',
379
+ description:
380
+ 'Lecture : les tableaux, et suivre en direct qui y dessine. Écriture : créer un tableau, dessiner, y coller des images, le renommer, le supprimer.',
381
+ icon: 'whiteboard',
382
+ notifies: false,
383
+ hasItems: true,
384
+ itemNoun: 'tableau',
385
+ shareTier: 'open'
365
386
  }
366
387
  ];
367
388
 
@@ -496,7 +517,8 @@ export const PROJECT_LINKED_FEATURES: readonly FeatureId[] = [
496
517
  'audience',
497
518
  'deploy',
498
519
  'uptime',
499
- 'x-hosting'
520
+ 'x-hosting',
521
+ 'whiteboard'
500
522
  ];
501
523
 
502
524
  /** Les fonctionnalités qui savent prévenir, dans l'ordre du registre. */
@@ -40,8 +40,10 @@ export const nativeHomeFeatureIdSchema = z.enum([
40
40
  'cve',
41
41
  'mailserver',
42
42
  'convert',
43
+ 'pdf',
43
44
  'invoicing',
44
- 'shortlinks'
45
+ 'shortlinks',
46
+ 'whiteboard'
45
47
  ]);
46
48
  export type NativeHomeFeatureId = z.infer<typeof nativeHomeFeatureIdSchema>;
47
49
 
@@ -76,22 +76,35 @@ export const liveCursorKindSchema = z.enum([
76
76
  export type LiveCursorKind = z.infer<typeof liveCursorKindSchema>;
77
77
 
78
78
  /**
79
- * Position du curseur dans la surface de la vue. Unités mixtes à dessein :
79
+ * Position du curseur dans la surface de la vue. Celle de la popup, par défaut,
80
+ * a des unités mixtes à dessein :
80
81
  * - `x` est relatif (0..1) à la largeur de la surface, bornée à 1240 px : seule
81
82
  * une fraction reste juste quand les deux fenêtres divergent ;
82
83
  * - `y` est en pixels absolus du contenu, défilement compris : le contenu est
83
84
  * le même des deux côtés, alors qu'une fraction de la hauteur se décalerait
84
85
  * dès qu'une liste est chargée plus loin d'un côté.
85
- * Les bornes de `x` dépassent [0, 1] : le pointeur vit aussi dans les marges,
86
- * et l'écrêter ferait disparaître le curseur d'un pair sur la même page.
86
+ * Une vue qui déclare sa propre surface (un canevas qu'on déplace et qu'on
87
+ * zoome) donne les deux dans ses unités à elle. Les bornes n'écartent que
88
+ * l'absurde : un pointeur vit aussi dans les marges, et l'écrêter ferait
89
+ * disparaître le curseur d'un pair sur la même page.
87
90
  */
88
91
  export const liveCursorSchema = z.object({
89
- x: z.number().min(-10).max(10),
90
- y: z.number().min(-100_000).max(100_000),
92
+ x: z.number().min(-1_000_000).max(1_000_000),
93
+ y: z.number().min(-1_000_000).max(1_000_000),
91
94
  kind: liveCursorKindSchema
92
95
  });
93
96
  export type LiveCursor = z.infer<typeof liveCursorSchema>;
94
97
 
98
+ /**
99
+ * Un canal de curseurs, `feature:clé` : ceux qui partagent la surface d'une vue
100
+ * plutôt que celle de la popup, d'où que vienne leur connexion. Seul le serveur
101
+ * d'un module y assied une connexion (`ctx.live.joinCursors`).
102
+ */
103
+ export const liveCursorChannelSchema = z
104
+ .string()
105
+ .max(96)
106
+ .regex(/^[a-z][a-z0-9-]*:[A-Za-z0-9_.-]{1,64}$/, 'Canal attendu sous la forme feature:clé');
107
+
95
108
  /**
96
109
  * Un pair tel qu'il est diffusé. Ni pseudo ni avatar : `users.avatar` est une
97
110
  * URL de données pouvant atteindre 1,5 Mo, et le roster repart à chaque
@@ -207,8 +220,10 @@ export const TOPIC_FEATURE: Record<NativeLiveTopic, WorkspaceFeatureId | null> =
207
220
  cve: 'cve',
208
221
  mailserver: 'mailserver',
209
222
  convert: 'convert',
223
+ pdf: 'pdf',
210
224
  invoicing: 'invoicing',
211
225
  shortlinks: 'shortlinks',
226
+ whiteboard: 'whiteboard',
212
227
  workspace: null,
213
228
  home: null,
214
229
  account: null,
@@ -102,6 +102,12 @@ export const workspaceFeatureIdSchema = z.enum([
102
102
  * ne voit les conversions d'un autre membre.
103
103
  */
104
104
  'convert',
105
+ /**
106
+ * PDF. `read` = l'atelier, qui travaille dans le navigateur, et ses
107
+ * signatures gardées sur le compte. Rien ne passe par le serveur, il n'y a
108
+ * rien à écrire.
109
+ */
110
+ 'pdf',
105
111
  /**
106
112
  * Facturation. `read` = consulter les clients, les devis, les factures et
107
113
  * les règlements. `write` = tenir le carnet, rédiger et corriger un
@@ -113,7 +119,13 @@ export const workspaceFeatureIdSchema = z.enum([
113
119
  * Liens courts. `read` = voir les liens et leurs statistiques, `write` =
114
120
  * créer un lien, changer sa destination et ses réglages, le supprimer.
115
121
  */
116
- 'shortlinks'
122
+ 'shortlinks',
123
+ /**
124
+ * Tableau blanc. `read` = voir les tableaux et suivre en direct qui y
125
+ * dessine, `write` = créer un tableau, dessiner, y coller des images, le
126
+ * renommer, le supprimer.
127
+ */
128
+ 'whiteboard'
117
129
  ]);
118
130
 
119
131
  export type WorkspaceFeatureId = z.infer<typeof workspaceFeatureIdSchema>;
@@ -62,11 +62,11 @@ export const agentPower = {
62
62
  };
63
63
 
64
64
  /**
65
- * Stop or cleanly restart the agent process on the device (not the machine).
66
- * `stop`: a supervised agent is relaunched by its manager, a standalone one
67
- * stays offline until relaunched on the machine. `restart`: exit-and-relaunch.
68
- * Needs `devices: write`; the agent must be online. Fire-and-forget: the outcome
69
- * is observed through presence.
65
+ * Act on the agent process of a device (not the machine): `restart`
66
+ * (exit-and-relaunch), `pause` (monitor nothing and take no order until
67
+ * resumed), `resume`. Needs `devices: write`; the agent must be online, or
68
+ * paused and reachable for `resume`. Fire-and-forget: the outcome is observed
69
+ * through presence and the device's `pause` field.
70
70
  */
71
71
  export const agentLifecycle = {
72
72
  command: 'agent.lifecycle' as const,
@@ -1,5 +1,12 @@
1
1
  import { z } from 'zod';
2
- import { liveCursorSchema, livePathSchema, livePeerSchema, liveTopicSchema } from '../domain/live';
2
+ import {
3
+ liveCursorChannelSchema,
4
+ liveCursorSchema,
5
+ livePathSchema,
6
+ livePeerSchema,
7
+ liveTopicSchema
8
+ } from '../domain/live';
9
+ import { userColorSchema } from '../domain/user';
3
10
 
4
11
  /**
5
12
  * Déclare où je suis, et récupère l'état de la salle. L'espace n'est pas dans
@@ -25,11 +32,16 @@ export const liveCommands = [liveHere] as const;
25
32
  export const LIVE_CURSOR_COMMAND = 'live.cursor' as const;
26
33
 
27
34
  /**
28
- * Ce que porte une trame de curseur : des coordonnées, rien d'autre. Ni chemin
29
- * ni espace : la voie rapide court-circuite l'autorisation, le lieu vient du
30
- * dernier `live.here`. `cursor: null` = le pointeur a quitté la surface.
35
+ * Ce que porte une trame de curseur : des coordonnées et leur surface, rien
36
+ * d'autre. Ni chemin ni espace : la voie rapide court-circuite l'autorisation,
37
+ * le lieu vient du dernier `live.here`. `cursor: null` = le pointeur a quitté la
38
+ * surface. `channel` nomme la surface d'une vue, `null` celle de la popup : une
39
+ * trame qui nomme un canal où la connexion n'est pas assise est ignorée.
31
40
  */
32
- export const liveCursorFrameSchema = z.object({ cursor: liveCursorSchema.nullable() });
41
+ export const liveCursorFrameSchema = z.object({
42
+ cursor: liveCursorSchema.nullable(),
43
+ channel: liveCursorChannelSchema.nullable()
44
+ });
33
45
  export type LiveCursorFrame = z.infer<typeof liveCursorFrameSchema>;
34
46
 
35
47
  /**
@@ -111,14 +123,25 @@ export const livePeersPushSchema = z.object({
111
123
  });
112
124
  export type LivePeersPush = z.infer<typeof livePeersPushSchema>;
113
125
 
114
- /** Curseurs des pairs situés au **même chemin exactement** que le destinataire. */
126
+ /**
127
+ * Curseurs des pairs qui partagent la surface du destinataire : ceux du **même
128
+ * chemin exactement**, ou ceux du même canal, d'où qu'ils viennent.
129
+ */
115
130
  export const LIVE_CURSORS_EVENT = 'live.cursors' as const;
116
131
  export const liveCursorsPushSchema = z.object({
117
132
  workspaceId: z.number().int().positive(),
133
+ /** La surface de ces positions : le canal, `null` pour la popup. */
134
+ channel: liveCursorChannelSchema.nullable(),
118
135
  cursors: z.array(
119
136
  z.object({
120
137
  connId: z.string().min(1),
121
138
  userId: z.number().int().positive(),
139
+ color: userColorSchema,
140
+ /**
141
+ * Le pseudo d'un pair de canal, qui peut venir d'un autre espace ;
142
+ * `null` sur la popup, où il se lit dans les membres de l'espace.
143
+ */
144
+ name: z.string().nullable(),
122
145
  cursor: liveCursorSchema
123
146
  })
124
147
  )
package/src/index.ts CHANGED
@@ -58,6 +58,8 @@ export {
58
58
  AGENT_DOCKER_STATS_RESULT,
59
59
  AGENT_LOG_SOURCES_RESULT,
60
60
  AGENT_METRICS_BATCH,
61
+ AGENT_PAUSED_HEADER,
62
+ AGENT_PAUSED_UNTIL_HEADER,
61
63
  AGENT_PKG_COUNT,
62
64
  AGENT_PKG_DONE,
63
65
  AGENT_PKG_LIST,
@@ -573,6 +575,7 @@ export type {
573
575
  ShortcutTemplate
574
576
  } from './domain/home';
575
577
  export {
578
+ liveCursorChannelSchema,
576
579
  liveCursorKindSchema,
577
580
  liveCursorSchema,
578
581
  livePathGate,
@@ -818,6 +818,16 @@ export type AgentTokenRotatePayload = z.infer<typeof agentTokenRotatePayloadSche
818
818
  * `CLOSE_PENDING_APPROVAL` in the agent's `runner.rs`.
819
819
  */
820
820
  export const AGENT_CLOSE_PENDING_APPROVAL = 4001;
821
+ /**
822
+ * Request headers of an agent connecting *paused* (`agent.lifecycle pause`,
823
+ * `deveye-agent pause`, or the tray icon): `x-deveye-paused: 1`, and the unix
824
+ * second the pause ends in `x-deveye-paused-until` when it has one. Such a
825
+ * session is control only: the server keeps it out of the online fleet, pushes
826
+ * it no work, and only `resume`, `restart`, a token rotation or a destroy
827
+ * reach it.
828
+ */
829
+ export const AGENT_PAUSED_HEADER = 'x-deveye-paused';
830
+ export const AGENT_PAUSED_UNTIL_HEADER = 'x-deveye-paused-until';
821
831
  /** Tell the agent to self-destruct (wipe its local config + binary) and exit. */
822
832
  export const AGENT_DESTROY = 'agent.destroy' as const;
823
833
  /** Tell the agent to download, verify and swap in a newer signed binary. */
@@ -840,17 +850,19 @@ export const agentUpdatePayloadSchema = z.object({
840
850
  export type AgentUpdatePayload = z.infer<typeof agentUpdatePayloadSchema>;
841
851
 
842
852
  /**
843
- * Ask the agent to stop or cleanly restart its own *process* (not the machine):
844
- * - `stop` exit now. Supervised (autostart service) → the manager relaunches
845
- * it; standalone → the device stays offline until a manual relaunch.
853
+ * Act on the agent's own *process* (not the machine):
846
854
  * - `restart` exit and come back: the manager relaunches a supervised agent, a
847
855
  * standalone one respawns itself first.
848
- * Fire-and-forget: no reply frame (the process exits) — the outcome is observed
849
- * through presence (offline, then online again for a restart).
856
+ * - `pause` stop monitoring and obeying until resumed: the agent closes its
857
+ * working session and reconnects paused (see `AGENT_PAUSED_HEADER`). The
858
+ * pause survives a restart of the agent and of the machine.
859
+ * - `resume` end the pause; only a paused agent takes it.
860
+ * Fire-and-forget: no reply frame. The outcome is observed through presence
861
+ * (`restart`) or the device's `pause` field.
850
862
  */
851
863
  export const AGENT_LIFECYCLE = 'agent.lifecycle' as const;
852
864
 
853
- export const agentLifecycleActionSchema = z.enum(['stop', 'restart']);
865
+ export const agentLifecycleActionSchema = z.enum(['restart', 'pause', 'resume']);
854
866
  export type AgentLifecycleAction = z.infer<typeof agentLifecycleActionSchema>;
855
867
 
856
868
  export const agentLifecyclePayloadSchema = z.object({ action: agentLifecycleActionSchema });
@@ -28,6 +28,7 @@ declare module 'deveye-sdk-client' {
28
28
  FeatureAccess,
29
29
  FeatureDomain,
30
30
  FeatureId,
31
+ LiveCursor,
31
32
  MinimalUser,
32
33
  PathExclusionKind,
33
34
  RequestProgress,
@@ -299,6 +300,12 @@ declare module 'deveye-sdk-client' {
299
300
  step?: number;
300
301
  label: string;
301
302
  valueLabel?: string;
303
+ /**
304
+ * A number field in place of `valueLabel`: the exact value is typed, at
305
+ * the same step. The slider's bounds are advice only: the field goes
306
+ * from 0 to far beyond.
307
+ */
308
+ editable?: boolean;
302
309
  marks?: readonly string[];
303
310
  indicator?: number;
304
311
  hint?: string;
@@ -689,8 +696,11 @@ declare module 'deveye-sdk-client' {
689
696
  file: File,
690
697
  onProgress: (ratio: number) => void
691
698
  ): UploadHandle;
692
- /** Downloads a URL served as an attachment, without leaving the page. */
693
- export function saveFrom(url: string): void;
699
+ /**
700
+ * Downloads a URL served as an attachment, without leaving the page.
701
+ * `name` names the file: a `blob:` URL made in the page has none.
702
+ */
703
+ export function saveFrom(url: string, name?: string): void;
694
704
  /** Opens the system picker; `folder` takes a whole folder, relative paths included. Cancelled: empty. */
695
705
  export function pickFiles(opts?: {
696
706
  multiple?: boolean;
@@ -846,6 +856,30 @@ declare module 'deveye-sdk-client' {
846
856
  input: z.input<Extract<M['commands'][number], { command: N }>['input'] & ZodType>,
847
857
  opts?: SendOptions
848
858
  ): Promise<z.output<Extract<M['commands'][number], { command: N }>['output'] & ZodType>>;
859
+ /**
860
+ * The same command, to a given workspace of one of the account's
861
+ * instances: `instanceId: null` for this one, else a remote instance
862
+ * the account is signed in to (`useRemoteTargets`). The targeted
863
+ * server judges the rights, and the application-code prompt, when it
864
+ * asks for one, is that account's. Rejects with `closed` when no
865
+ * session is open there.
866
+ */
867
+ sendTo<N extends M['commands'][number]['command']>(
868
+ target: { instanceId: number | null; workspaceId: number },
869
+ name: N,
870
+ input: z.input<Extract<M['commands'][number], { command: N }>['input'] & ZodType>,
871
+ opts?: Omit<SendOptions, 'workspaceId'>
872
+ ): Promise<z.output<Extract<M['commands'][number], { command: N }>['output'] & ZodType>>;
873
+ /**
874
+ * Fire and forget: no reply, no timeout, no trace entry. For what is
875
+ * re-sent several times a second (a pointer position); silently dropped
876
+ * while the socket is closed or backed up. The server still validates
877
+ * and checks access as for `send`.
878
+ */
879
+ post<N extends M['commands'][number]['command']>(
880
+ name: N,
881
+ input: z.input<Extract<M['commands'][number], { command: N }>['input'] & ZodType>
882
+ ): void;
849
883
  };
850
884
 
851
885
  // ── Password-based encryption (secrecy) ────────────────────────────────
@@ -1137,6 +1171,38 @@ declare module 'deveye-sdk-client' {
1137
1171
  name: string;
1138
1172
  features: readonly string[];
1139
1173
  }>;
1174
+ /** A remote instance of the account (another DevEye server it signs in to). */
1175
+ export interface RemoteInstanceSummary {
1176
+ id: number;
1177
+ label: string;
1178
+ origin: string;
1179
+ /** Why nothing can be sent there right now; `null` when it can. */
1180
+ unavailable: string | null;
1181
+ }
1182
+ /** A workspace of a remote instance: the `{ instanceId, workspaceId }` target of `sendTo`. */
1183
+ export interface RemoteWorkspaceTarget {
1184
+ /** Unique across the workspaces of every instance. */
1185
+ key: string;
1186
+ instanceId: number;
1187
+ instanceLabel: string;
1188
+ instanceOrigin: string;
1189
+ workspaceId: number;
1190
+ workspaceName: string;
1191
+ /** Its instance's. */
1192
+ unavailable: string | null;
1193
+ }
1194
+ export interface RemoteTargets {
1195
+ instances: readonly RemoteInstanceSummary[];
1196
+ workspaces: readonly RemoteWorkspaceTarget[];
1197
+ }
1198
+ /**
1199
+ * The account's remote instances and their workspaces, probed while the
1200
+ * component is mounted. The two servers never talk to each other: this
1201
+ * browser carries a `sendTo` command to the instance chosen, on the
1202
+ * socket it holds there. Signed out of one, its workspaces are those last
1203
+ * seen, named but not targetable.
1204
+ */
1205
+ export function useRemoteTargets(): RemoteTargets;
1140
1206
  /**
1141
1207
  * The domains of a feature whose manifest declares `domains`, in the
1142
1208
  * active workspace, kept live. For a form that designates one (filter on
@@ -1199,6 +1265,19 @@ declare module 'deveye-sdk-client' {
1199
1265
  * is the host's; a missing item is ignored after a short grace.
1200
1266
  */
1201
1267
  export function openFeature(feature: string, itemId?: number | string): void;
1268
+ /** A file one feature hands to another, with what the recipient should do with it, in its own terms. */
1269
+ export interface HandedFile {
1270
+ file: File;
1271
+ purpose: string | null;
1272
+ }
1273
+ /**
1274
+ * Hands a file to another feature and opens it: the recipient picks it up
1275
+ * through `useHandedFile`. The parcel waits in memory, is taken once, and
1276
+ * never outlives the page.
1277
+ */
1278
+ export function handFileTo(feature: string, file: File, purpose?: string | null): void;
1279
+ /** Picks up the file handed to `feature`: the one waiting at mount, and those arriving while the view is open. */
1280
+ export function useHandedFile(feature: string, onFile: (parcel: HandedFile) => void): void;
1202
1281
  /**
1203
1282
  * Ask the feature popup for a wider frame (px) while the calling
1204
1283
  * component is mounted, `null` to ask for nothing. Several requests
@@ -1206,6 +1285,39 @@ declare module 'deveye-sdk-client' {
1206
1285
  * (a table explorer in expanded mode).
1207
1286
  */
1208
1287
  export function useRequestPopupWidth(px: number | null): void;
1288
+ /**
1289
+ * A view's own cursor surface: where DevEye's live cursors are placed,
1290
+ * instead of the popup. For a canvas each viewer pans and zooms, where a
1291
+ * point relative to the popup designates nothing. Your coordinates are
1292
+ * yours (a scene's), within a million either way.
1293
+ */
1294
+ export interface LiveCursorSurface {
1295
+ /** The cursor channel your server seated this connection in (`ctx.live.joinCursors`). */
1296
+ channel: string;
1297
+ /** A screen point (client pixels) in your coordinates; `null` off the surface. */
1298
+ fromScreen(clientX: number, clientY: number): { x: number; y: number } | null;
1299
+ /** Back to client pixels; `null` where the surface does not show it. */
1300
+ toScreen(x: number, y: number): { x: number; y: number } | null;
1301
+ /** Calls `onChange` whenever `toScreen` would answer differently (a pan, a zoom). */
1302
+ subscribe(onChange: () => void): () => void;
1303
+ }
1304
+ /**
1305
+ * Places DevEye's live cursors on `surface` while the calling view is the
1306
+ * one open: the same cursors, cadence, glide, bubble and account switch as
1307
+ * anywhere else, between the connections seated in `surface.channel`
1308
+ * rather than the peers at the same path. `null` gives the popup back. Pass
1309
+ * a stable object: a new one re-declares the surface.
1310
+ */
1311
+ export function useLiveCursorSurface(surface: LiveCursorSurface | null): void;
1312
+ /**
1313
+ * The peers' raw positions in `channel`, as they arrive (about twenty times
1314
+ * a second), for what your view draws with them (a laser trail). DevEye
1315
+ * draws the cursors themselves.
1316
+ */
1317
+ export function onLiveCursors(
1318
+ channel: string,
1319
+ cb: (cursors: readonly { connId: string; userId: number; cursor: LiveCursor }[]) => void
1320
+ ): () => void;
1209
1321
 
1210
1322
  // Change events re-exported for convenience in handlers.
1211
1323
  export type InputChange = ChangeEvent<HTMLInputElement>;
package/src/sdk/client.ts CHANGED
@@ -93,6 +93,11 @@ export interface FeatureClient {
93
93
  * Panels for the manifest's settings tabs that need one: `'general'`,
94
94
  * `'sources'`, `'encryption'`, and any custom tab id. Generic tabs
95
95
  * (`'notifications'`, `'permissions'`) need no panel.
96
+ *
97
+ * `'sharing'` is not a tab of yours: the shell draws its own sharing tab
98
+ * for an item, and a panel under this id is appended below it, for a
99
+ * gesture that extends sharing (Devices: enrolling the machine on a
100
+ * remote instance too).
96
101
  */
97
102
  settingsPanels?: Readonly<Record<string, ComponentType<SettingsPanelProps>>>;
98
103
  /**
@@ -477,6 +482,43 @@ export interface HostingClientProvider {
477
482
  }>;
478
483
  }
479
484
 
485
+ /** A board of the workspace, as the Whiteboard client provider lists it for a project's picker. */
486
+ export interface WhiteboardLinkedCandidate {
487
+ id: number;
488
+ name: string;
489
+ /** Projected here from another workspace. */
490
+ foreign?: boolean;
491
+ }
492
+
493
+ /**
494
+ * What the Whiteboard module offers the host's screens under
495
+ * `WHITEBOARD_CLIENT_PROVIDER`: the workspace's boards, a linked board shown
496
+ * inside a project's tab, and the feature's own board dialog.
497
+ */
498
+ export interface WhiteboardClientProvider {
499
+ /** The workspace's boards, in the module's own order. */
500
+ listBoards(): Promise<readonly WhiteboardLinkedCandidate[]>;
501
+ /**
502
+ * The given boards, summarised for a project's dashboard tile, in ONE
503
+ * round trip. An id the caller cannot read, or that is gone, comes back
504
+ * `unavailable`, never as a throw.
505
+ */
506
+ summarize(boardIds: readonly number[]): Promise<readonly SdkTileSummary[]>;
507
+ /**
508
+ * A board linked to a project: its title, its preview, when it last
509
+ * changed, and the way into the editor. Loads itself, follows the
510
+ * feature's invalidations, and renders the host's "unlink" as its
511
+ * trailing action.
512
+ */
513
+ LinkedBoard: ComponentType<{ boardId: number; canWrite: boolean; onUnlink: () => void }>;
514
+ /** The feature's board form, to create a board from a project. */
515
+ BoardDialog: ComponentType<{
516
+ open: boolean;
517
+ onClose: () => void;
518
+ onSaved: (boardId: number) => void;
519
+ }>;
520
+ }
521
+
480
522
  /**
481
523
  * What the Invoicing module offers other screens under
482
524
  * `INVOICING_CLIENT_PROVIDER`. It sends Invoicing's own command under the
@@ -258,7 +258,7 @@ export interface FeatureLink {
258
258
  }
259
259
 
260
260
  /** Hard cap on `links`: the "About" card stays a card. */
261
- export const MAX_FEATURE_LINKS = 6;
261
+ export const MAX_FEATURE_LINKS = 7;
262
262
 
263
263
  export interface FeatureManifest<Id extends FeatureId = FeatureId> {
264
264
  /** External modules: `x-<slug>`. Native features keep their enum id. */
@@ -638,6 +638,32 @@ export interface HostingItemsProvider {
638
638
  */
639
639
  export const HOSTING_CLIENT_PROVIDER = 'hosting.client' as const;
640
640
 
641
+ /**
642
+ * Key under `FeatureService.providers` for the whiteboards the app's Projects
643
+ * feature links to: same shape and same reason as `UPTIME_ITEMS_PROVIDER`
644
+ * (`ft_projects_whiteboard_links` is Projects' table).
645
+ */
646
+ export const WHITEBOARD_ITEMS_PROVIDER = 'whiteboard.items' as const;
647
+
648
+ export interface WhiteboardItemsProvider {
649
+ /** Is this board visible from this workspace: its home, or one it is projected into? */
650
+ exists(boardId: number, workspaceId: number): Promise<boolean>;
651
+ /**
652
+ * The item's display name as seen from `workspaceId` (its home, or a
653
+ * workspace it is projected into): the provider resolves the home and its
654
+ * OPEN cipher itself. `null` when it is gone or unreadable.
655
+ */
656
+ labelOf(boardId: number, workspaceId: number): Promise<string | null>;
657
+ }
658
+
659
+ /**
660
+ * Key under `FeatureClient.providers` for the Whiteboard pieces the app's
661
+ * Projects screens compose: the list of the workspace's boards, a linked
662
+ * board shown inside a project's tab, and the feature's own board dialog.
663
+ * The contract types live in `@deveye/types/sdk/client`.
664
+ */
665
+ export const WHITEBOARD_CLIENT_PROVIDER = 'whiteboard.client' as const;
666
+
641
667
  /**
642
668
  * Key of what Projects knows about the items of OTHER features: the projects
643
669
  * of the workspace that link them (a module's list shows how many projects use
package/src/sdk/server.ts CHANGED
@@ -419,6 +419,8 @@ export interface DevEyeFacade {
419
419
  */
420
420
  list(): Promise<readonly SdkDevice[]>;
421
421
  isOnline(deviceId: string): boolean;
422
+ /** The agent is paused and its control session is connected: offline for every purpose but a resume. */
423
+ isPaused(deviceId: string): boolean;
422
424
  };
423
425
  /** Requires capability `'telemetry.read'` (native-id modules only). */
424
426
  telemetry: SdkTelemetry;
@@ -679,6 +681,8 @@ export interface SdkWorkspaceSummary {
679
681
  */
680
682
  export interface AgentsFacade {
681
683
  isOnline(deviceId: string): boolean;
684
+ /** The agent is paused and its control session is connected (never online at the same time). */
685
+ isPaused(deviceId: string): boolean;
682
686
  /**
683
687
  * The two orders a device's lifecycle gives the hub. `requestDestroy`
684
688
  * asks the agent to uninstall itself (deletion path); `disconnectAgent`
@@ -1119,6 +1123,18 @@ export interface SdkLive {
1119
1123
  * is never attached, so it can never be mistaken for a reply.
1120
1124
  */
1121
1125
  publish(workspaceId: number, event: string, payload: unknown): void;
1126
+ /**
1127
+ * {@link SdkLive.publish}, narrowed to the connections of these accounts:
1128
+ * the participants of something open, when the rest of the room may not
1129
+ * see it (an item its role hides from a member). An empty list sends
1130
+ * nothing.
1131
+ */
1132
+ publishTo(
1133
+ workspaceId: number,
1134
+ userIds: readonly number[],
1135
+ event: string,
1136
+ payload: unknown
1137
+ ): void;
1122
1138
  /** {@link SdkContextLive.accountChanged}, from a service (a webhook, a ticker). */
1123
1139
  accountChanged(userId: number): void;
1124
1140
  /** {@link SdkContextLive.pendingChanged}, from a service or a public route (a report just filed). */
@@ -1133,6 +1149,24 @@ export interface SdkLive {
1133
1149
  export interface SdkContextLive {
1134
1150
  /** {@link SdkLive.publish}, in the workspace of the call. */
1135
1151
  publish(event: string, payload: unknown): void;
1152
+ /**
1153
+ * Seats the caller's connection in YOUR cursor channel `key` (capability
1154
+ * `'live.publish'`): for a view with its own cursor surface (a canvas
1155
+ * each viewer pans and zooms), whose participants may sit in different
1156
+ * workspaces (a projected item). While the client declares that surface
1157
+ * (`useLiveCursorSurface`), DevEye's cursors and bubble go between the
1158
+ * connections seated there, and only them. Check first that the caller
1159
+ * may see the item: the host checks nothing more. The seat lasts until
1160
+ * {@link SdkContextLive.leaveCursors}, a switch to another workspace, the
1161
+ * loss of `read` on your feature or the socket closing.
1162
+ *
1163
+ * Resolves with the channel to hand the client and the caller's
1164
+ * connection id, the one its cursor carries to the others; `null` outside
1165
+ * a browser socket (a test), where there is nothing to seat.
1166
+ */
1167
+ joinCursors(key: string): Promise<{ channel: string; connId: string } | null>;
1168
+ /** Gets the caller's connection out of the cursor channel `key`, if it sits there. */
1169
+ leaveCursors(key: string): void;
1136
1170
  /**
1137
1171
  * Something of this ACCOUNT changed (its plan, its subscription): its open
1138
1172
  * clients, in whatever workspace they sit, re-fetch the account plan and
@@ -1153,6 +1187,8 @@ export interface SdkFleetDevices {
1153
1187
  /** One device by id, whatever its workspace, or null. */
1154
1188
  find(deviceId: string): Promise<SdkDevice | null>;
1155
1189
  isOnline(deviceId: string): boolean;
1190
+ /** The agent is paused and its control session is connected: offline for every purpose but a resume. */
1191
+ isPaused(deviceId: string): boolean;
1156
1192
  }
1157
1193
 
1158
1194
  /**
@@ -139,8 +139,13 @@ export interface RecordedCalls {
139
139
  }[];
140
140
  /** Instants pinned through `telemetry.pinInstant`. */
141
141
  pinnedInstants: { deviceId: string; ts: number }[];
142
- /** Frames pushed through `live.publish`, in order. */
143
- livePublishes: { workspaceId: number; event: string; payload: unknown }[];
142
+ /** Frames pushed through `live.publish` and `live.publishTo` (with its `userIds`), in order. */
143
+ livePublishes: {
144
+ workspaceId: number;
145
+ event: string;
146
+ payload: unknown;
147
+ userIds?: readonly number[];
148
+ }[];
144
149
  /** Accounts beaten through `live.accountChanged`, in order. */
145
150
  accountChanges: number[];
146
151
  /** How many times `live.pendingChanged` was called. */
@@ -225,7 +230,8 @@ function recordingDevices(
225
230
  : Promise.resolve(devices.find((d) => d.id === id) ?? testDevice({ id })),
226
231
  assertControl: () => Promise.resolve(),
227
232
  list: () => Promise.resolve([...devices]),
228
- isOnline: (id) => devices.find((d) => d.id === id)?.online ?? true
233
+ isOnline: (id) => devices.find((d) => d.id === id)?.online ?? true,
234
+ isPaused: () => false
229
235
  };
230
236
  }
231
237
 
@@ -295,6 +301,7 @@ function recordingAgents(recorded: RecordedCalls, docker: TestAgents = {}): DevE
295
301
  };
296
302
  return {
297
303
  isOnline: () => true,
304
+ isPaused: () => false,
298
305
  requestScan: req('requestScan'),
299
306
  pushConfig: (deviceId) => Promise.resolve(req('pushConfig')(deviceId)),
300
307
  // The app's rule with the harness's plan: paid unless `paid: false`.
@@ -646,6 +653,9 @@ export function createTestContext<Repo = undefined>(
646
653
  publish(event, payload) {
647
654
  recorded.livePublishes.push({ workspaceId, event, payload });
648
655
  },
656
+ // No browser socket here, as in a test of the real host: nobody to seat.
657
+ joinCursors: () => Promise.resolve(null),
658
+ leaveCursors: () => undefined,
649
659
  accountChanged(userId) {
650
660
  recorded.accountChanges.push(userId);
651
661
  },
@@ -917,14 +927,19 @@ export function createTestServiceDeps<Repo = undefined>(
917
927
  });
918
928
  }
919
929
  },
920
- devicesFor: () => ({ list: devices.list, isOnline: devices.isOnline }),
930
+ devicesFor: () => ({
931
+ list: devices.list,
932
+ isOnline: devices.isOnline,
933
+ isPaused: devices.isPaused
934
+ }),
921
935
  membersFor: (workspaceId) => ({
922
936
  list: () => Promise.resolve(overrides.members?.[workspaceId] ?? [])
923
937
  }),
924
938
  devices: {
925
939
  find: (id) =>
926
940
  Promise.resolve((overrides.devices ?? []).find((d) => d.id === id) ?? null),
927
- isOnline: devices.isOnline
941
+ isOnline: devices.isOnline,
942
+ isPaused: devices.isPaused
928
943
  },
929
944
  telemetry: recordingTelemetry(recorded, overrides.snapshots ?? []),
930
945
  geo: {
@@ -939,6 +954,9 @@ export function createTestServiceDeps<Repo = undefined>(
939
954
  publish(workspaceId, event, payload) {
940
955
  recorded.livePublishes.push({ workspaceId, event, payload });
941
956
  },
957
+ publishTo(workspaceId, userIds, event, payload) {
958
+ recorded.livePublishes.push({ workspaceId, event, payload, userIds: [...userIds] });
959
+ },
942
960
  accountChanged(userId) {
943
961
  recorded.accountChanges.push(userId);
944
962
  },