@estiva-app/interop 0.67.0 → 0.69.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/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@estiva-app/interop",
3
- "version": "0.67.0",
3
+ "version": "0.69.0",
4
4
  "description": "Render and act on another app's objects from its published NIP-89 manifest. The owner defines the projection; the consumer decides how it looks.",
5
5
  "license": "MIT",
6
6
  "type": "module",
@@ -47,12 +47,12 @@
47
47
  "prepublishOnly": "npm run build"
48
48
  },
49
49
  "peerDependencies": {
50
- "@estiva-app/conversation": ">=0.6.1",
51
- "@estiva-app/protocol": ">=0.24.0"
50
+ "@estiva-app/conversation": ">=0.20.0",
51
+ "@estiva-app/protocol": ">=0.44.0"
52
52
  },
53
53
  "devDependencies": {
54
- "@estiva-app/conversation": ">=0.6.1",
55
- "@estiva-app/protocol": ">=0.24.0",
54
+ "@estiva-app/conversation": ">=0.20.0",
55
+ "@estiva-app/protocol": ">=0.44.0",
56
56
  "typescript": "~5.9.3"
57
57
  }
58
58
  }
package/src/index.ts CHANGED
@@ -147,6 +147,25 @@ export {
147
147
  type MoveRefusal,
148
148
  } from './folders.js'
149
149
 
150
+ /**
151
+ * What an app link names, and where a file is mentioned — once for every app
152
+ * (SPEC §7.7, §13.1, §6.8; PEEKM-7). Each app passes its relay read; none
153
+ * keeps a resolver of its own.
154
+ */
155
+ export {
156
+ linkReader,
157
+ linkTagsOf,
158
+ linksIn,
159
+ writtenOpenerOf,
160
+ within,
161
+ MAX_LINKS_ASKED,
162
+ type LinkAnswer,
163
+ type LinkReader,
164
+ type LinkReaderOptions,
165
+ type OwnPlace,
166
+ } from './links.js'
167
+ export { mentionedInFilter, mentionedInOf, readMentionedIn, MENTIONED_IN_LIMIT, type MentionedIn } from './mentions.js'
168
+
150
169
  /**
151
170
  * RFC 0.5 §7's URL grammar — how an object is named in an address bar, and how
152
171
  * a pasted link is matched back to one.
package/src/links.ts ADDED
@@ -0,0 +1,312 @@
1
+ /**
2
+ * What an app link names, once for every app — SPEC §7.7, §13.1, §13.6.2
3
+ * (PEEKM-7). The chip a pasted link becomes, the card under a comment, the
4
+ * block a link to one block shows, the `a` and `q` tags a send or an edit
5
+ * carries, and where a card written as a URL opens: Peek, Ship, Leaf and the
6
+ * agent each kept a copy of this, and they drifted (Leaf retried, Ship tagged
7
+ * a URL in code, only Leaf's opener was https only).
8
+ *
9
+ * A URL names an object when a published manifest's `urls` pattern claims its
10
+ * host and `<type>`, and then **one author** holds that `d`: the `#d` query
11
+ * asks for two, and a `d` two authors hold names nothing, so somebody
12
+ * publishing the same `(kind, d)` cannot put their object's card or its
13
+ * mention under a link to another's. Only an addressable kind is asked: a
14
+ * manifest anyone can publish could otherwise point a path at a kind where a
15
+ * `d` is no identity. A link to one block (`#block-<id>`) names its file, and
16
+ * the block is its part (§13.6.1). A URL that names an event names its id.
17
+ *
18
+ * Asked once per link for the reader's life: a link names the same object for
19
+ * as long as its owner's manifest does. A read that failed is forgotten, so the
20
+ * next ask tries again, and is said as a change after 5, 10 and 20 seconds so
21
+ * whoever still draws from it asks.
22
+ *
23
+ * why: https://github.com/estiva-app/estiva-docs/blob/main/decisions/a-files-path-is-the-same-on-every-apps-host.md
24
+ * why: https://github.com/estiva-app/estiva-docs/blob/main/decisions/an-edit-says-what-the-message-links-now.md
25
+ */
26
+ import { MAX_PARTS } from '@estiva-app/conversation'
27
+ import { partTag, valuesIn, type LinkResolver, type PartPointer, type RenderBlock } from '@estiva-app/protocol'
28
+ import { matchObjectUrl, urlPatternsOf, type UrlPattern } from './objectUrl.js'
29
+ import type { QueryFn } from './projection.js'
30
+
31
+ /** What one link names: an address or a message's event id, and the block when it links to one. */
32
+ export interface LinkAnswer {
33
+ value: string | null
34
+ block?: PartPointer
35
+ }
36
+
37
+ /** The comment a body is written in: its file and the message it replies to, which its tags never repeat as a mention. */
38
+ export interface OwnPlace {
39
+ /** The file the comment is on, `kind:pubkey:d`: its `A`, never also an `a` for a link to it. */
40
+ file?: string
41
+ /** The event id it replies to: its `e`, never also a `q`. */
42
+ parent?: string
43
+ }
44
+
45
+ export interface LinkReaderOptions {
46
+ /** A read as the viewer. Throws when the relay could not be asked. */
47
+ query: QueryFn
48
+ /**
49
+ * The published manifests, `kind:31990` (§7.2). Omitted: one read of every
50
+ * manifest through `query`, kept for the reader's life and forgotten when it
51
+ * fails. An app that already holds them passes its own.
52
+ */
53
+ manifests?: () => Promise<readonly { tags: string[][] }[]>
54
+ /** How many times a failed read is said as a change, after 5, 10, 20… seconds. Default 3; 0 says none. */
55
+ retries?: number
56
+ }
57
+
58
+ export interface LinkReader {
59
+ /** What one link names; rejects when the relay could not be asked (and the next ask tries again). */
60
+ answerOf(url: string): Promise<LinkAnswer>
61
+ /**
62
+ * Ask what each of these links names; settles when every answer is in, and
63
+ * rejects when a read failed (it left no answer), so a `LinkChips` forgets
64
+ * those links and asks again.
65
+ */
66
+ ask(urls: readonly string[]): Promise<void>
67
+ /** What a link names, from what has come back: undefined until it has, and for nothing. A `LinkResolver`. */
68
+ known: LinkResolver
69
+ /** The file and block a link to one block names, from what has come back. */
70
+ knownBlock(url: string): PartPointer | undefined
71
+ /** Whether a link's answer has come back, naming something or nothing. */
72
+ answered(url: string): boolean
73
+ /** Called each time an answer comes back, or a failed one may be asked again. Returns the unsubscribe. */
74
+ changed(listener: () => void): () => void
75
+ /** How many times {@link changed} has fired: a snapshot for `useSyncExternalStore`. */
76
+ version(): number
77
+ /**
78
+ * The `a`, `q` and `part` tags a body earns ({@link linkTagsOf}), asking
79
+ * first what its links name and waiting at most `waitMs` (default 5 s): a
80
+ * link not answered by then earns nothing, and the body keeps it.
81
+ */
82
+ tagsFor(blocks: readonly RenderBlock[], own: OwnPlace, options?: { waitMs?: number; edit?: boolean }): Promise<string[][]>
83
+ /** {@link writtenOpenerOf} against the hosts the manifests read so far declare. */
84
+ opener(url: string | undefined, opens: string | undefined, origin: string): string | undefined
85
+ /** Every host an app declares its paths on, as the manifests read so far said. */
86
+ declaredOrigins(): ReadonlySet<string>
87
+ }
88
+
89
+ // The runtime's, in every app and in node; this package compiles without the DOM or node types.
90
+ declare const URL: { new (raw: string, base?: string): { origin: string } }
91
+ declare const setTimeout: (run: () => void, ms: number) => unknown
92
+ declare const clearTimeout: (timer: unknown) => void
93
+
94
+ /** Wait for `work`, but no longer than `ms`; never rejects. */
95
+ export async function within(work: Promise<unknown>, ms: number): Promise<void> {
96
+ let timer: unknown
97
+ await Promise.race([
98
+ work.then(
99
+ () => {},
100
+ () => {},
101
+ ),
102
+ new Promise<void>((resolve) => {
103
+ timer = setTimeout(resolve, ms)
104
+ }),
105
+ ])
106
+ clearTimeout(timer)
107
+ }
108
+
109
+ /** How many links one body asks about, the first ones — as `LinkChips`' `limit`: each answer can cost a relay query. */
110
+ export const MAX_LINKS_ASKED = 24
111
+
112
+ const EVENT_ID = /^[0-9a-f]{64}$/i
113
+ const RETRY_MS = 5000
114
+
115
+ /** NIP-89's handler information, where an app publishes its manifest and `urls` (§7.2). */
116
+ const KIND_APP_HANDLER = 31990
117
+
118
+ /** One link reader for an app: its relay reads, and the manifests it holds. */
119
+ export function linkReader(options: LinkReaderOptions): LinkReader {
120
+ const { query, retries = 3 } = options
121
+ const origins = new Set<string>()
122
+ let shapes: Promise<UrlPattern[]> | null = null
123
+ const shapesOf = (): Promise<UrlPattern[]> => {
124
+ if (shapes) return shapes
125
+ const read = (options.manifests ?? (() => query([{ kinds: [KIND_APP_HANDLER], limit: 500 }])))().then((manifests) => {
126
+ const found = manifests.flatMap((manifest) => urlPatternsOf(manifest))
127
+ for (const shape of found) {
128
+ try {
129
+ origins.add(new URL(shape.pattern).origin)
130
+ } catch {
131
+ // A shape that is not a URL declares no host.
132
+ }
133
+ }
134
+ return found
135
+ })
136
+ shapes = read
137
+ // A failed read must not poison the reader, nor an empty one (a relay still
138
+ // starting, a read before sign-in): the next link asks again.
139
+ read.then(
140
+ (found) => {
141
+ if (found.length === 0 && shapes === read) shapes = null
142
+ },
143
+ () => {
144
+ if (shapes === read) shapes = null
145
+ },
146
+ )
147
+ return read
148
+ }
149
+
150
+ const answer = async (url: string): Promise<LinkAnswer> => {
151
+ const shapes = await shapesOf()
152
+ // No manifest read yet is no answer: kept as one, the link would name nothing for the reader's life.
153
+ if (shapes.length === 0) throw new Error('No app manifest has been read yet.')
154
+ const hit = matchObjectUrl(url, shapes)
155
+ if (!hit) return { value: null }
156
+ if (hit.by === 'id') return { value: EVENT_ID.test(hit.identifier) ? hit.identifier.toLowerCase() : null }
157
+ // A path on another app's host can read as several kinds (§7.7, LTX-6): ask under each addressable one.
158
+ const kinds = (hit.kinds ?? (hit.kind === undefined ? undefined : [hit.kind]))?.filter((kind) => kind >= 30000 && kind < 40000)
159
+ if (kinds?.length === 0) return { value: null }
160
+ // A shape that names no kind asks every one; only an addressable answer counts.
161
+ const found = (await query([{ '#d': [hit.identifier], limit: 2, ...(kinds ? { kinds } : {}) }])).filter((event) => event.kind >= 30000 && event.kind < 40000)
162
+ const authors = new Set(found.map((event) => `${event.kind}:${event.pubkey.toLowerCase()}`))
163
+ if (authors.size !== 1) return { value: null }
164
+ const address = `${[...authors][0]}:${hit.identifier}`
165
+ return hit.block === undefined ? { value: address } : { value: address, block: { address, block: hit.block } }
166
+ }
167
+
168
+ const asked = new Map<string, Promise<LinkAnswer>>()
169
+ const known = new Map<string, LinkAnswer>()
170
+ const failures = new Map<string, number>()
171
+ const listeners = new Set<() => void>()
172
+ let answered = 0
173
+ const changed = () => {
174
+ answered += 1
175
+ for (const listener of listeners) listener()
176
+ }
177
+
178
+ const answerOf = (url: string): Promise<LinkAnswer> => {
179
+ let pending = asked.get(url)
180
+ if (!pending) {
181
+ pending = answer(url).then(
182
+ (found) => {
183
+ known.set(url, found)
184
+ changed()
185
+ return found
186
+ },
187
+ (error: unknown) => {
188
+ asked.delete(url)
189
+ const failed = failures.get(url) ?? 0
190
+ failures.set(url, failed + 1)
191
+ if (failed < retries) setTimeout(changed, RETRY_MS * 2 ** failed)
192
+ throw error
193
+ },
194
+ )
195
+ asked.set(url, pending)
196
+ }
197
+ return pending
198
+ }
199
+
200
+ const knownValue: LinkResolver = (url) => known.get(url)?.value ?? undefined
201
+ const knownBlock = (url: string) => known.get(url)?.block
202
+
203
+ return {
204
+ answerOf,
205
+ async ask(urls) {
206
+ const waiting = [...new Set(urls)].filter((url) => !known.has(url))
207
+ await Promise.allSettled(waiting.map(answerOf))
208
+ if (waiting.some((url) => !known.has(url))) throw new Error('A link could not be asked about; asked again later.')
209
+ },
210
+ known: knownValue,
211
+ knownBlock,
212
+ answered: (url) => known.has(url),
213
+ changed(listener) {
214
+ listeners.add(listener)
215
+ return () => {
216
+ listeners.delete(listener)
217
+ }
218
+ },
219
+ version: () => answered,
220
+ async tagsFor(blocks, own, { waitMs = 5000, edit = false } = {}) {
221
+ const urls = linksIn(blocks).slice(0, MAX_LINKS_ASKED)
222
+ const waiting = urls.filter((url) => !known.has(url))
223
+ if (waiting.length > 0) await within(Promise.allSettled(waiting.map(answerOf)), waitMs)
224
+ const first = new Set(urls)
225
+ const resolve: LinkResolver = (url) => (first.has(url) ? knownValue(url) : undefined)
226
+ return linkTagsOf(blocks, own, resolve, edit ? undefined : (url) => (first.has(url) ? knownBlock(url) : undefined))
227
+ },
228
+ opener: (url, opens, origin) => writtenOpenerOf(url, opens, origin, origins),
229
+ declaredOrigins: () => origins,
230
+ }
231
+ }
232
+
233
+ /**
234
+ * Every link a body names something by, in the order it names them: the URLs
235
+ * {@link valuesIn} asks a `LinkResolver` about — bare, or a link on words'
236
+ * target, and none in code. What a sender asks about before it tags.
237
+ */
238
+ export function linksIn(blocks: readonly RenderBlock[]): string[] {
239
+ const urls: string[] = []
240
+ valuesIn(blocks, (url) => {
241
+ urls.push(url)
242
+ return undefined
243
+ })
244
+ return [...new Set(urls)]
245
+ }
246
+
247
+ /**
248
+ * The tags a message's body earns for what it names (§13.1, §13.6.1): an `a`
249
+ * per address and a `q` per message, by a `nostr:` reference or an app link
250
+ * `resolve` answers, in the order the body first names them; then one `part`
251
+ * per file a link to one of its blocks names, the first link's, when
252
+ * `blockOf` is given. The comment's own file earns neither an `a` nor a part
253
+ * (it is the `A`), and the message it replies to no `q` (it is the `e`).
254
+ *
255
+ * A send and an edit carry the same `a` and `q` set: an edit says what the
256
+ * message links now. An edit carries no `part` (pass no `blockOf`), and a
257
+ * person is never here: `p` and `urgent` stay as the send wrote them.
258
+ *
259
+ * why: https://github.com/estiva-app/estiva-docs/blob/main/decisions/an-edit-says-what-the-message-links-now.md
260
+ */
261
+ export function linkTagsOf(
262
+ blocks: readonly RenderBlock[],
263
+ own: OwnPlace,
264
+ resolve: LinkResolver,
265
+ blockOf?: (url: string) => PartPointer | undefined,
266
+ ): string[][] {
267
+ const file = own.file && sameValue(own.file)
268
+ const parent = own.parent?.toLowerCase()
269
+ const tags: string[][] = []
270
+ for (const value of valuesIn(blocks, resolve)) {
271
+ if (EVENT_ID.test(value)) {
272
+ if (value !== parent) tags.push(['q', value])
273
+ } else if (value !== file) tags.push(['a', value])
274
+ }
275
+ if (blockOf) {
276
+ const parts = new Map<string, string>()
277
+ for (const url of linksIn(blocks)) {
278
+ const part = blockOf(url)
279
+ if (part && sameValue(part.address) !== file && !parts.has(part.address)) parts.set(part.address, part.block)
280
+ }
281
+ // As many as a box shows under it (conversation's `boxLinksOf`): a part the box did not draw is not sent.
282
+ for (const [address, block] of [...parts].slice(0, MAX_PARTS)) tags.push(partTag(address, block))
283
+ }
284
+ return tags
285
+ }
286
+
287
+ /** An address as `valuesIn` spells it: the kind and pubkey as hex, the `d` as written. */
288
+ function sameValue(address: string): string {
289
+ const [kind, pubkey = '', ...d] = address.split(':')
290
+ return `${kind}:${pubkey.toLowerCase()}:${d.join(':')}`
291
+ }
292
+
293
+ /**
294
+ * Where a card or chip written as a URL opens: the address as written, in the
295
+ * app it names (§7.7, LTX-6), so `leaf.estiva.app/issue/…` opens Leaf, not
296
+ * Ship. Undefined for anything but https, and for a host that is neither this
297
+ * app's (`origin`), the one its file opens on (`opens`), nor one an app
298
+ * declares: a card that draws one file never opens a site no app serves from
299
+ * (WBM-11 security review). The same rule in every app.
300
+ *
301
+ * why: https://github.com/estiva-app/estiva-docs/blob/main/decisions/a-files-path-is-the-same-on-every-apps-host.md
302
+ */
303
+ export function writtenOpenerOf(url: string | undefined, opens: string | undefined, origin: string, declared: ReadonlySet<string>): string | undefined {
304
+ if (!url || !/^https:\/\//i.test(url)) return undefined
305
+ try {
306
+ const at = new URL(url).origin
307
+ const opensAt = opens ? new URL(opens, origin).origin : undefined
308
+ return at === origin || at === opensAt || declared.has(at) ? url : undefined
309
+ } catch {
310
+ return undefined
311
+ }
312
+ }
@@ -0,0 +1,119 @@
1
+ /**
2
+ * Where a file is mentioned — its "Mentioned in", once for every app (SPEC
3
+ * §6.4, §6.8, PEEKM-7). Peek's file panel and Ship's Activity each read it
4
+ * their own way: Peek dropped a row an edit took a `nostr:` reference out of,
5
+ * Ship kept every first version, and neither saw a link an edit added.
6
+ *
7
+ * A file lists a message while the message's **latest words** link it. The
8
+ * candidates are every message, comment and edit pointing at the file by `a`
9
+ * (an edit carries the `a` its new words earn); an edit stands for the message
10
+ * it edits; and each is confirmed against the folded body, by a `nostr:`
11
+ * reference or an app link that names the file. A message the reader cannot
12
+ * read lists nothing, whatever its edits point at. The file's own conversation
13
+ * is not a mention of it.
14
+ *
15
+ * why: https://github.com/estiva-app/estiva-docs/blob/main/decisions/an-edit-says-what-the-message-links-now.md
16
+ * why: https://github.com/estiva-app/estiva-docs/blob/main/decisions/activity-lists-only-mentions-from-elsewhere.md
17
+ */
18
+ import { anchorsOf, editsByTarget, editTargetOf, isCommentOn, KIND_COMMENT, KIND_EDIT, KIND_MESSAGE } from '@estiva-app/conversation'
19
+ import { toRenderTree, valuesIn, type LinkResolver, type SignedEvent } from '@estiva-app/protocol'
20
+ import { linksIn, within, type LinkReader } from './links.js'
21
+ import type { QueryFn } from './projection.js'
22
+
23
+ /** One message that mentions the file, as its latest words say. */
24
+ export interface MentionedIn {
25
+ /** The message as sent: a `kind:1111` comment or a `kind:9` message. Where it was said, its thread, its author. */
26
+ event: SignedEvent
27
+ /** Its latest words: the latest edit's, or its own. */
28
+ body: string
29
+ /** The latest edit, when there is one: its files and cards replace the message's (§6.8). */
30
+ edit?: SignedEvent
31
+ }
32
+
33
+ /** Enough for a list that is scanned, not read; the oldest pointers are what a cap drops. */
34
+ export const MENTIONED_IN_LIMIT = 200
35
+
36
+ /** The one filter for the candidates: every message, comment and edit pointing at the file. */
37
+ export function mentionedInFilter(address: string, limit = MENTIONED_IN_LIMIT): Record<string, unknown> {
38
+ return { kinds: [KIND_COMMENT, KIND_MESSAGE, KIND_EDIT], '#a': [address], limit }
39
+ }
40
+
41
+ const isMessage = (event: SignedEvent) => event.kind === KIND_COMMENT || event.kind === KIND_MESSAGE
42
+
43
+ /**
44
+ * The messages among `events` that list under the file, newest first.
45
+ *
46
+ * `events` holds the candidates ({@link mentionedInFilter}), the messages their
47
+ * edits edit, and every edit of each message; `resolveLink` what the app links
48
+ * in their words name. `commentKinds` is the file's owner's comment kinds
49
+ * (`isCommentOn`): a message on the file itself is not a mention of it.
50
+ * `unanswered` says which links could not be asked about: a message whose
51
+ * latest version points at the file and holds one keeps its row until the
52
+ * link can be read, rather than lose it to a failed read.
53
+ */
54
+ export function mentionedInOf(
55
+ events: readonly SignedEvent[],
56
+ address: string,
57
+ resolveLink?: LinkResolver,
58
+ commentKinds?: readonly number[],
59
+ unanswered: (url: string) => boolean = () => false,
60
+ ): MentionedIn[] {
61
+ const messages = new Map<string, SignedEvent>()
62
+ for (const event of events) if (isMessage(event)) messages.set(event.id.toLowerCase(), event)
63
+ const edits = editsByTarget(events)
64
+ const pointed = new Set<string>()
65
+ for (const event of events) {
66
+ if (!event.tags.some((t) => t[0] === 'a' && t[1] === address)) continue
67
+ const id = event.kind === KIND_EDIT ? editTargetOf(event) : isMessage(event) ? event.id.toLowerCase() : undefined
68
+ if (id) pointed.add(id)
69
+ }
70
+ const file = valueOf(address)
71
+ const out: MentionedIn[] = []
72
+ for (const id of pointed) {
73
+ const event = messages.get(id)
74
+ if (!event) continue
75
+ if (anchorsOf(event).includes(address) || isCommentOn(event, address, commentKinds)) continue
76
+ // An edit by anyone but the author is not the message's (the relay refuses one; a reader does not trust that).
77
+ const edit = edits.get(id)?.filter((e) => e.pubkey === event.pubkey).at(-1)
78
+ const body = edit?.content ?? event.content
79
+ const tree = toRenderTree(body, 'marker')
80
+ const pointsNow = (edit ?? event).tags.some((t) => t[0] === 'a' && t[1] === address)
81
+ if (!valuesIn(tree, resolveLink).includes(file) && !(pointsNow && linksIn(tree).some(unanswered))) continue
82
+ out.push(edit ? { event, body, edit } : { event, body })
83
+ }
84
+ return out.sort((a, b) => b.event.created_at - a.event.created_at)
85
+ }
86
+
87
+ /**
88
+ * {@link mentionedInOf} as the viewer: the candidates, then the messages their
89
+ * edits edit and every edit of each message, then what the links in their
90
+ * latest words name, asked through `links` and waited for at most `waitMs`.
91
+ * Throws when a read is refused, so an unreadable relay and a file nobody
92
+ * mentions are not the same empty list.
93
+ */
94
+ export async function readMentionedIn(
95
+ query: QueryFn,
96
+ address: string,
97
+ options: { links?: LinkReader; limit?: number; waitMs?: number; commentKinds?: readonly number[] } = {},
98
+ ): Promise<MentionedIn[]> {
99
+ const candidates = await query([mentionedInFilter(address, options.limit)])
100
+ const held = new Set(candidates.filter(isMessage).map((e) => e.id.toLowerCase()))
101
+ const missing = [...new Set(candidates.filter((e) => e.kind === KIND_EDIT).map(editTargetOf))].filter((id): id is string => !!id && !held.has(id))
102
+ const targets = missing.length ? await query([{ ids: missing, kinds: [KIND_COMMENT, KIND_MESSAGE] }]) : []
103
+ const ids = [...held, ...targets.map((e) => e.id.toLowerCase())]
104
+ const edits = ids.length ? await query([{ kinds: [KIND_EDIT], '#e': ids, limit: 1000 }]) : []
105
+ const events = [...candidates, ...targets, ...edits]
106
+ const links = options.links
107
+ if (!links) return mentionedInOf(events, address, undefined, options.commentKinds, () => true)
108
+ // Every link in a candidate's latest words: read as if each named the file, so each candidate holding one is kept to ask.
109
+ const urls = [...new Set(mentionedInOf(events, address, () => address, options.commentKinds).flatMap((m) => linksIn(toRenderTree(m.body, 'marker'))))]
110
+ const waiting = urls.filter((url) => !links.answered(url))
111
+ if (waiting.length) await within(links.ask(waiting), options.waitMs ?? 5000)
112
+ return mentionedInOf(events, address, links.known, options.commentKinds, (url) => !links.answered(url))
113
+ }
114
+
115
+ /** The address as `valuesIn` spells it. */
116
+ function valueOf(address: string): string {
117
+ const [kind, pubkey = '', ...d] = address.split(':')
118
+ return `${kind}:${pubkey.toLowerCase()}:${d.join(':')}`
119
+ }
package/src/projection.ts CHANGED
@@ -227,6 +227,9 @@ export const KIND_MESSAGE = 9
227
227
  */
228
228
  const KIND_DELETION = 5
229
229
 
230
+ /** The tags a comment's body earns for what it names: `ActionEventArgs.linkTags`. */
231
+ const LINK_TAG_NAMES = new Set(['a', 'q', 'part'])
232
+
230
233
  /**
231
234
  * Every kind an app's comments might be under — what it publishes **now**, plus
232
235
  * any it has published before.
@@ -4154,8 +4157,14 @@ async function walkArchivedAbove(
4154
4157
  * every change naming its addresses — titles, statuses, moves — not only the
4155
4158
  * archives, and a relay answers newest first, so a small group keeps the
4156
4159
  * archive change inside the page.
4160
+ *
4161
+ * Ten, because the relay slows sharply past about twelve values in one `#a`
4162
+ * on `kind:1851`, while many small filters in one request do not. Measured as
4163
+ * the agent on production 2026-10-26, 49 Folder channels with no change among
4164
+ * them: one filter of 49 took 15–20 s, of 25 3.5 s, of 12 0.3 s, and 49
4165
+ * filters of one 0.3–0.5 s (43e9a775). `kind:1111` stayed under a second at 49.
4157
4166
  */
4158
- const ARCHIVE_READ_GROUP = 25
4167
+ const ARCHIVE_READ_GROUP = 10
4159
4168
 
4160
4169
  /**
4161
4170
  * Identifiers per root filter in {@link resolveParents}. A root read answers
@@ -5804,6 +5813,14 @@ export interface ActionEventArgs {
5804
5813
  * why: https://github.com/estiva-app/estiva-docs/blob/main/decisions/a-reply-on-a-page-keeps-its-threads-place.md
5805
5814
  */
5806
5815
  replyTo?: { id: string; kind: number; author: string; place?: readonly string[][] }
5816
+ /**
5817
+ * The `a`, `q` and `part` tags a comment's body earns for what it names, by a
5818
+ * `nostr:` reference or an app link — {@link LinkReader.tagsFor}, asked by
5819
+ * the caller, which holds the relay (SPEC §13.1). Only for `comment`; any
5820
+ * other tag here is left out, and so is one naming the comment's own file or
5821
+ * the comment it answers.
5822
+ */
5823
+ linkTags?: readonly string[][]
5807
5824
  /**
5808
5825
  * The format the action's prose value is in, when it is not marker text —
5809
5826
  * `'estiva-blocks-1'` for a block document (SPEC §7.3's `format`, MAN-1).
@@ -6073,6 +6090,13 @@ function buildOneActionEvent(args: ActionEventArgs): UnsignedActionEvent | strin
6073
6090
  if (ps.length >= MAX_MENTIONED_PEOPLE) break
6074
6091
  if (!ps.some((t) => t[1] === person)) tags.push(['p', person])
6075
6092
  }
6093
+ // What the body links, as the apps' sends tag it, after the people (§13.1, PEEKM-7).
6094
+ for (const tag of args.linkTags ?? []) {
6095
+ if (!LINK_TAG_NAMES.has(tag[0]) || typeof tag[1] !== 'string') continue
6096
+ if ((tag[0] === 'a' || tag[0] === 'part') && tag[1] === address) continue
6097
+ if (tag[0] === 'q' && tag[1] === replyTo?.id) continue
6098
+ if (!tags.some((t) => t[0] === tag[0] && t[1] === tag[1])) tags.push([...tag])
6099
+ }
6076
6100
  }
6077
6101
  // A move also names its new parent where a relay indexes it (SPEC §7.2, FOL-45):
6078
6102
  // `value` is not indexed, so without this no read by the new parent finds a
@@ -6320,7 +6344,24 @@ export interface FolderContents extends FolderSummary {
6320
6344
  * goes; a sidebar built by walking something else would inherit exactly that.
6321
6345
  * This asks for folders by kind.
6322
6346
  */
6323
- export async function listFolders(query: QueryFn): Promise<FolderSummary[]> {
6347
+ export async function listFolders(
6348
+ query: QueryFn,
6349
+ options: {
6350
+ /**
6351
+ * `false` leaves out what only a record's channel needs — a Ship project's
6352
+ * conversation placed under the Folder that lists the project, and archived
6353
+ * with it — and so reads only the Folders' own archives. Those channels have
6354
+ * no state, so {@link topLevelFolders} is the same either way.
6355
+ *
6356
+ * For a reader that walks Folders for their files and draws no dots (the
6357
+ * agent's Peek topics): placing them reads every change to every file a
6358
+ * Folder lists, and a text save is a whole document. Measured as the agent
6359
+ * on production 2026-10-26: 149 s and 22.8 MB with them, where the Folders'
6360
+ * records alone were 0.9 s.
6361
+ */
6362
+ recordChannels?: boolean
6363
+ } = {},
6364
+ ): Promise<FolderSummary[]> {
6324
6365
  const { events, byId } = await readFolderRecords(query)
6325
6366
  /*
6326
6367
  A folder listed in another folder's state is a file there. Read off the
@@ -6342,7 +6383,17 @@ export async function listFolders(query: QueryFn): Promise<FolderSummary[]> {
6342
6383
  listedIn.set(identifier, containers)
6343
6384
  }
6344
6385
  }
6345
- const { recordsOf, archives, rootOf } = await placeRecordChannels(events, byId, listedIn, query)
6386
+ const { recordsOf, archives, rootOf } =
6387
+ options.recordChannels === false
6388
+ ? {
6389
+ recordsOf: new Map<string, string[]>(),
6390
+ archives: await readArchiveChanges(
6391
+ [...byId.values()].flatMap((folder) => (folder.channel ? [folder.channel] : [])),
6392
+ query,
6393
+ ),
6394
+ rootOf: new Map<string, SignedEvent>(),
6395
+ }
6396
+ : await placeRecordChannels(events, byId, listedIn, query)
6346
6397
  for (const [id, containers] of listedIn) {
6347
6398
  const folder = byId.get(id)
6348
6399
  if (folder) folder.listedIn = containers
@@ -6802,6 +6853,17 @@ export async function resolveFolderContents(
6802
6853
  * card ({@link ArchiveReadOptions.folderFiles}).
6803
6854
  */
6804
6855
  listedOnly?: boolean
6856
+ /**
6857
+ * Only the listed files of these kinds: the rest are neither read nor
6858
+ * returned, as if no app drew them. Every rule above still holds for the
6859
+ * ones kept — a parent of another kind is read as a link reads it.
6860
+ *
6861
+ * For a reader that draws only some kinds (the agent's Peek topics: bare
6862
+ * files and nested Folders), since every listed file is read with its whole
6863
+ * change history: Estiva HQ cost 75 s and 11 MB on 2026-10-26, nearly all
6864
+ * of it project descriptions.
6865
+ */
6866
+ kinds?: readonly number[]
6805
6867
  } = {},
6806
6868
  ): Promise<FolderContents> {
6807
6869
  // 1. The folder itself. Both kinds in one trip: the state is the model and
@@ -6833,7 +6895,7 @@ export async function resolveFolderContents(
6833
6895
  : {}),
6834
6896
  }
6835
6897
 
6836
- const { addresses, placed } = state
6898
+ const { addresses: everyAddress, placed } = state
6837
6899
  ? // §5.2: one tag type lists every file, topics included, with no special
6838
6900
  // case. The order is the folder's, so it is preserved rather than sorted.
6839
6901
  {
@@ -6843,6 +6905,10 @@ export async function resolveFolderContents(
6843
6905
  : options.listedOnly
6844
6906
  ? { addresses: [], placed: new Map<string, SignedEvent[]>() }
6845
6907
  : await addressesByContainment(folder, query)
6908
+ const { kinds } = options
6909
+ const addresses = kinds
6910
+ ? everyAddress.filter((address) => kinds.includes(addressPointerOf(address)?.kind ?? NaN))
6911
+ : everyAddress
6846
6912
 
6847
6913
  if (addresses.length === 0) {
6848
6914
  // Nothing listed, so no change query to ride on: the Folder's own archive
@@ -6902,7 +6968,9 @@ export async function resolveFolderContents(
6902
6968
  // for it here only repeated them: its 500 newest are among each group's page
6903
6969
  // (APP-2, where it was most of a second copy of every change).
6904
6970
  const otherChangeKinds = changeKinds.filter((kind) => kind !== ARCHIVE_RULE.changeKind)
6905
- const events = await query([
6971
+ // Chunked: at ten addresses per archive filter, a Folder of about 1,200 files
6972
+ // would pass the relay's filters-per-request ceiling in one request.
6973
+ const events = await queryChunked([
6906
6974
  ...[...groups.values()].map(({ pointer, addresses: group }) => ({
6907
6975
  kinds: [pointer.kind],
6908
6976
  authors: [pointer.pubkey],
@@ -6915,7 +6983,7 @@ export async function resolveFolderContents(
6915
6983
  ...archiveFilters(channelAddress ? [...addresses, channelAddress] : addresses),
6916
6984
  // A Folder listed here counts its archive only from its own admins (§3.2). Same request.
6917
6985
  ...(nestedFolderIds.length ? [{ kinds: [KIND_CHANNEL_ADMINS], '#d': nestedFolderIds, limit: nestedFolderIds.length }] : []),
6918
- ])
6986
+ ], query)
6919
6987
  const ownArchive = folderArchiveOf(events, summary)
6920
6988
  if (ownArchive) summary.archived = ownArchive
6921
6989