@mostra/protocol 0.10.0 → 0.12.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 (129) hide show
  1. package/dist/actions.d.ts +11 -3
  2. package/dist/actions.d.ts.map +1 -1
  3. package/dist/actions.js.map +1 -1
  4. package/dist/browser.d.ts +43 -1
  5. package/dist/browser.d.ts.map +1 -1
  6. package/dist/browser.js +29 -1
  7. package/dist/browser.js.map +1 -1
  8. package/dist/diagnostics/codes/action.d.ts +1 -1
  9. package/dist/diagnostics/codes/action.d.ts.map +1 -1
  10. package/dist/diagnostics/codes/action.js +12 -1
  11. package/dist/diagnostics/codes/action.js.map +1 -1
  12. package/dist/diagnostics/codes/index.d.ts +3 -2
  13. package/dist/diagnostics/codes/index.d.ts.map +1 -1
  14. package/dist/diagnostics/codes/index.js +3 -1
  15. package/dist/diagnostics/codes/index.js.map +1 -1
  16. package/dist/diagnostics/codes/remote.d.ts +1 -1
  17. package/dist/diagnostics/codes/remote.d.ts.map +1 -1
  18. package/dist/diagnostics/codes/remote.js +78 -1
  19. package/dist/diagnostics/codes/remote.js.map +1 -1
  20. package/dist/diagnostics/codes/submit.d.ts +1 -1
  21. package/dist/diagnostics/codes/submit.d.ts.map +1 -1
  22. package/dist/diagnostics/codes/submit.js +12 -1
  23. package/dist/diagnostics/codes/submit.js.map +1 -1
  24. package/dist/diagnostics/codes/team.d.ts +8 -0
  25. package/dist/diagnostics/codes/team.d.ts.map +1 -0
  26. package/dist/diagnostics/codes/team.js +44 -0
  27. package/dist/diagnostics/codes/team.js.map +1 -0
  28. package/dist/diagnostics/diagnostic.d.ts +1 -1
  29. package/dist/diagnostics/diagnostic.d.ts.map +1 -1
  30. package/dist/diagnostics/diagnostic.js +2 -1
  31. package/dist/diagnostics/diagnostic.js.map +1 -1
  32. package/dist/index.d.ts +17 -7
  33. package/dist/index.js +14 -4
  34. package/dist/interaction.d.ts +17 -3
  35. package/dist/interaction.d.ts.map +1 -1
  36. package/dist/interaction.js +17 -13
  37. package/dist/interaction.js.map +1 -1
  38. package/dist/manifest.d.ts +3 -0
  39. package/dist/manifest.d.ts.map +1 -1
  40. package/dist/manifest.js +5 -2
  41. package/dist/manifest.js.map +1 -1
  42. package/dist/methods/artifact/pause.d.ts +33 -0
  43. package/dist/methods/artifact/pause.d.ts.map +1 -0
  44. package/dist/methods/artifact/pause.js +33 -0
  45. package/dist/methods/artifact/pause.js.map +1 -0
  46. package/dist/methods/index.d.ts.map +1 -1
  47. package/dist/methods/index.js +16 -2
  48. package/dist/methods/index.js.map +1 -1
  49. package/dist/methods/port/relay-author.d.ts +28 -0
  50. package/dist/methods/port/relay-author.d.ts.map +1 -0
  51. package/dist/methods/port/relay-author.js +42 -0
  52. package/dist/methods/port/relay-author.js.map +1 -0
  53. package/dist/methods/port/trusted-controls-policy.d.ts +1 -1
  54. package/dist/methods/remote/link.d.ts +40 -0
  55. package/dist/methods/remote/link.d.ts.map +1 -0
  56. package/dist/methods/remote/link.js +40 -0
  57. package/dist/methods/remote/link.js.map +1 -0
  58. package/dist/methods/results/get.d.ts +3 -1
  59. package/dist/methods/results/get.d.ts.map +1 -1
  60. package/dist/methods/results/get.js +4 -3
  61. package/dist/methods/results/get.js.map +1 -1
  62. package/dist/methods/results/list.d.ts +33 -0
  63. package/dist/methods/results/list.d.ts.map +1 -0
  64. package/dist/methods/results/list.js +35 -0
  65. package/dist/methods/results/list.js.map +1 -0
  66. package/dist/methods/roster/add.d.ts +47 -0
  67. package/dist/methods/roster/add.d.ts.map +1 -0
  68. package/dist/methods/roster/add.js +46 -0
  69. package/dist/methods/roster/add.js.map +1 -0
  70. package/dist/methods/roster/get.d.ts +18 -0
  71. package/dist/methods/roster/get.d.ts.map +1 -0
  72. package/dist/methods/roster/get.js +22 -0
  73. package/dist/methods/roster/get.js.map +1 -0
  74. package/dist/methods/roster/remove.d.ts +28 -0
  75. package/dist/methods/roster/remove.d.ts.map +1 -0
  76. package/dist/methods/roster/remove.js +31 -0
  77. package/dist/methods/roster/remove.js.map +1 -0
  78. package/dist/methods/share/start.d.ts +15 -2
  79. package/dist/methods/share/start.d.ts.map +1 -1
  80. package/dist/methods/share/start.js +5 -1
  81. package/dist/methods/share/start.js.map +1 -1
  82. package/dist/methods/state/get.d.ts +1 -1
  83. package/dist/methods/state/patch.d.ts +1 -1
  84. package/dist/methods/view/url.d.ts +1 -1
  85. package/dist/methods/wait/wait.d.ts +1 -1
  86. package/dist/operator.d.ts +511 -0
  87. package/dist/operator.d.ts.map +1 -0
  88. package/dist/operator.js +134 -0
  89. package/dist/operator.js.map +1 -0
  90. package/dist/team-settings.d.ts +21 -0
  91. package/dist/team-settings.d.ts.map +1 -0
  92. package/dist/team-settings.js +27 -0
  93. package/dist/team-settings.js.map +1 -0
  94. package/dist/team.d.ts +221 -0
  95. package/dist/team.d.ts.map +1 -0
  96. package/dist/team.js +162 -0
  97. package/dist/team.js.map +1 -0
  98. package/dist/verify.d.ts +7 -0
  99. package/dist/verify.d.ts.map +1 -1
  100. package/dist/verify.js.map +1 -1
  101. package/dist/worker.d.ts +1 -1
  102. package/package.json +11 -1
  103. package/schemas/protocol.draft-07.json +1027 -45
  104. package/schemas/protocol.schema.json +996 -46
  105. package/src/actions.ts +8 -4
  106. package/src/browser.ts +64 -0
  107. package/src/diagnostics/codes/action.ts +12 -0
  108. package/src/diagnostics/codes/index.ts +6 -2
  109. package/src/diagnostics/codes/remote.ts +84 -0
  110. package/src/diagnostics/codes/submit.ts +12 -0
  111. package/src/diagnostics/codes/team.ts +53 -0
  112. package/src/diagnostics/diagnostic.ts +3 -1
  113. package/src/index.ts +66 -2
  114. package/src/interaction.ts +30 -5
  115. package/src/manifest.ts +5 -0
  116. package/src/methods/artifact/pause.ts +59 -0
  117. package/src/methods/index.ts +14 -0
  118. package/src/methods/port/relay-author.ts +57 -0
  119. package/src/methods/remote/link.ts +65 -0
  120. package/src/methods/results/get.ts +3 -2
  121. package/src/methods/results/list.ts +61 -0
  122. package/src/methods/roster/add.ts +77 -0
  123. package/src/methods/roster/get.ts +30 -0
  124. package/src/methods/roster/remove.ts +49 -0
  125. package/src/methods/share/start.ts +23 -3
  126. package/src/operator.ts +660 -0
  127. package/src/team-settings.ts +38 -0
  128. package/src/team.ts +398 -0
  129. package/src/verify.ts +7 -0
@@ -0,0 +1,38 @@
1
+ /**
2
+ * The manifest's `team` settings (D168): a module of its own, with no other import of the
3
+ * protocol, so the manifest reads them without the team wire types.
4
+ */
5
+ import * as z from "zod";
6
+ import { wireRegistry } from "./wire-registry.ts";
7
+
8
+ /**
9
+ * What viewers see of each other's respondent status and presence (CO-07, D168): `private` (their
10
+ * own entry only), `counts` (their own entry and how many stand where), `names` (everyone's name and
11
+ * status). The manifest's `team.visibility`; owners, agents and hosts always see everything.
12
+ */
13
+ export type TeamVisibility = "private" | "counts" | "names";
14
+
15
+ /** The Zod schema of the `TeamVisibility` type. */
16
+ export const TeamVisibility: z.ZodType<TeamVisibility> = z
17
+ .enum(["private", "counts", "names"])
18
+ .register(wireRegistry, {
19
+ id: "TeamVisibility",
20
+ description: "What viewers see of each other: private, counts or names (D168).",
21
+ });
22
+
23
+ /** The visibility an artifact gets when its manifest names none (D168: private unless it opts in). */
24
+ export const DEFAULT_TEAM_VISIBILITY: TeamVisibility = "private";
25
+
26
+ /** The manifest's `team` settings (D168). */
27
+ export interface TeamSettings {
28
+ /** What viewers see of each other's status and presence; default `private`. */
29
+ readonly visibility?: TeamVisibility;
30
+ }
31
+
32
+ /** The Zod schema of the `TeamSettings` type. */
33
+ export const TeamSettings: z.ZodType<TeamSettings> = z
34
+ .object({ visibility: TeamVisibility.exactOptional() })
35
+ .register(wireRegistry, {
36
+ id: "TeamSettings",
37
+ description: "An artifact's team settings: what viewers see of each other (D168).",
38
+ });
package/src/team.ts ADDED
@@ -0,0 +1,398 @@
1
+ /**
2
+ * Team features (D121, D168; INTERFACES §2.3, §4, §6): expected respondents and their roster,
3
+ * respondent status, the visibility policy, and presence. The host protocol's `roster/*` methods,
4
+ * the browser protocol's `respondents` and `presence` routes and the client hooks
5
+ * (`useRespondents`, `usePresence`) speak these shapes. Presence is never stored (D47): its shapes
6
+ * travel only as ephemeral messages and answers.
7
+ */
8
+ import * as z from "zod";
9
+ import { SubmissionId, ViewerId, ViewId } from "./ids.ts";
10
+ import { ViewerKind } from "./interaction.ts";
11
+ import { DEFAULT_TEAM_VISIBILITY, TeamSettings, TeamVisibility } from "./team-settings.ts";
12
+ import { wireRegistry } from "./wire-registry.ts";
13
+
14
+ export { DEFAULT_TEAM_VISIBILITY, TeamSettings, TeamVisibility };
15
+
16
+ // ── Respondents ──────────────────────────────────────────────────────────────────────────────
17
+
18
+ /** The most expected respondents one artifact's roster holds. */
19
+ export const ROSTER_MAX = 1000;
20
+
21
+ /**
22
+ * An expected respondent as a host or agent names them (D121): the host's stable key for the
23
+ * person (`view/url`'s `viewer.ref`, D104), their display name, and an email address a remote
24
+ * server may send an invitation to (its operator's `invitations` port; nothing is sent locally).
25
+ */
26
+ export interface RespondentSpec {
27
+ /** The host's stable key for this person, such as an email or an account ID (D104). */
28
+ readonly ref: string;
29
+ /** The name people see; updated when given again. */
30
+ readonly name?: string;
31
+ /** Where a remote server's operator may send this person's invitation. Never sent by Mostra. */
32
+ readonly email?: string;
33
+ }
34
+
35
+ /** The Zod schema of the `RespondentSpec` type. */
36
+ export const RespondentSpec: z.ZodType<RespondentSpec> = z
37
+ .object({
38
+ ref: z.string().min(1).max(256),
39
+ name: z.string().min(1).max(256).exactOptional(),
40
+ email: z
41
+ .string()
42
+ .max(320)
43
+ .regex(/^[^\s@]+@[^\s@]+$/)
44
+ .exactOptional(),
45
+ })
46
+ .register(wireRegistry, {
47
+ id: "RespondentSpec",
48
+ description: "An expected respondent: the host's stable key, a display name, an email.",
49
+ });
50
+
51
+ /**
52
+ * Where an expected respondent stands in the roster's current round (CO-03): `not-opened` (no view
53
+ * of the artifact since the round began), `drafting` (opened it or wrote their draft since), or
54
+ * `submitted` (a submission in the round). Open for later states on the wire.
55
+ */
56
+ export type RespondentStatus = "not-opened" | "drafting" | "submitted";
57
+
58
+ /** The Zod schema of the `RespondentStatus` type. */
59
+ export const RespondentStatus: z.ZodType<RespondentStatus> = z
60
+ .enum(["not-opened", "drafting", "submitted"])
61
+ .register(wireRegistry, {
62
+ id: "RespondentStatus",
63
+ description: "Where a respondent stands in the round: not-opened, drafting or submitted.",
64
+ });
65
+
66
+ /** How many respondents stand where, in the current round. */
67
+ export interface RosterCounts {
68
+ /** Every expected respondent. */
69
+ readonly total: number;
70
+ /** How many haven't opened the artifact in the round. */
71
+ readonly notOpened: number;
72
+ /** How many opened it or wrote their draft in the round, without submitting. */
73
+ readonly drafting: number;
74
+ /** How many submitted in the round. */
75
+ readonly submitted: number;
76
+ }
77
+
78
+ /** The Zod schema of the `RosterCounts` type. */
79
+ export const RosterCounts: z.ZodType<RosterCounts> = z
80
+ .object({
81
+ total: z.int().min(0),
82
+ notOpened: z.int().min(0),
83
+ drafting: z.int().min(0),
84
+ submitted: z.int().min(0),
85
+ })
86
+ .register(wireRegistry, {
87
+ id: "RosterCounts",
88
+ description: "How many respondents have not opened, are drafting, or submitted in the round.",
89
+ });
90
+
91
+ /** One expected respondent as agents and hosts read it (`roster/get`): everything. */
92
+ export interface Respondent {
93
+ /** The host's stable key for the person. */
94
+ readonly ref: string;
95
+ /** The display name. */
96
+ readonly name?: string;
97
+ /** The invitation address, when one was given. */
98
+ readonly email?: string;
99
+ /** The viewer the person's personal link acts as (D104). */
100
+ readonly viewerId: string;
101
+ /** Where they stand in the current round. */
102
+ readonly status: RespondentStatus;
103
+ /** When they first opened the artifact. */
104
+ readonly openedAt?: string;
105
+ /** When they last opened it or wrote their draft. */
106
+ readonly activeAt?: string;
107
+ /** Their submission in the current round, when they made one. */
108
+ readonly submission?: { readonly id: string; readonly at: string };
109
+ /** How many submissions they made in all. */
110
+ readonly submissions: number;
111
+ /** Their personal link's token, for `view/rotate` and `view/revoke`; absent once revoked. */
112
+ readonly tokenId?: string;
113
+ /** When they joined the roster. */
114
+ readonly addedAt: string;
115
+ }
116
+
117
+ /** The Zod schema of the `Respondent` type. */
118
+ export const Respondent: z.ZodType<Respondent> = z
119
+ .object({
120
+ ref: z.string(),
121
+ name: z.string().exactOptional(),
122
+ email: z.string().exactOptional(),
123
+ viewerId: ViewerId.schema,
124
+ status: RespondentStatus,
125
+ openedAt: z.iso.datetime().exactOptional(),
126
+ activeAt: z.iso.datetime().exactOptional(),
127
+ submission: z.object({ id: SubmissionId.schema, at: z.iso.datetime() }).exactOptional(),
128
+ submissions: z.int().min(0),
129
+ tokenId: z.string().exactOptional(),
130
+ addedAt: z.iso.datetime(),
131
+ })
132
+ .register(wireRegistry, {
133
+ id: "Respondent",
134
+ description:
135
+ "An expected respondent as agents and hosts read it: name, viewer, status and submission.",
136
+ });
137
+
138
+ /** An artifact's roster as agents and hosts read it (`roster/get`). */
139
+ export interface Roster {
140
+ /** The roster's round (D168): always 1 under `once`; under `epochs`, one more after each completion. */
141
+ readonly round: number;
142
+ /** Whether every expected respondent has submitted in the round; an empty roster never has. */
143
+ readonly complete: boolean;
144
+ /** What viewers see of each other (the manifest's `team.visibility`). */
145
+ readonly visibility: TeamVisibility;
146
+ /** How many stand where in the round. */
147
+ readonly counts: RosterCounts;
148
+ /** Every expected respondent, in the order they joined. */
149
+ readonly respondents: readonly Respondent[];
150
+ }
151
+
152
+ /** The Zod schema of the `Roster` type. */
153
+ export const Roster: z.ZodType<Roster> = z
154
+ .object({
155
+ round: z.int().min(1),
156
+ complete: z.boolean(),
157
+ visibility: TeamVisibility,
158
+ counts: RosterCounts,
159
+ respondents: z.array(Respondent).readonly(),
160
+ })
161
+ .register(wireRegistry, {
162
+ id: "Roster",
163
+ description: "An artifact's expected respondents with their status, the round and its counts.",
164
+ });
165
+
166
+ /**
167
+ * Another viewer as a page may see them: an opaque key that is stable for one viewer of one
168
+ * artifact (never a viewer or view ID, D104), their display name and how Mostra knows them.
169
+ */
170
+ export interface Peer {
171
+ /** Stable for one viewer of one artifact, different across artifacts; `self` marks the page's own. */
172
+ readonly key: string;
173
+ /** Whether this is the page's own viewer. */
174
+ readonly self: boolean;
175
+ /** The display name, when one is known. */
176
+ readonly name?: string;
177
+ /** How Mostra knows the viewer. */
178
+ readonly kind: ViewerKind;
179
+ /** On a hosted link: whether a provider verified the name (D165 item 8). */
180
+ readonly verified?: boolean;
181
+ }
182
+
183
+ const peerShape = {
184
+ key: z.string().min(1).max(64),
185
+ self: z.boolean(),
186
+ name: z.string().exactOptional(),
187
+ kind: ViewerKind,
188
+ verified: z.boolean().exactOptional(),
189
+ };
190
+
191
+ /** One respondent as a page sees them under the visibility policy. */
192
+ export interface RespondentForPage extends Peer {
193
+ /** Where they stand in the round. */
194
+ readonly status: RespondentStatus;
195
+ /** When they first opened the artifact. */
196
+ readonly openedAt?: string;
197
+ /** When they submitted in the round. */
198
+ readonly submittedAt?: string;
199
+ }
200
+
201
+ /** The Zod schema of the `RespondentForPage` type. */
202
+ export const RespondentForPage: z.ZodType<RespondentForPage> = z
203
+ .object({
204
+ ...peerShape,
205
+ status: RespondentStatus,
206
+ openedAt: z.iso.datetime().exactOptional(),
207
+ submittedAt: z.iso.datetime().exactOptional(),
208
+ })
209
+ .register(wireRegistry, {
210
+ id: "RespondentForPage",
211
+ description: "A respondent as a page sees them: key, name, status, when opened and submitted.",
212
+ });
213
+
214
+ /**
215
+ * The roster as one page may see it (CO-03, CO-07): under `private` only the viewer's own entry,
216
+ * under `counts` also the counts and whether the round is complete, under `names` every respondent.
217
+ * The owner's page sees as under `names`.
218
+ */
219
+ export interface RosterForPage {
220
+ /** The policy that decided what this answer holds. */
221
+ readonly visibility: TeamVisibility;
222
+ /** Whether this page's viewer sees everything as the artifact's owner. */
223
+ readonly owner: boolean;
224
+ /** The roster's round (always 1 under `once`). */
225
+ readonly round: number;
226
+ /** The viewer's own entry, when they are an expected respondent. */
227
+ readonly self?: RespondentForPage;
228
+ /** Under `counts` and `names`, and for the owner. */
229
+ readonly counts?: RosterCounts;
230
+ /** Under `counts` and `names`, and for the owner. */
231
+ readonly complete?: boolean;
232
+ /** Under `names`, and for the owner: every respondent, in the order they joined. */
233
+ readonly respondents?: readonly RespondentForPage[];
234
+ }
235
+
236
+ /** The Zod schema of the `RosterForPage` type. */
237
+ export const RosterForPage: z.ZodType<RosterForPage> = z
238
+ .object({
239
+ visibility: TeamVisibility,
240
+ owner: z.boolean(),
241
+ round: z.int().min(1),
242
+ self: RespondentForPage.exactOptional(),
243
+ counts: RosterCounts.exactOptional(),
244
+ complete: z.boolean().exactOptional(),
245
+ respondents: z.array(RespondentForPage).readonly().exactOptional(),
246
+ })
247
+ .register(wireRegistry, {
248
+ id: "RosterForPage",
249
+ description: "The roster as a page may see it under the visibility policy (CO-07).",
250
+ });
251
+
252
+ /** `POST …/respondents`: reads the roster as the page may see it and follows it for a minute. */
253
+ export interface RespondentsRequest {
254
+ /** The view the page was opened as (D104). */
255
+ readonly viewId: string;
256
+ }
257
+
258
+ /** The Zod schema of the `RespondentsRequest` type. */
259
+ export const RespondentsRequest: z.ZodType<RespondentsRequest> = z
260
+ .object({ viewId: ViewId.schema })
261
+ .register(wireRegistry, {
262
+ id: "RespondentsRequest",
263
+ description: "Reads the roster as the page may see it, and follows it for a minute.",
264
+ });
265
+
266
+ // ── Presence ─────────────────────────────────────────────────────────────────────────────────
267
+
268
+ /** The largest coordinate a shared cursor may carry, in CSS pixels. */
269
+ export const PRESENCE_COORDINATE_MAX = 10_000_000;
270
+
271
+ /** A shared pointer position, in the page's document coordinates (CSS pixels). */
272
+ export interface PresenceCursor {
273
+ /** From the document's left edge. */
274
+ readonly x: number;
275
+ /** From the document's top edge. */
276
+ readonly y: number;
277
+ }
278
+
279
+ /** The Zod schema of the `PresenceCursor` type. */
280
+ export const PresenceCursor: z.ZodType<PresenceCursor> = z
281
+ .object({
282
+ x: z.number().min(-PRESENCE_COORDINATE_MAX).max(PRESENCE_COORDINATE_MAX),
283
+ y: z.number().min(-PRESENCE_COORDINATE_MAX).max(PRESENCE_COORDINATE_MAX),
284
+ })
285
+ .register(wireRegistry, {
286
+ id: "PresenceCursor",
287
+ description: "A shared pointer position in the page's document coordinates, in CSS pixels.",
288
+ });
289
+
290
+ /**
291
+ * A shared selection: the element the viewer is in (its `data-presence-id`, `id` or `name`) and,
292
+ * in a text input, the selected range.
293
+ */
294
+ export interface PresenceSelection {
295
+ /** The element: its `data-presence-id`, `id` or `name`. */
296
+ readonly element?: string;
297
+ /** In a text input, where the selection starts. */
298
+ readonly start?: number;
299
+ /** In a text input, where it ends. */
300
+ readonly end?: number;
301
+ }
302
+
303
+ /** The Zod schema of the `PresenceSelection` type. */
304
+ export const PresenceSelection: z.ZodType<PresenceSelection> = z
305
+ .object({
306
+ element: z.string().min(1).max(256).exactOptional(),
307
+ start: z.int().min(0).max(PRESENCE_COORDINATE_MAX).exactOptional(),
308
+ end: z.int().min(0).max(PRESENCE_COORDINATE_MAX).exactOptional(),
309
+ })
310
+ .register(wireRegistry, {
311
+ id: "PresenceSelection",
312
+ description: "A shared selection: the element the viewer is in and the selected text range.",
313
+ });
314
+
315
+ /**
316
+ * `POST …/presence`: the page joins presence for the next half minute, sharing what it gives
317
+ * (CO-04). `cursor` and `selection` replace what the page shared (`null` stops sharing it); `leave`
318
+ * ends the page's presence at once. Never stored.
319
+ */
320
+ export interface PresenceRequest {
321
+ /** The view the page was opened as (D104). */
322
+ readonly viewId: string;
323
+ /** The pointer to share; `null` stops sharing it; absent leaves it as it was. */
324
+ readonly cursor?: PresenceCursor | null;
325
+ /** The selection to share; `null` stops sharing it; absent leaves it as it was. */
326
+ readonly selection?: PresenceSelection | null;
327
+ /** Ends the page's presence now. */
328
+ readonly leave?: true;
329
+ /**
330
+ * The page's own count of its presence posts, growing with each (a leave included): a post the
331
+ * gateway gets after one with a higher count, such as an update that overtook the page's leave,
332
+ * changes nothing.
333
+ */
334
+ readonly seq?: number;
335
+ }
336
+
337
+ /** The Zod schema of the `PresenceRequest` type. */
338
+ export const PresenceRequest: z.ZodType<PresenceRequest> = z
339
+ .object({
340
+ viewId: ViewId.schema,
341
+ cursor: PresenceCursor.nullable().exactOptional(),
342
+ selection: PresenceSelection.nullable().exactOptional(),
343
+ leave: z.literal(true).exactOptional(),
344
+ seq: z.number().int().nonnegative().max(Number.MAX_SAFE_INTEGER).exactOptional(),
345
+ })
346
+ .register(wireRegistry, {
347
+ id: "PresenceRequest",
348
+ description: "Joins presence for half a minute, sharing a cursor and a selection, or leaves.",
349
+ });
350
+
351
+ /** A viewer present on the artifact now, as a page may see them. */
352
+ export interface PresencePeer extends Peer {
353
+ /** Their pointer, when they share it. */
354
+ readonly cursor?: PresenceCursor;
355
+ /** Their selection, when they share it. */
356
+ readonly selection?: PresenceSelection;
357
+ /** When they last told Mostra anything. */
358
+ readonly at: string;
359
+ }
360
+
361
+ /** The Zod schema of the `PresencePeer` type. */
362
+ export const PresencePeer: z.ZodType<PresencePeer> = z
363
+ .object({
364
+ ...peerShape,
365
+ cursor: PresenceCursor.exactOptional(),
366
+ selection: PresenceSelection.exactOptional(),
367
+ at: z.iso.datetime(),
368
+ })
369
+ .register(wireRegistry, {
370
+ id: "PresencePeer",
371
+ description: "A viewer present now: key, name, and the cursor and selection they share.",
372
+ });
373
+
374
+ /**
375
+ * Who is present, as one page may see it (CO-04, CO-07): under `names` (or for the owner) every
376
+ * present viewer with what they share; under `counts` how many others are present; under
377
+ * `private` only the page's own viewer.
378
+ */
379
+ export interface PresenceState {
380
+ /** The policy that decided what this answer holds. */
381
+ readonly visibility: TeamVisibility;
382
+ /** Present viewers this page may see, its own first. */
383
+ readonly peers: readonly PresencePeer[];
384
+ /** How many other viewers are present, under `counts` and `names`. */
385
+ readonly others?: number;
386
+ }
387
+
388
+ /** The Zod schema of the `PresenceState` type. */
389
+ export const PresenceState: z.ZodType<PresenceState> = z
390
+ .object({
391
+ visibility: TeamVisibility,
392
+ peers: z.array(PresencePeer).readonly(),
393
+ others: z.int().min(0).exactOptional(),
394
+ })
395
+ .register(wireRegistry, {
396
+ id: "PresenceState",
397
+ description: "Who is present, as a page may see them under the visibility policy.",
398
+ });
package/src/verify.ts CHANGED
@@ -403,6 +403,13 @@ export interface RenderResult {
403
403
  readonly timedOut: boolean;
404
404
  /** When each step ended, in ms after the render started. */
405
405
  readonly timingsMs: Readonly<Record<string, number>>;
406
+ /**
407
+ * Why the page was rendered a second time, in a fresh browser context, when it was: a
408
+ * connection the browser couldn't make for a reason of its own (Chromium's random local port
409
+ * colliding on Windows, `net::ERR_NO_BUFFER_SPACE`, D157, #132). The second render's findings
410
+ * are the answer's.
411
+ */
412
+ readonly renderedAgain?: string;
406
413
  }
407
414
 
408
415
  /** `verify/compare`'s params; internal to Mostra. */