@estiva-app/conversation 0.23.0 → 0.24.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.
@@ -1,6 +1,7 @@
1
1
  /**
2
2
  * A message's opening words, as a caption — what `[`'s row for a comment
3
- * shows under its author, the same in every app (PEEKM-6).
3
+ * shows under its author, and any preview of a message, the same in every app
4
+ * (PEEKM-6).
4
5
  *
5
6
  * One line of plain words: marks and line prefixes gone, a link on words as
6
7
  * its words, a fenced code block's fences dropped. A `nostr:` reference reads
@@ -14,9 +15,14 @@
14
15
  * so the same comment reads the same in an app that has the file loaded and
15
16
  * one that does not (Miky, 27 October, PEEKM-6's kickoff).
16
17
  *
18
+ * A bare app URL that names a file or a message reads as that reference would
19
+ * (§13.6.2, "A bare app link reads as a reference"), never as the raw URL
20
+ * (Katerina, 30 October, widget review item 20). A URL nothing claims stays
21
+ * as written (§13.1), and so does one in code.
22
+ *
17
23
  * why: https://github.com/estiva-app/estiva-docs/blob/main/decisions/a-conversation-is-one-shared-thing-and-only-its-colours-are-the-apps.md
18
24
  */
19
- import { decodeNpub, parseInlineMarks, referenceToPointer } from '@estiva-app/protocol'
25
+ import { decodeNpub, parseInlineMarks, referenceOfLink, referenceToPointer, urlRunsIn, type LinkResolver } from '@estiva-app/protocol'
20
26
 
21
27
  /** A file's type word by its kind, as `[`'s Files rows name it. */
22
28
  const TYPE_WORDS: Record<number, string> = { 30850: 'Project', 30851: 'Issue', 30840: 'Topic', 30842: 'Document', 39000: 'Folder' }
@@ -32,6 +38,20 @@ const LINE_PREFIX = /^\s*(?:(?:>|#{1,6})\s+)*(?:(?:[-*+]|\d+[.)])\s+(?:\[[ xX]\]
32
38
  const LINK_ON_WORDS = /(?<!!)\[([^[\]\n]+)\]\(((?:https?:\/\/|mailto:)[^\s)]+)\)/g
33
39
  const linkWords = (whole: string, words: string, url: string) => (url.split('(').length > url.split(')').length ? whole : words)
34
40
 
41
+ /** A reference to a file or a message: the ones a caption names by a type word, not by anything its writer typed. */
42
+ const OBJECT_REFERENCE = /^nostr:(?:naddr1|nevent1|note1)/i
43
+
44
+ export interface OpeningWordsOptions {
45
+ /**
46
+ * What an app link names (§7.7), as answered so far — the resolver the app
47
+ * gives its box (`BoxLinkContext.resolveLink`). A bare app URL it answers
48
+ * reads as the reference it names ("Issue", "Message"); one it does not —
49
+ * nothing claims it, or the answer has not come back yet — stays as
50
+ * written. Without it, every URL stays as written.
51
+ */
52
+ resolveLink?: LinkResolver
53
+ }
54
+
35
55
  /** The shortened form §13.1 asks for when a reference names nobody here. */
36
56
  function shortened(uri: string): string {
37
57
  return `${uri.replace(/^nostr:/i, '').slice(0, 12)}…`
@@ -61,27 +81,99 @@ export function referenceWord(uri: string, nameOf: (pubkey: string) => string |
61
81
  }
62
82
 
63
83
  /**
64
- * One line's words. Protocol's mark reader recurses once per mark, so a line of a few thousand (anyone can post one)
65
- * overflows the stack; that line then reads as its text with the marker characters dropped, rather than taking down
66
- * every `[` list that captions it (Peek: Feedback & Bugs 4acb43ac is the reader's own fix).
84
+ * How a line is read: `caption`, as a preview shows it ({@link openingWords}); `words`, only what its writer
85
+ * wrote ({@link messageWords}). `code` is a line of a fenced code block, where a URL is literal (§13.1).
86
+ */
87
+ interface Reading {
88
+ mode: 'caption' | 'words'
89
+ nameOf: (pubkey: string) => string | undefined
90
+ resolveLink?: LinkResolver
91
+ code?: boolean
92
+ }
93
+
94
+ /** A character `text` does not hold, from the private use area. */
95
+ function unusedCharacter(text: string): string | undefined {
96
+ for (let code = 0xe000; code <= 0xf8ff; code++) {
97
+ const ch = String.fromCharCode(code)
98
+ if (!text.includes(ch)) return ch
99
+ }
100
+ return undefined
101
+ }
102
+
103
+ /** A bare URL as the line reads it: the reference's word in a caption, as written in code or when nothing claims it. */
104
+ function urlWord(url: string, reading: Reading): string {
105
+ if (reading.code) return url
106
+ if (reading.mode === 'words') return ''
107
+ const reference = reading.resolveLink ? referenceOfLink(url, reading.resolveLink) : undefined
108
+ return reference ? referenceWord(reference, reading.nameOf) : url
109
+ }
110
+
111
+ /** Each bare URL in a run of plain text, as the line reads it; the rest as it is. */
112
+ function withUrlsRead(text: string, reading: Reading): string {
113
+ let out = ''
114
+ let at = 0
115
+ for (const { url, from, to } of urlRunsIn(text)) {
116
+ out += text.slice(at, from) + urlWord(url, reading)
117
+ at = to
118
+ }
119
+ return out + text.slice(at)
120
+ }
121
+
122
+ /** A `nostr:` reference as the line reads it: its word, or nothing in a message's own words when it names a file or a message. */
123
+ function referenceAs(uri: string, reading: Reading): string {
124
+ return reading.mode === 'words' && OBJECT_REFERENCE.test(uri) ? '' : referenceWord(uri, reading.nameOf)
125
+ }
126
+
127
+ /**
128
+ * One line's words. A bare URL is found in the text the marks leave, as a reader finds it (`urlRunsIn`), and read by
129
+ * {@link urlWord}. A URL written in a link's words names nothing (§13.6.2), so its `://` is broken by a character the
130
+ * line does not hold until the line is read. Protocol's mark reader recurses once per mark, so a line of a few thousand
131
+ * (anyone can post one) overflows the stack; that line then reads as its text with the marker characters dropped,
132
+ * rather than taking down every `[` list that captions it (Peek: Feedback & Bugs 4acb43ac is the reader's own fix).
67
133
  */
68
- function lineWords(line: string, nameOf: (pubkey: string) => string | undefined): string {
134
+ function lineWords(line: string, reading: Reading): string {
135
+ const mark = line.includes('://') ? unusedCharacter(line) : undefined
136
+ const text = line.replace(LINK_ON_WORDS, (whole: string, words: string, url: string) => {
137
+ const read = linkWords(whole, words, url)
138
+ return read !== whole && mark ? read.replaceAll('://', `:${mark}//`) : read
139
+ })
140
+ const unmark = (words: string) => (mark ? words.replaceAll(mark, '') : words)
69
141
  try {
70
- return parseInlineMarks(line)
71
- .map((span) => (span.reference ? referenceWord(span.reference, nameOf) : span.text))
142
+ return parseInlineMarks(text)
143
+ .map((span) => (span.reference ? referenceAs(span.reference, reading) : unmark(span.code ? span.text : withUrlsRead(span.text, reading))))
72
144
  .join('')
73
145
  } catch {
74
- return line.replace(/[*_~`]+/g, '')
146
+ return unmark(withUrlsRead(text.replace(/[*_~`]+/g, ''), reading))
75
147
  }
76
148
  }
77
149
 
150
+ /** A body's lines on one line, read as `reading` says, a code block's fences dropped. */
151
+ function bodyWords(body: string, reading: Omit<Reading, 'code'>): string {
152
+ let inCode = false
153
+ const lines: string[] = []
154
+ for (const line of body.split('\n')) {
155
+ if (FENCE.test(line)) {
156
+ inCode = !inCode
157
+ continue
158
+ }
159
+ lines.push(lineWords(line.replace(LINE_PREFIX, ''), { ...reading, code: inCode }))
160
+ }
161
+ return lines.join(' ').replace(/\s+/g, ' ').trim()
162
+ }
163
+
78
164
  /** A message body's opening words on one line, as a caption: see the module's note. */
79
- export function openingWords(body: string, nameOf: (pubkey: string) => string | undefined): string {
80
- return body
81
- .split('\n')
82
- .filter((line) => !FENCE.test(line))
83
- .map((line) => lineWords(line.replace(LINE_PREFIX, '').replace(LINK_ON_WORDS, linkWords), nameOf))
84
- .join(' ')
85
- .replace(/\s+/g, ' ')
86
- .trim()
165
+ export function openingWords(body: string, nameOf: (pubkey: string) => string | undefined, options: OpeningWordsOptions = {}): string {
166
+ return bodyWords(body, { mode: 'caption', nameOf, resolveLink: options.resolveLink })
167
+ }
168
+
169
+ /**
170
+ * The words a message is found by in `[` (Katerina, 30 October, widget review
171
+ * item 19): what its writer wrote, read as {@link openingWords} reads it, but
172
+ * with no link's raw text — no bare URL, resolved or not — and no type word
173
+ * for a file or a message it names, so typing a file's word finds the file,
174
+ * not every message that links to it. A link on words keeps its words, a
175
+ * person reads as `@Name`, and code is kept as written.
176
+ */
177
+ export function messageWords(body: string, nameOf: (pubkey: string) => string | undefined): string {
178
+ return bodyWords(body, { mode: 'words', nameOf })
87
179
  }
package/src/references.ts CHANGED
@@ -2,12 +2,16 @@
2
2
  * What `[` offers, and in what order — CON-26's ranking (Miky, 2026-10-02),
3
3
  * in one place for every app (PEE-21).
4
4
  *
5
- * Two capped sections, Messages above Files:
5
+ * Two capped sections, Files above Messages ({@link referenceSectionsOf};
6
+ * Katerina, 2026-10-30, widget review item 19 — Messages led until then, and
7
+ * typing a file's word picked a message):
6
8
  *
7
- * - **Messages:** this thread or file first, then the parent file's.
8
9
  * - **Files:** this Folder first, then files you read recently (your §11 read
9
10
  * markers), then everything else, which you reach only by typing (relay
10
11
  * search).
12
+ * - **Messages:** this thread or file first, then the parent file's. A message
13
+ * is found by its own words ({@link messageWords}), never by a link's raw
14
+ * text: a row built by {@link messageCandidate} carries them.
11
15
  *
12
16
  * With nothing typed the tiers set the order. Once you type, a better title
13
17
  * match beats a higher tier; an open issue goes before a done or cancelled
@@ -20,6 +24,8 @@
20
24
  * markers, a relay search — is the app's: each app holds them differently.
21
25
  */
22
26
  import { addrToNaddr } from '@estiva-app/protocol'
27
+ import { messageReference } from './compose.js'
28
+ import { messageWords, openingWords, type OpeningWordsOptions } from './openingWords.js'
23
29
 
24
30
  /** What a reference names, as the row's type word says it (label objects by type, not app). */
25
31
  export type ReferenceType = 'message' | 'issue' | 'project' | 'topic' | 'document'
@@ -42,7 +48,10 @@ export interface ReferenceCandidate {
42
48
  * none, and on a message. Not matched: search keeps to titles.
43
49
  */
44
50
  summary?: string
45
- /** Matched beside `title`: a message's text, an issue's ref (`CON-33`). */
51
+ /**
52
+ * Matched beside `title`: a message's own words ({@link messageWords}), an
53
+ * issue's ref (`CON-33`). A message without it is matched on `caption`.
54
+ */
46
55
  search?: string
47
56
  /** 0 is closest: {@link MESSAGE_TIER} or {@link FILE_TIER}. */
48
57
  tier: number
@@ -71,6 +80,63 @@ export interface RankedReferences {
71
80
  files: ReferenceCandidate[]
72
81
  }
73
82
 
83
+ /** One of `[`'s sections, by name: the app gives it its heading. */
84
+ export interface RankedSection {
85
+ name: 'files' | 'messages'
86
+ items: ReferenceCandidate[]
87
+ }
88
+
89
+ /**
90
+ * {@link rankReferences}' sections in the order `[` draws them: Files, then
91
+ * Messages (Katerina, 2026-10-30), in every app. An empty one is kept: the
92
+ * menu draws no heading for it.
93
+ */
94
+ export function referenceSectionsOf(ranked: RankedReferences): RankedSection[] {
95
+ return [
96
+ { name: 'files', items: ranked.files },
97
+ { name: 'messages', items: ranked.messages },
98
+ ]
99
+ }
100
+
101
+ /** A message `[` can offer, as the app holds it. */
102
+ export interface ReferableMessage {
103
+ /** Its event id. */
104
+ id: string
105
+ /** Its kind, carried in the reference so a reader fetches the right thing: 9 for chat, 1111 for a comment. */
106
+ kind: number
107
+ /** Who wrote it, as the row names them. */
108
+ author: string
109
+ body: string
110
+ /** When it was written, in seconds, or any number that is higher for a newer one. */
111
+ at?: number
112
+ }
113
+
114
+ /**
115
+ * A message as `[`'s row offers it, the same in every app: its reference
116
+ * (`messageReference`), its author as the title, its opening words as the
117
+ * caption ({@link openingWords}, an app link read as what it names when
118
+ * `resolveLink` has answered for it), and its own words to be found by
119
+ * ({@link messageWords}) — not the raw text of a link in it.
120
+ */
121
+ export function messageCandidate(
122
+ message: ReferableMessage,
123
+ tier: number,
124
+ nameOf: (pubkey: string) => string | undefined,
125
+ options: OpeningWordsOptions = {},
126
+ ): ReferenceCandidate {
127
+ return {
128
+ id: message.id,
129
+ uri: messageReference(message.id, message.kind),
130
+ type: 'message',
131
+ kind: message.kind,
132
+ title: message.author,
133
+ caption: openingWords(message.body, nameOf, options),
134
+ search: messageWords(message.body, nameOf),
135
+ tier,
136
+ ...(message.at === undefined ? {} : { at: message.at }),
137
+ }
138
+ }
139
+
74
140
  export interface RankReferencesInput {
75
141
  messages: readonly ReferenceCandidate[]
76
142
  files: readonly ReferenceCandidate[]