@estiva-app/conversation 0.23.1 → 0.25.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[]
@@ -0,0 +1,185 @@
1
+ /**
2
+ * A list row's dot — SPEC §11.8 over a stream's messages, for a reader that
3
+ * holds only who said what and when, never the bodies.
4
+ *
5
+ * Moved here from Peek (SHIPS-2) so Peek's Topics and Ship's Topics judge a
6
+ * topic's dot by one rule: which files the viewer is a member of, read from
7
+ * the relay and folded ({@link membershipQueries}, {@link foldMemberships}),
8
+ * the terms that fold gives a stream ({@link streamTermsOf}), and whether any
9
+ * of the stream's messages is unread on them ({@link streamHasUnread}).
10
+ *
11
+ * The read state and the muted list are encrypted (NIP-44), so nothing here
12
+ * reads them: the app hands in the merged markers and the muted set it holds.
13
+ */
14
+ import { encodeNpub, type SignedEvent } from '@estiva-app/protocol'
15
+ import { candidateFilesOf, membershipFilters, membershipOf, mentions, type Membership } from './membership.js'
16
+ import { READ_STATE_HORIZON_DAYS, fileContext } from './readState.js'
17
+ import { isUnread } from './unread.js'
18
+
19
+ /** What a list holds of a message: no body. `root` is the thread root's id, the message's own when it is one. */
20
+ export interface StreamMessage {
21
+ id: string
22
+ /** Unix seconds. */
23
+ at: number
24
+ /** Author pubkey. */
25
+ by: string
26
+ root: string
27
+ }
28
+
29
+ /** What a stream is judged against besides its messages. */
30
+ export interface StreamFrontier {
31
+ /** The merged read state: context → unix seconds. */
32
+ merged: Readonly<Record<string, number>>
33
+ /** The viewer's pubkey; their own messages do not count. */
34
+ me: string | undefined
35
+ /** Now, unix seconds. */
36
+ nowSeconds: number
37
+ horizonSeconds: number
38
+ }
39
+
40
+ /** The terms a stream is told about on: SPEC §11.8's membership, join time and mute. */
41
+ export interface StreamTerms {
42
+ member: boolean
43
+ since?: number
44
+ muted: boolean
45
+ }
46
+
47
+ /**
48
+ * Is anything in this stream unread for the viewer — SPEC §11.8's four
49
+ * conditions over §11.3's markers, judged by {@link isUnread}.
50
+ *
51
+ * `context` is the stream's read-state context (§11.1): `fileContext(address)`
52
+ * for a file, `channelContext(uuid)` for a Folder's general stream. A message is
53
+ * judged against its thread's marker as well as the stream's (§11.3).
54
+ *
55
+ * The messages carry no body, so whether one *names the viewer* comes from
56
+ * `isMentioned` (the ids the membership read's `#p` filter returned) and is
57
+ * handed to the judge as the body it would have had. Without a marker, a file
58
+ * member is told from the second they joined; a Folder's own chat has no
59
+ * members here and lights only for a message that names the viewer, so
60
+ * absence there is the horizon (§11.6).
61
+ */
62
+ export function streamHasUnread(
63
+ messages: readonly StreamMessage[],
64
+ context: string,
65
+ terms: StreamTerms,
66
+ frontier: StreamFrontier,
67
+ isMentioned: (messageId: string) => boolean,
68
+ ): boolean {
69
+ const { me } = frontier
70
+ if (!me) return false
71
+ // Only for a message that names the viewer, so a viewer without a hex key judges the rest.
72
+ const named = () => `nostr:${encodeNpub(me)}`
73
+ const judge = {
74
+ stream: context,
75
+ me,
76
+ member: terms.member,
77
+ since: terms.since,
78
+ muted: terms.muted,
79
+ floor: frontier.nowSeconds - frontier.horizonSeconds,
80
+ }
81
+ for (const message of messages) {
82
+ const root = message.root === message.id ? undefined : message.root
83
+ const unread = isUnread(
84
+ { id: message.id, pubkey: message.by, kind: 1111, created_at: message.at, tags: [], content: isMentioned(message.id) ? named() : '' },
85
+ root,
86
+ frontier.merged,
87
+ judge,
88
+ )
89
+ if (unread) return true
90
+ }
91
+ return false
92
+ }
93
+
94
+ /** Per filter. Measured on production as the agent, the most-named identity there: 700 events in 90 days. */
95
+ export const MEMBERSHIP_LIMIT = 1000
96
+
97
+ /** The read horizon, in seconds: nothing before it can light a dot. */
98
+ export const HORIZON_SECONDS = READ_STATE_HORIZON_DAYS * 24 * 60 * 60
99
+
100
+ /** The three filters that find every file the viewer may be a member of (§11.8), bounded by the horizon. */
101
+ export function membershipQueries(pubkey: string, nowSeconds: number, limit = MEMBERSHIP_LIMIT): Record<string, unknown>[] {
102
+ return membershipFilters(pubkey, nowSeconds - HORIZON_SECONDS).map((filter) => ({ ...filter, limit }))
103
+ }
104
+
105
+ /** What the relay says the viewer is a member of, within the horizon. */
106
+ export interface MembershipRead {
107
+ /** Every candidate file, folded: the ones the viewer is in and the ones they left. */
108
+ files: ReadonlyMap<string, Membership>
109
+ /** Ids of the messages whose content names the viewer. */
110
+ mentioned: ReadonlySet<string>
111
+ /** Unix seconds a created file's membership starts at — the horizon's start. */
112
+ floor: number
113
+ }
114
+
115
+ /** The address's author, or undefined when it is not a file address. */
116
+ export function authorOfAddress(address: string): string | undefined {
117
+ if (fileContext(address) === undefined) return undefined
118
+ return address.split(':')[1]
119
+ }
120
+
121
+ /**
122
+ * Fold what {@link membershipQueries} returned. Pure: the clock is `nowSeconds`.
123
+ *
124
+ * A file's address names its author, so a file the viewer created needs no
125
+ * query: a candidate whose address is theirs is folded with its root added,
126
+ * dated to the horizon's start — the earliest the viewer could be told about —
127
+ * and a leave of theirs among the changes still takes them off. Membership the
128
+ * horizon hides lapses for this reader and comes back with the next event
129
+ * naming the viewer (§11.8 *The fold*).
130
+ */
131
+ export function foldMemberships(pubkey: string, events: readonly SignedEvent[], nowSeconds: number): MembershipRead {
132
+ const floor = nowSeconds - HORIZON_SECONDS
133
+ const byFile = new Map<string, SignedEvent[]>()
134
+ const mentioned = new Set<string>()
135
+ for (const event of events) {
136
+ if (mentions(event, pubkey)) mentioned.add(event.id)
137
+ for (const file of candidateFilesOf(event)) {
138
+ const list = byFile.get(file)
139
+ if (list) list.push(event)
140
+ else byFile.set(file, [event])
141
+ }
142
+ }
143
+ const files = new Map<string, Membership>()
144
+ for (const [file, held] of byFile) {
145
+ const [kind, , d] = file.split(':')
146
+ const own = authorOfAddress(file) === pubkey
147
+ // The root the viewer created, when they did — ordered before everything else for the file.
148
+ const root = own ? [{ id: '', pubkey, kind: Number(kind), created_at: floor, tags: [['d', d ?? '']], content: '', sig: '' }] : []
149
+ files.set(file, membershipOf(file, pubkey, [...root, ...held]))
150
+ }
151
+ return { files, mentioned, floor }
152
+ }
153
+
154
+ /**
155
+ * The terms a stream is judged on, from the membership read and the muted set.
156
+ *
157
+ * A file is a member by the fold, else by authorship (a file the viewer
158
+ * created is theirs unless a leave of theirs says otherwise, and a leave is
159
+ * among the files read). Anything that is not a file address — a Folder's
160
+ * general stream — has nothing to read (Miky, 2026-10-01): nobody is a member
161
+ * of it, so it lights only for a message that names the viewer.
162
+ */
163
+ export function streamTermsOf(
164
+ key: string,
165
+ read: Pick<MembershipRead, 'files' | 'floor'>,
166
+ me: string | undefined,
167
+ muted: ReadonlySet<string>,
168
+ ): StreamTerms {
169
+ const isMuted = muted.has(key)
170
+ if (fileContext(key) === undefined) return { member: false, muted: isMuted }
171
+ const folded = read.files.get(key)
172
+ if (folded) return { member: folded.member, since: folded.since, muted: isMuted }
173
+ if (me && authorOfAddress(key) === me) return { member: true, since: read.floor, muted: isMuted }
174
+ return { member: false, muted: isMuted }
175
+ }
176
+
177
+ /**
178
+ * Whether the horizon's read has a word on the viewer in this file: an event
179
+ * naming them within it, or the file is theirs. Without one, "not a member"
180
+ * may only mean they joined before the horizon; a list that must say whose a
181
+ * file is reads those over all history.
182
+ */
183
+ export function membershipJudges(key: string, read: Pick<MembershipRead, 'files'>, me: string | undefined): boolean {
184
+ return read.files.has(key) || (!!me && authorOfAddress(key) === me)
185
+ }