@miadi/companion-ui 0.2.0 → 0.4.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/src/thread.ts CHANGED
@@ -1,7 +1,7 @@
1
1
  /**
2
2
  * The conversation a person holds with an episode's companion seat, as data.
3
3
  *
4
- * Three sources meet here and nowhere else:
4
+ * Four sources meet here and nowhere else:
5
5
  *
6
6
  * - **takes**: what the person said, a recorded take filed in the episode under
7
7
  * `captures/<take>/` with its English transcript;
@@ -9,7 +9,10 @@
9
9
  * phone page keeps them (`replies/<episode>.jsonl` in its state directory);
10
10
  * - **voices**: the voice ledger's records of those replies. A reply is voiced
11
11
  * in parts of at most 900 characters, each its own record, so one reply can be
12
- * several voices.
12
+ * several voices;
13
+ * - **marks**: what the person pointed at on the episode's drawings and wrote there, with
14
+ * the thread the seat answered in, as each drawing's sidecar keeps them. A voiced reply
15
+ * that answers a mark names it (`mark: { id, doc }`).
13
16
  *
14
17
  * A voice whose `source` is `phone-capture` is a companion reply. Those voices
15
18
  * belong to the conversation, not to the episode's other recordings, and
@@ -57,6 +60,72 @@ export interface CompanionReply {
57
60
  related?: CompanionRelated[]
58
61
  /** The person's ruling on the reply, when given. */
59
62
  feedback?: CompanionFeedback
63
+ /**
64
+ * A reply that walks the episode's diagrams (jgwill/smcraft Spec 84): each step names a
65
+ * drawing, what to light in it, and the words said there. A host with a board plays them.
66
+ */
67
+ steps?: CompanionStep[]
68
+ /** The mark this reply answers, when the seat answered a mark by voice (kit 0.5.4). */
69
+ mark?: CompanionMarkRef
70
+ }
71
+
72
+ /** A mark named from elsewhere: its id and its drawing, by absolute path. */
73
+ export interface CompanionMarkRef {
74
+ /** `m-<time><random>`, the loom's id. */
75
+ id: string
76
+ /** The drawing the mark is on, by absolute path. */
77
+ doc: string
78
+ }
79
+
80
+ /** Who wrote a mark or a word in its thread. */
81
+ export interface CompanionMarkAuthor {
82
+ name: string
83
+ role: "person" | "agent"
84
+ }
85
+
86
+ /** One word in a mark's thread, as the drawing's sidecar keeps it. */
87
+ export interface CompanionMarkReply {
88
+ author: CompanionMarkAuthor
89
+ text: string
90
+ at: string
91
+ }
92
+
93
+ /**
94
+ * A mark a person (or an agent) left on one of the episode's drawings, with its thread, as
95
+ * the drawing's sidecar keeps it (`<name>.<kind>.marks.json`, jgwill/smcraft Spec 83).
96
+ */
97
+ export interface CompanionMark {
98
+ id: string
99
+ /** The drawing, by absolute path. */
100
+ doc: string
101
+ /** The drawing, relative to the episode's `diagrams/` folder: `screenwalk.smdf.json`. */
102
+ drawing: string
103
+ /** The drawing's own name (`settings.name`), when it says one. */
104
+ title?: string
105
+ /** What the mark points at, in the loom's names (`state:Witnessing`). Empty for an area or the whole drawing. */
106
+ elements: string[]
107
+ /** True when the mark points at an area of the drawing. */
108
+ area?: boolean
109
+ text: string
110
+ author: CompanionMarkAuthor
111
+ /** When the mark was made. */
112
+ at: string
113
+ /** When its thread last moved: its latest reply, else `at`. */
114
+ lastAt: string
115
+ /** `open` waits on the side that did not write last; `answered` was answered; `resolved` is closed. */
116
+ status: "open" | "answered" | "resolved"
117
+ replies: CompanionMarkReply[]
118
+ }
119
+
120
+ /** One step of a reply that walks a diagram. Element names are the loom's (`state:Published`). */
121
+ export interface CompanionStep {
122
+ say: string
123
+ title?: string
124
+ /** The drawing, by absolute path. */
125
+ doc?: string
126
+ focus?: string
127
+ spotlight?: string[]
128
+ region?: { x: number; y: number; width: number; height: number }
60
129
  }
61
130
 
62
131
  /** One voice-ledger record, reduced to what the conversation needs. */
@@ -86,13 +155,37 @@ export interface CompanionReplyTurn extends CompanionReply {
86
155
  fromVoices?: boolean
87
156
  }
88
157
 
89
- export type CompanionTurn = CompanionTakeTurn | CompanionReplyTurn
158
+ export interface CompanionMarkTurn extends CompanionMark {
159
+ kind: "mark"
160
+ /** The ids of the voiced replies that answer this mark, oldest first. */
161
+ voiced: string[]
162
+ }
163
+
164
+ export type CompanionTurn = CompanionTakeTurn | CompanionReplyTurn | CompanionMarkTurn
165
+
166
+ /** The marks on one drawing, counted, so a host that shows a few turns can still say what exists. */
167
+ export interface CompanionMarkCount {
168
+ /** The drawing, relative to `diagrams/`. */
169
+ drawing: string
170
+ title?: string
171
+ marks: number
172
+ /** Open marks whose last word is an agent's. */
173
+ answered: number
174
+ /** Open marks whose last word is a person's: they wait on an agent. */
175
+ waiting: number
176
+ resolved: number
177
+ /** The agents who answered on this drawing, by name. */
178
+ answeredBy: string[]
179
+ }
90
180
 
91
181
  export interface CompanionThread {
92
- /** Takes and replies in the order they happened. */
182
+ /** Takes, replies and marks in the order they happened. */
93
183
  turns: CompanionTurn[]
94
184
  takes: number
95
185
  replies: number
186
+ marks: number
187
+ /** The marks counted per drawing, in the order of their first mark. */
188
+ markCounts: CompanionMarkCount[]
96
189
  /** Sessions that wrote replies, newest last. */
97
190
  sessions: string[]
98
191
  }
@@ -155,6 +248,8 @@ export function buildCompanionThread(input: {
155
248
  takes?: readonly CompanionTake[]
156
249
  replies?: readonly CompanionReply[]
157
250
  voices?: readonly CompanionVoice[]
251
+ /** The marks on the episode's drawings, with their threads (`readCompanionMarks`). */
252
+ marks?: readonly CompanionMark[]
158
253
  }): CompanionThread {
159
254
  const takes = (input.takes ?? []).filter((take) => !take.purpose || !NOT_CONVERSATION.has(take.purpose))
160
255
  const replies = [...(input.replies ?? [])].sort((a, b) => time(a.at) - time(b.at))
@@ -210,6 +305,11 @@ export function buildCompanionThread(input: {
210
305
  fromVoices: true,
211
306
  })
212
307
  }
308
+ const marks = [...(input.marks ?? [])].sort((a, b) => time(a.at) - time(b.at))
309
+ for (const mark of marks) {
310
+ const voiced = replies.filter((r) => r.mark && answersMark(r.mark, mark)).map((r) => r.id)
311
+ turns.push({ kind: "mark", ...mark, voiced })
312
+ }
213
313
  turns.sort((a, b) => time(a.at) - time(b.at))
214
314
 
215
315
  const sessions: string[] = []
@@ -223,10 +323,108 @@ export function buildCompanionThread(input: {
223
323
  turns,
224
324
  takes: turns.filter((t) => t.kind === "take").length,
225
325
  replies: turns.filter((t) => t.kind === "reply").length,
326
+ marks: marks.length,
327
+ markCounts: countMarks(marks),
226
328
  sessions,
227
329
  }
228
330
  }
229
331
 
332
+ /** True when a reply's mark names this mark: the same id, on the same drawing (the same path, or the same file under an episode's `diagrams/`). */
333
+ function answersMark(ref: CompanionMarkRef, mark: CompanionMark): boolean {
334
+ return ref.id === mark.id && (ref.doc === mark.doc || ref.doc.endsWith(`/diagrams/${mark.drawing}`))
335
+ }
336
+
337
+ /** Where a mark stands: closed, answered (the last word is an agent's), or waiting on an agent. */
338
+ export function markState(mark: Pick<CompanionMark, "status" | "author" | "replies">): "resolved" | "answered" | "waiting" | "asks" {
339
+ if (mark.status === "resolved") return "resolved"
340
+ const last = mark.replies.at(-1)?.author ?? mark.author
341
+ if (last.role === "person") return "waiting"
342
+ // An agent's own mark with no answer yet is a question to the person.
343
+ return mark.replies.length === 0 ? "asks" : "answered"
344
+ }
345
+
346
+ /** The agent who last answered in a mark's thread, by name. */
347
+ export function markAnswerer(mark: Pick<CompanionMark, "replies">): string | undefined {
348
+ for (let i = mark.replies.length - 1; i >= 0; i--) {
349
+ const r = mark.replies[i]!
350
+ if (r.author.role === "agent" && r.author.name) return r.author.name
351
+ }
352
+ return undefined
353
+ }
354
+
355
+ function countMarks(marks: readonly CompanionMark[]): CompanionMarkCount[] {
356
+ const counts = new Map<string, CompanionMarkCount>()
357
+ for (const mark of marks) {
358
+ let c = counts.get(mark.drawing)
359
+ if (!c) {
360
+ c = { drawing: mark.drawing, ...(mark.title ? { title: mark.title } : {}), marks: 0, answered: 0, waiting: 0, resolved: 0, answeredBy: [] }
361
+ counts.set(mark.drawing, c)
362
+ }
363
+ c.marks++
364
+ const state = markState(mark)
365
+ if (state === "resolved") c.resolved++
366
+ else if (state === "answered") c.answered++
367
+ else if (state === "waiting") c.waiting++
368
+ const by = markAnswerer(mark)
369
+ if (by && !c.answeredBy.includes(by)) c.answeredBy.push(by)
370
+ }
371
+ return [...counts.values()]
372
+ }
373
+
374
+ /** `screenwalk.smdf.json` → `screenwalk`: a drawing's name when it carries none. */
375
+ export function drawingLabel(mark: { drawing: string; title?: string }): string {
376
+ return mark.title || mark.drawing.replace(/^.*\//, "").replace(/\.(smdf|erdf|sqdf)\.json$/i, "")
377
+ }
378
+
379
+ /** `a`, `a and b`, `a, b and c`. */
380
+ function listed(items: readonly string[]): string {
381
+ return items.length <= 1 ? (items[0] ?? "") : `${items.slice(0, -1).join(", ")} and ${items.at(-1)}`
382
+ }
383
+
384
+ /**
385
+ * What a mark points at, as a person reads it: `state:Witnessing` → `Witnessing`, an
386
+ * attribute under its entity only when the entity is not named too, four names at most
387
+ * and then how many more; `an area` or `the drawing` when it names no element.
388
+ */
389
+ export function markElementNames(mark: Pick<CompanionMark, "elements" | "area">): string {
390
+ const parsed = mark.elements
391
+ .map((e) => {
392
+ const at = e.indexOf(":")
393
+ return at > 0 ? { kind: e.slice(0, at), name: e.slice(at + 1).trim() } : { kind: "", name: e.trim() }
394
+ })
395
+ .filter((e) => e.name)
396
+ const entities = new Set(parsed.filter((e) => e.kind === "entity").map((e) => e.name))
397
+ const names: string[] = []
398
+ for (const e of parsed) {
399
+ if (e.kind === "attribute" && entities.has(e.name.split(".")[0]!)) continue
400
+ const name = e.kind === "message" && /^\d+$/.test(e.name) ? `message ${e.name}` : e.name
401
+ if (!names.includes(name)) names.push(name)
402
+ }
403
+ if (names.length === 0) return mark.area ? "an area" : "the drawing"
404
+ if (names.length <= 4) return listed(names)
405
+ return `${names.slice(0, 3).join(", ")} and ${names.length - 3} more`
406
+ }
407
+
408
+ /**
409
+ * The marks in one line, for a host that shows only the latest turns:
410
+ * `7 marks on Screenwalk: 6 answered by Mia, 1 resolved · 1 mark on ScreenwalkRecords: answered by Mia`.
411
+ * Empty when there are none. `waitsFor` names who a waiting mark waits on (default `Mia`).
412
+ */
413
+ export function sayMarks(thread: Pick<CompanionThread, "markCounts">, waitsFor = "Mia"): string {
414
+ return thread.markCounts
415
+ .map((c) => {
416
+ const head = `${c.marks} mark${c.marks === 1 ? "" : "s"} on ${drawingLabel(c)}`
417
+ const by = listed(c.answeredBy) || "an agent"
418
+ const parts = [
419
+ c.answered ? (c.answered === c.marks ? `answered by ${by}` : `${c.answered} answered by ${by}`) : "",
420
+ c.waiting ? (c.waiting === c.marks ? `waiting for ${waitsFor}` : `${c.waiting} waiting for ${waitsFor}`) : "",
421
+ c.resolved ? (c.resolved === c.marks ? "resolved" : `${c.resolved} resolved`) : "",
422
+ ].filter(Boolean)
423
+ return parts.length ? `${head}: ${parts.join(", ")}` : head
424
+ })
425
+ .join(" · ")
426
+ }
427
+
230
428
  function groupVoices(voices: readonly CompanionVoice[]): CompanionVoice[][] {
231
429
  const groups: CompanionVoice[][] = []
232
430
  for (const voice of voices) {
@@ -238,6 +436,12 @@ function groupVoices(voices: readonly CompanionVoice[]): CompanionVoice[][] {
238
436
  return groups
239
437
  }
240
438
 
439
+ /** The mark a reply answers, when it is in the thread. */
440
+ export function markOf(thread: Pick<CompanionThread, "turns">, reply: CompanionReplyTurn): CompanionMarkTurn | undefined {
441
+ const ref = reply.mark
442
+ return ref ? (thread.turns.find((t) => t.kind === "mark" && answersMark(ref, t)) as CompanionMarkTurn | undefined) : undefined
443
+ }
444
+
241
445
  /** The take a reply answers, when it is in the thread. */
242
446
  export function takeOf(thread: CompanionThread, reply: CompanionReplyTurn): CompanionTakeTurn | undefined {
243
447
  return reply.take ? (thread.turns.find((t) => t.kind === "take" && t.id === reply.take) as CompanionTakeTurn | undefined) : undefined