@estiva-app/interop 0.50.0 → 0.52.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.50.0",
3
+ "version": "0.52.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",
package/src/index.ts CHANGED
@@ -155,6 +155,7 @@ export {
155
155
  eventIdFromRef,
156
156
  urlPatternsOf,
157
157
  matchObjectUrl,
158
+ blockUrlOf,
158
159
  type UrlPattern,
159
160
  type MatchedObjectUrl,
160
161
  } from './objectUrl.js'
package/src/objectUrl.ts CHANGED
@@ -172,8 +172,19 @@ export interface MatchedObjectUrl {
172
172
  * only `identifier`; this is for one that wants to say where it is.
173
173
  */
174
174
  within?: { identifier: string; by: 'd' | 'id' }
175
+ /**
176
+ * One block of the object, when the pattern declares a `<block>` in its
177
+ * fragment and the URL carries one (SPEC §7.7, COM-2): Ship's block menu
178
+ * copies `…/issue/<slug>-<d>#block-<id>`. The block is optional — the same
179
+ * pattern still claims the URL without its fragment — so an app adds it to a
180
+ * shape it already declares rather than declaring a second one.
181
+ */
182
+ block?: string
175
183
  }
176
184
 
185
+ /** The placeholder a pattern's fragment uses for a block id. */
186
+ const BLOCK_PLACEHOLDER = '<block>'
187
+
177
188
  /**
178
189
  * Match a pasted URL against one app's declared shapes.
179
190
  *
@@ -247,14 +258,81 @@ export function matchObjectUrl(url: string, patterns: UrlPattern[]): MatchedObje
247
258
  }
248
259
  if (!satisfied) continue
249
260
 
250
- const match: MatchedObjectUrl = query
251
- ? { ...query, ...(kind === undefined ? {} : { kind }), within: path }
252
- : { ...path, ...(kind === undefined ? {} : { kind }) }
253
- if (!best || declared.length > best.specificity) best = { specificity: declared.length, match }
261
+ const block = readBlock(shape.hash, target.hash)
262
+ const match: MatchedObjectUrl = {
263
+ ...(query ? { ...query, within: path } : path),
264
+ ...(kind === undefined ? {} : { kind }),
265
+ ...(block === undefined ? {} : { block }),
266
+ }
267
+ // A filled `<block>` breaks a tie, so an app that declares the block shape
268
+ // beside its older shape loses no block to declaration order.
269
+ const specificity = declared.length * 2 + (block === undefined ? 0 : 1)
270
+ if (!best || specificity > best.specificity) best = { specificity, match }
254
271
  }
255
272
  return best?.match ?? null
256
273
  }
257
274
 
275
+ /**
276
+ * The block a URL's fragment names, by the pattern's `#…<block>…`; undefined
277
+ * when the pattern declares none, the URL has no fragment, or it does not fit.
278
+ * A fragment cut mid-escape names no block rather than throwing — the object
279
+ * still resolves, which is what the link was mostly for.
280
+ */
281
+ function readBlock(pattern: string, value: string): string | undefined {
282
+ const at = pattern.indexOf(BLOCK_PLACEHOLDER)
283
+ if (at === -1) return undefined
284
+ const before = pattern.slice(0, at)
285
+ const after = pattern.slice(at + BLOCK_PLACEHOLDER.length)
286
+ if (value.length <= before.length + after.length || !value.startsWith(before) || !value.endsWith(after)) {
287
+ return undefined
288
+ }
289
+ try {
290
+ const block = decodeURIComponent(value.slice(before.length, value.length - after.length))
291
+ return BLOCK_ID.test(block) ? block : undefined
292
+ } catch {
293
+ return undefined
294
+ }
295
+ }
296
+
297
+ /** The ids a reader takes from a URL — protocol's `partsOf` takes the same. */
298
+ const BLOCK_ID = /^[A-Za-z0-9_-]{1,64}$/
299
+
300
+ /**
301
+ * The link that opens one block of an object, built from the app's own `urls`
302
+ * shape for its kind — the outbound half of {@link matchObjectUrl}'s `block`.
303
+ *
304
+ * Built from `urls` rather than `web` because NIP-89's `web` template has one
305
+ * placeholder, `<bech32>`, and an app's `/o/<naddr>` redirect is not obliged to
306
+ * carry a fragment through. Returns undefined when the app declares no path
307
+ * shape for that kind with a `<block>` fragment; the caller then opens the
308
+ * object without the block, which is still the right object.
309
+ */
310
+ export function blockUrlOf(
311
+ patterns: UrlPattern[],
312
+ target: { kind: number; d: string; title?: string; block: string },
313
+ ): string | undefined {
314
+ // A `d` that is not a clean identifier would be spliced into the path raw
315
+ // (`../settings`), and `matchObjectUrl` could never read the link back.
316
+ if (identifierFromRef(target.d) !== target.d || !BLOCK_ID.test(target.block)) return undefined
317
+ for (const { pattern, kind } of patterns) {
318
+ if (kind !== target.kind) continue
319
+ const hashAt = pattern.indexOf('#')
320
+ if (hashAt === -1) continue
321
+ const path = pattern.slice(0, hashAt)
322
+ const hash = pattern.slice(hashAt + 1)
323
+ // A fragment route (`/#/issue/<d>`) is the legacy shape, never written.
324
+ if (hash.startsWith('/') || !hash.includes(BLOCK_PLACEHOLDER) || !path.includes('<d>')) continue
325
+ // Only `<d>` and `<block>` are known here; a shape with any other
326
+ // placeholder (`?thread=<id>`) would be emitted half-filled.
327
+ if (/<(?!slug>|d>)[^>]*>/.test(path)) continue
328
+ const ref = path.includes('<slug>-<d>') ? objectRef(target.d, target.title) : target.d
329
+ // Replacer functions, so a `$&` in an identifier is not a replacement pattern.
330
+ const base = path.replace(/<slug>-<d>|<d>/, () => ref)
331
+ return `${base}#${hash.replace(BLOCK_PLACEHOLDER, () => encodeURIComponent(target.block))}`
332
+ }
333
+ return undefined
334
+ }
335
+
258
336
  /** The identity a placeholder declares, read off the value in that position. */
259
337
  function readPlaceholder(placeholder: string, value: string): { identifier: string; by: 'd' | 'id' } | null {
260
338
  const wantsEventId = placeholder.includes('<id>')
@@ -286,6 +364,8 @@ function splitUrl(raw: string): {
286
364
  segments: string[]
287
365
  fragmented: boolean
288
366
  query: Record<string, string>
367
+ /** A fragment that is not a route — `block-<id>` — as written; '' when none. */
368
+ hash: string
289
369
  } | null {
290
370
  const match = /^(https?):\/\/([^/?#]+)([^?#]*)(?:\?([^#]*))?(?:#(.*))?$/i.exec(raw.trim())
291
371
  if (!match) return null
@@ -316,6 +396,7 @@ function splitUrl(raw: string): {
316
396
  segments: [...(path ?? '').split('/'), ...fragmentPath.split('/')].filter(Boolean),
317
397
  fragmented: fragmentPath !== '',
318
398
  query: parseQuery(search ?? ''),
399
+ hash: fragmentPath === '' ? (fragment ?? '') : '',
319
400
  }
320
401
  }
321
402
 
package/src/projection.ts CHANGED
@@ -30,7 +30,7 @@ import { planPlaceFile, planUnlistFile, type FolderRef } from './folders.js'
30
30
  the copy that lived here — a `kind:9` is never a comment (CON-20 migrated
31
31
  them), a reply is never a root, and `ts` is trusted only inside its own second.
32
32
  */
33
- import { byOrder, isCommentOn, orderingMs } from '@estiva-app/conversation'
33
+ import { anchorsOf, byOrder, isCommentOn, isReply, orderingMs } from '@estiva-app/conversation'
34
34
 
35
35
  /** Query the relay. Returns matching events; shape mirrors the HTTP bridge. */
36
36
  export type QueryFn = (filters: Record<string, unknown>[]) => Promise<SignedEvent[]>
@@ -357,12 +357,24 @@ function rootOf(event: SignedEvent): string {
357
357
  * discussion. A badge counting them said "3" beside an issue with one comment.
358
358
  * See `@estiva-app/conversation`'s `isCommentOn` for the per-kind rule, which
359
359
  * this passes the owner's declared comment kinds (§7.3).
360
+ *
361
+ * ## `replies`: the threads under those comments too (CON-34)
362
+ *
363
+ * A dot judges replies by their thread (SPEC §11.3), and a reply never comes
364
+ * back for `#a`: its lowercase tags name its parent comment, and the file is
365
+ * only in its uppercase `A` (§6.4). Asked with `replies`, each file gets a
366
+ * second filter by `#A`, and a reply is kept when its root is one of the
367
+ * comments this read found for the file — the root decides (C11), so a reply
368
+ * in a thread that only mentions the file, or under a root older than the
369
+ * limit, is not here. The messages are then roots and replies, told apart by
370
+ * `root === id`; a consumer that counts comments must not ask for them.
360
371
  */
361
372
  export async function conversationsOf(
362
373
  files: ForeignObject[],
363
374
  query: QueryFn,
364
375
  /** Warm from the read that produced these files; see {@link ProjectionCache}. */
365
376
  cache?: ProjectionCache,
377
+ options: { replies?: boolean } = {},
366
378
  ): Promise<Record<string, ConversationMessage[]>> {
367
379
  const addressed = files.flatMap((file) => {
368
380
  if (!file.address) return []
@@ -410,16 +422,31 @@ export async function conversationsOf(
410
422
  const conversations: Record<string, ConversationMessage[]> = {}
411
423
  for (const a of asked) conversations[a.ref] = []
412
424
 
425
+ const filters: Record<string, unknown>[] = asked.flatMap((a) =>
426
+ options.replies
427
+ ? [a.filter, { kinds: [KIND_COMMENT], '#A': [a.address], limit: CONVERSATION_LIMIT }]
428
+ : [a.filter],
429
+ )
430
+ /** The file in this list an event is a comment on (§6.4), by every `a` it carries. */
431
+ const commentedFile = (event: SignedEvent): string | undefined =>
432
+ event.tags
433
+ .filter((t) => t[0] === 'a' && t[1] && refOf.has(t[1]) && isCommentOn(event, t[1], kindsOf.get(t[1])))
434
+ .map((t) => refOf.get(t[1]))
435
+ .find((found) => found !== undefined)
436
+ /** Replies, kept until every root is in: which file a reply is in is its root's. */
437
+ const replies: SignedEvent[] = []
413
438
  const seen = new Set<string>()
414
- for (let start = 0; start < asked.length; start += MAX_FILTERS_PER_QUERY) {
415
- const events = await query(
416
- asked.slice(start, start + MAX_FILTERS_PER_QUERY).map((a) => a.filter),
417
- )
439
+ for (let start = 0; start < filters.length; start += MAX_FILTERS_PER_QUERY) {
440
+ const events = await query(filters.slice(start, start + MAX_FILTERS_PER_QUERY))
418
441
  for (const event of events) {
419
442
  // A relay may answer one event under two filters; counting it twice would
420
443
  // inflate the badge above what the panel then shows.
421
444
  if (seen.has(event.id)) continue
422
445
  seen.add(event.id)
446
+ if (options.replies && isReply(event)) {
447
+ replies.push(event)
448
+ continue
449
+ }
423
450
  /*
424
451
  Every `a` tag, not the first one.
425
452
 
@@ -434,15 +461,47 @@ export async function conversationsOf(
434
461
  came back for both; it belongs to the one whose discussion it is, and to
435
462
  neither when it merely mentions them. `isCommentOn` is §6.4's rule.
436
463
  */
437
- const ref = event.tags
438
- .filter((t) => t[0] === 'a' && t[1] && refOf.has(t[1]) && isCommentOn(event, t[1], kindsOf.get(t[1])))
439
- .map((t) => refOf.get(t[1]))
440
- .find((found) => found !== undefined)
464
+ const ref = commentedFile(event)
441
465
  if (ref !== undefined) {
442
466
  conversations[ref].push({ id: event.id, at: event.created_at, by: event.pubkey, root: rootOf(event) })
443
467
  }
444
468
  }
445
469
  }
470
+ if (replies.length > 0) {
471
+ /*
472
+ Each root by its own id only, never by the event its `E` names: any comment
473
+ on another file could carry this thread's root there and take its replies
474
+ (review, foundation#112). The ids are unique, so nothing overwrites.
475
+ */
476
+ const fileOfRoot = new Map<string, string>()
477
+ for (const [ref, messages] of Object.entries(conversations)) {
478
+ for (const m of messages) if (m.root === m.id) fileOfRoot.set(m.id, ref)
479
+ }
480
+ const addressOf = new Map(asked.map((a) => [a.ref, a.address]))
481
+ // A reply in a file's thread names that file in its `A` (§6.4), so one that
482
+ // does not is not counted there, whatever root it claims.
483
+ const inList = replies.filter((event) => anchorsOf(event).some((address) => refOf.has(address)))
484
+ /*
485
+ A new reply in an old thread: its root is past the `#a` limit, so this
486
+ read did not find it — on a busy file, exactly the reply the dot exists
487
+ for. Those roots are asked by id in one request, capped at the limit so
488
+ replies naming made-up roots cannot multiply the reads, and decide as any
489
+ root does (C11). Listed for attribution only, not as messages.
490
+ */
491
+ const missing = [...new Set(inList.map(rootOf).filter((root) => !fileOfRoot.has(root)))].slice(0, CONVERSATION_LIMIT)
492
+ if (missing.length > 0) {
493
+ for (const root of await query([{ ids: missing, limit: missing.length }])) {
494
+ const ref = commentedFile(root)
495
+ if (ref !== undefined && !fileOfRoot.has(root.id)) fileOfRoot.set(root.id, ref)
496
+ }
497
+ }
498
+ for (const event of inList) {
499
+ const root = rootOf(event)
500
+ const ref = fileOfRoot.get(root)
501
+ if (ref === undefined || !anchorsOf(event).includes(addressOf.get(ref) as string)) continue
502
+ conversations[ref].push({ id: event.id, at: event.created_at, by: event.pubkey, root })
503
+ }
504
+ }
446
505
  for (const messages of Object.values(conversations)) messages.sort((a, b) => a.at - b.at || (a.id < b.id ? -1 : 1))
447
506
  return conversations
448
507
  }