@miadi/companion-ui 0.3.0 → 0.4.1

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
@@ -62,6 +65,56 @@ export interface CompanionReply {
62
65
  * drawing, what to light in it, and the words said there. A host with a board plays them.
63
66
  */
64
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[]
65
118
  }
66
119
 
67
120
  /** One step of a reply that walks a diagram. Element names are the loom's (`state:Published`). */
@@ -102,13 +155,37 @@ export interface CompanionReplyTurn extends CompanionReply {
102
155
  fromVoices?: boolean
103
156
  }
104
157
 
105
- 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
+ }
106
180
 
107
181
  export interface CompanionThread {
108
- /** Takes and replies in the order they happened. */
182
+ /** Takes, replies and marks in the order they happened. */
109
183
  turns: CompanionTurn[]
110
184
  takes: number
111
185
  replies: number
186
+ marks: number
187
+ /** The marks counted per drawing, in the order of their first mark. */
188
+ markCounts: CompanionMarkCount[]
112
189
  /** Sessions that wrote replies, newest last. */
113
190
  sessions: string[]
114
191
  }
@@ -171,6 +248,8 @@ export function buildCompanionThread(input: {
171
248
  takes?: readonly CompanionTake[]
172
249
  replies?: readonly CompanionReply[]
173
250
  voices?: readonly CompanionVoice[]
251
+ /** The marks on the episode's drawings, with their threads (`readCompanionMarks`). */
252
+ marks?: readonly CompanionMark[]
174
253
  }): CompanionThread {
175
254
  const takes = (input.takes ?? []).filter((take) => !take.purpose || !NOT_CONVERSATION.has(take.purpose))
176
255
  const replies = [...(input.replies ?? [])].sort((a, b) => time(a.at) - time(b.at))
@@ -226,6 +305,11 @@ export function buildCompanionThread(input: {
226
305
  fromVoices: true,
227
306
  })
228
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
+ }
229
313
  turns.sort((a, b) => time(a.at) - time(b.at))
230
314
 
231
315
  const sessions: string[] = []
@@ -239,10 +323,108 @@ export function buildCompanionThread(input: {
239
323
  turns,
240
324
  takes: turns.filter((t) => t.kind === "take").length,
241
325
  replies: turns.filter((t) => t.kind === "reply").length,
326
+ marks: marks.length,
327
+ markCounts: countMarks(marks),
242
328
  sessions,
243
329
  }
244
330
  }
245
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
+
246
428
  function groupVoices(voices: readonly CompanionVoice[]): CompanionVoice[][] {
247
429
  const groups: CompanionVoice[][] = []
248
430
  for (const voice of voices) {
@@ -254,6 +436,12 @@ function groupVoices(voices: readonly CompanionVoice[]): CompanionVoice[][] {
254
436
  return groups
255
437
  }
256
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
+
257
445
  /** The take a reply answers, when it is in the thread. */
258
446
  export function takeOf(thread: CompanionThread, reply: CompanionReplyTurn): CompanionTakeTurn | undefined {
259
447
  return reply.take ? (thread.turns.find((t) => t.kind === "take" && t.id === reply.take) as CompanionTakeTurn | undefined) : undefined