@estiva-app/interop 0.62.0 → 0.64.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.62.0",
3
+ "version": "0.64.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/projection.ts CHANGED
@@ -3292,6 +3292,21 @@ export interface ForeignObject {
3292
3292
  * See {@link Archive} and {@link isArchived}.
3293
3293
  */
3294
3294
  archived?: Archive
3295
+ /**
3296
+ * When this file last changed, in seconds: the newest of its root's
3297
+ * `created_at` and every folded field's winning change (5ebf2756).
3298
+ *
3299
+ * For a card that lists some of a file's children rather than all of them —
3300
+ * a project's most recently changed issues. Its comments are not changes to
3301
+ * it. A regular event, which nothing changes by address, has its own
3302
+ * `created_at`. Absent on an unreachable stub, which has no root to read.
3303
+ */
3304
+ changedAt?: number
3305
+ }
3306
+
3307
+ /** The newest of a root's `created_at` and its folded fields' changes. */
3308
+ function changedAtOf(root: SignedEvent, folded: Record<string, { at?: number }>): number {
3309
+ return Math.max(root.created_at, ...Object.values(folded).map((f) => f.at ?? 0))
3295
3310
  }
3296
3311
 
3297
3312
 
@@ -3306,7 +3321,7 @@ function buildObject(args: {
3306
3321
  pointer: AddressPointer
3307
3322
  manifest: Manifest
3308
3323
  projection: Projection
3309
- folded: Record<string, { value: string; format?: ContentFormat }>
3324
+ folded: Record<string, { value: string; format?: ContentFormat; at?: number }>
3310
3325
  viaRecommendation: boolean
3311
3326
  webTemplate?: string
3312
3327
  comments?: ForeignObject['comments']
@@ -3315,28 +3330,6 @@ function buildObject(args: {
3315
3330
  const { root, pointer, manifest, projection, folded } = args
3316
3331
  const naddr = encodeNaddr(pointer)
3317
3332
  const { slots, meta } = resolveSlots(projection, root, folded, manifest)
3318
-
3319
- /**
3320
- * What each field holds now, however it got there.
3321
- *
3322
- * `resolveActions` reads the fold alone, which is right for a field that only
3323
- * ever exists as a change — but a project's lead is seeded by a tag on the
3324
- * root event. Without this, the assign control on a project nobody has
3325
- * reassigned reads "Assign to me" while a lead is plainly set, and the one
3326
- * control that is supposed to both report and set the field (PEEK-18) reports
3327
- * nothing.
3328
- */
3329
- const held: Record<string, string> = {}
3330
- // The built-in subtitle too, or a summary seeded at creation shows on the
3331
- // card while `summarize` offers a blank to edit (SPEC §6.12).
3332
- for (const spec of Object.values(withDefaultSubtitle(projection.slots, root.kind)).flat()) {
3333
- // `tag` may name several spellings (see `SlotSpec`); the field this slot
3334
- // *is* keyed on is the first, which is the one the app writes today. The
3335
- // rest are only there to keep older records rendering.
3336
- const field = spec.fold ?? (Array.isArray(spec.tag) ? spec.tag[0] : spec.tag)
3337
- const raw = field ? rawSlotValue(spec, root, folded, false)?.value : undefined
3338
- if (field && raw !== undefined) held[field] = raw
3339
- }
3340
3333
  const objectAddress = pointerToAddress(pointer)
3341
3334
  return {
3342
3335
  // An addressable object's `ref` is its address: stable across the author
@@ -3360,14 +3353,44 @@ function buildObject(args: {
3360
3353
  // Substituted here rather than in the component: `<bech32>` is a NIP-89
3361
3354
  // detail, and the widget's job is to draw a link, not to know the spec.
3362
3355
  openUrl: args.webTemplate?.replace('<bech32>', naddr),
3363
- actions: resolveActions(manifest, pointer.kind, folded).map((action) =>
3364
- action.current === undefined && action.field
3365
- ? { ...action, current: held[action.field] }
3366
- : action,
3367
- ),
3356
+ actions: actionsOfFile(manifest, projection, root, folded),
3368
3357
  viaRecommendation: args.viaRecommendation,
3369
3358
  ...(args.archived ? { archived: args.archived } : {}),
3359
+ changedAt: changedAtOf(root, folded),
3360
+ }
3361
+ }
3362
+
3363
+ /**
3364
+ * An addressable file's actions, each with what its field holds now, however
3365
+ * it got there.
3366
+ *
3367
+ * `resolveActions` reads the fold alone, which is right for a field that only
3368
+ * ever exists as a change — but a project's lead is seeded by a tag on the
3369
+ * root event. Without this, the assign control on a project nobody has
3370
+ * reassigned reads "Assign to me" while a lead is plainly set, and the one
3371
+ * control that is supposed to both report and set the field (PEEK-18) reports
3372
+ * nothing.
3373
+ */
3374
+ function actionsOfFile(
3375
+ manifest: Manifest,
3376
+ projection: Projection,
3377
+ root: SignedEvent,
3378
+ folded: Record<string, { value: string; format?: ContentFormat }>,
3379
+ ): ResolvedAction[] {
3380
+ const held: Record<string, string> = {}
3381
+ // The built-in subtitle too, or a summary seeded at creation shows on the
3382
+ // card while `summarize` offers a blank to edit (SPEC §6.12).
3383
+ for (const spec of Object.values(withDefaultSubtitle(projection.slots, root.kind)).flat()) {
3384
+ // `tag` may name several spellings (see `SlotSpec`); the field this slot
3385
+ // *is* keyed on is the first, which is the one the app writes today. The
3386
+ // rest are only there to keep older records rendering.
3387
+ const field = spec.fold ?? (Array.isArray(spec.tag) ? spec.tag[0] : spec.tag)
3388
+ const raw = field ? rawSlotValue(spec, root, folded, false)?.value : undefined
3389
+ if (field && raw !== undefined) held[field] = raw
3370
3390
  }
3391
+ return resolveActions(manifest, root.kind, folded).map((action) =>
3392
+ action.current === undefined && action.field ? { ...action, current: held[action.field] } : action,
3393
+ )
3371
3394
  }
3372
3395
 
3373
3396
  /**
@@ -3494,7 +3517,9 @@ export async function resolveForeignObject(
3494
3517
  : undefined,
3495
3518
  ])
3496
3519
  const followUp = childChangeFilters(plan, answered)
3497
- const assembled = assembleObject(plan, answered, followUp.length ? await queryChunked(followUp, query) : [])
3520
+ const childChanges = followUp.length ? await queryChunked(followUp, query) : []
3521
+ const childOwners = await childOwnersOf(plan, answered, childChanges, query, cache)
3522
+ const assembled = assembleObject(plan, answered, childChanges, childOwners)
3498
3523
  if (assembled.object.unreachable) return assembled.object
3499
3524
  if (options.archivedWith) await markArchivedParents([{ object: assembled.object, manifest: resolved.manifest }], query)
3500
3525
  return withFiles(
@@ -3630,11 +3655,12 @@ export async function resolveForeignObjects(
3630
3655
  followUp.push(...childChangeFilters(plan, events))
3631
3656
  }
3632
3657
  const childChanges = followUp.length ? await queryChunked(followUp, query) : []
3658
+ const ownerLists = await Promise.all(plans.map(({ plan }) => childOwnersOf(plan, events, childChanges, query, cache)))
3633
3659
 
3634
- const assembled = plans.map(({ reference, plan }) => ({
3660
+ const assembled = plans.map(({ reference, plan }, i) => ({
3635
3661
  reference,
3636
3662
  plan,
3637
- built: assembleObject(plan, events, childChanges),
3663
+ built: assembleObject(plan, events, childChanges, ownerLists[i]),
3638
3664
  }))
3639
3665
  if (options.archivedWith) {
3640
3666
  await markArchivedParents(assembled.map(({ plan, built }) => ({ object: built.object, manifest: plan.resolved.manifest })), query)
@@ -4173,7 +4199,12 @@ interface AssembledObject {
4173
4199
  * filters match — a comment naming two files in the set, a `kind:9` that is a
4174
4200
  * Topic's child and its comment — would otherwise be drawn twice.
4175
4201
  */
4176
- function assembleObject(plan: ObjectPlan, answered: SignedEvent[], childChanges: SignedEvent[] = []): AssembledObject {
4202
+ function assembleObject(
4203
+ plan: ObjectPlan,
4204
+ answered: SignedEvent[],
4205
+ childChanges: SignedEvent[] = [],
4206
+ childOwners: Set<string> = new Set(),
4207
+ ): AssembledObject {
4177
4208
  const { naddr, pointer, address, resolved, projection, commentKinds, childFilter, openUrl } = plan
4178
4209
  const { manifest, viaRecommendation } = resolved
4179
4210
  const seen = new Set<string>()
@@ -4265,6 +4296,7 @@ function assembleObject(plan: ObjectPlan, answered: SignedEvent[], childChanges:
4265
4296
  webTemplate: resolved.webTemplate,
4266
4297
  viaRecommendation,
4267
4298
  childChanges,
4299
+ childOwners,
4268
4300
  })
4269
4301
 
4270
4302
  return { object, ...(children ? { children } : {}) }
@@ -4529,8 +4561,10 @@ function childrenFrom(args: {
4529
4561
  viaRecommendation: boolean
4530
4562
  /** What {@link childChangeFilters} asked for; empty when it asked nothing. */
4531
4563
  childChanges?: SignedEvent[]
4564
+ /** What {@link childOwnersOf} answered: the authors whose children carry actions. */
4565
+ childOwners?: Set<string>
4532
4566
  }): ForeignObject[] | undefined {
4533
- const { events, childFilter, manifest, webTemplate, viaRecommendation, childChanges = [] } = args
4567
+ const { events, childFilter, manifest, webTemplate, viaRecommendation, childChanges = [], childOwners = new Set() } = args
4534
4568
  if (childFilter === undefined) return undefined
4535
4569
  if (childFilter === null) return []
4536
4570
 
@@ -4580,11 +4614,64 @@ function childrenFrom(args: {
4580
4614
  if (records.hiddenWhen && folded[records.hiddenWhen.field]?.value === records.hiddenWhen.equals) return []
4581
4615
  if (address && manifest.records && archiveOf(childChanges, address, records, event)) return []
4582
4616
  return [
4583
- buildChildObject({ root: event, manifest, projection: childProjection, records, webTemplate, viaRecommendation, folded }),
4617
+ buildChildObject({
4618
+ root: event,
4619
+ manifest,
4620
+ projection: childProjection,
4621
+ records,
4622
+ webTemplate,
4623
+ viaRecommendation,
4624
+ folded,
4625
+ ownsKind: childOwners.has(event.pubkey),
4626
+ }),
4584
4627
  ]
4585
4628
  })
4586
4629
  }
4587
4630
 
4631
+ /**
4632
+ * The authors of a card's children whose kind the card's own app owns — the
4633
+ * only children that carry actions (LTX-2).
4634
+ *
4635
+ * A child is drawn through its parent's manifest, and that need not be the
4636
+ * manifest its kind resolves to: an outside app may list Ship's issues under a
4637
+ * kind of its own and declare text actions on them that Ship keeps to itself.
4638
+ * Offered on the child, they would tell Leaf it may write a field Ship never
4639
+ * shared, with no `declaredBy` to say whose they are. So a child carries
4640
+ * actions only when its kind, resolved for its author as a file read on its
4641
+ * own is, lands on the parent's manifest. Per author, because an author's
4642
+ * recommendation is part of that answer, and through the cache, so a project's
4643
+ * issues by three people cost three lookups once. Nothing is asked when the
4644
+ * parent's app declares no action on the child's kind, and only for authors of
4645
+ * roots that came back: a move naming the parent is anyone's to write, and the
4646
+ * addresses it lists would otherwise cost a lookup each, root or not.
4647
+ */
4648
+ async function childOwnersOf(
4649
+ plan: ObjectPlan,
4650
+ answered: SignedEvent[],
4651
+ childChanges: SignedEvent[],
4652
+ query: QueryFn,
4653
+ cache?: ProjectionCache,
4654
+ ): Promise<Set<string>> {
4655
+ const { childFilter, resolved } = plan
4656
+ if (!childFilter || resolveActions(resolved.manifest, childFilter.kind, {}).length === 0) return new Set()
4657
+ const movedIn = new Set(movedInAddressesOf(answered, childFilter, resolved.manifest.records))
4658
+ const authors = new Set([
4659
+ ...childRootsOf(answered, childFilter).map((e) => e.pubkey),
4660
+ ...childChanges
4661
+ .filter((e) => e.kind === childFilter.kind && movedIn.has(childAddressOf(e) ?? ''))
4662
+ .map((e) => e.pubkey),
4663
+ ])
4664
+ const owners = await Promise.all(
4665
+ [...authors].map(async (pubkey) => {
4666
+ const owner = await resolveManifest({ kind: childFilter.kind, pubkey, identifier: '', relays: [] }, query, cache).catch(
4667
+ () => null,
4668
+ )
4669
+ return owner?.address === resolved.address ? [pubkey] : []
4670
+ }),
4671
+ )
4672
+ return new Set(owners.flat())
4673
+ }
4674
+
4588
4675
  /** The child roots a `list` filter asked for, picked back out of a pooled answer on its own criteria. */
4589
4676
  function childRootsOf(events: SignedEvent[], childFilter: NonNullable<ReturnType<typeof childFilterFor>>): SignedEvent[] {
4590
4677
  return events
@@ -4661,9 +4748,14 @@ const CHILD_CHANGE_GROUP = 10
4661
4748
  * event id. That is the whole of PRO-6's finding (6), and it is why `ref` and
4662
4749
  * `eventId` exist alongside `address`.
4663
4750
  *
4664
- * An object built this way carries **no actions**, and that is correct rather
4665
- * than a limitation: an action emits a change carrying an `a` tag naming what
4666
- * it changes, and a regular event cannot be named that way.
4751
+ * A regular event carries **no actions**, and that is correct rather than a
4752
+ * limitation: an action emits a change carrying an `a` tag naming what it
4753
+ * changes, and a regular event cannot be named that way. An addressable child —
4754
+ * a Ship issue read under its project — carries the actions its own app
4755
+ * declares for its kind, as it does when read on its own, so whether its app
4756
+ * shares its text is the same answer either way (LTX-2) — when the parent's app
4757
+ * is that app; listed by another, it carries none (`childOwnersOf`). Borrowed creations
4758
+ * (`declaredBy`) are added only on a file read on its own.
4667
4759
  */
4668
4760
  function buildChildObject(args: {
4669
4761
  root: SignedEvent
@@ -4685,9 +4777,14 @@ function buildChildObject(args: {
4685
4777
  * The child's own fold, when {@link childChangeFilters} read its changes
4686
4778
  * (MAN-7). Empty for a regular event, which nothing can change by address.
4687
4779
  */
4688
- folded?: Record<string, { value: string; format?: ContentFormat }>
4780
+ folded?: Record<string, { value: string; format?: ContentFormat; at?: number }>
4781
+ /**
4782
+ * Whether `manifest` is the one this child's kind resolves to for its author,
4783
+ * as {@link childOwnersOf} found. Its actions are offered only then.
4784
+ */
4785
+ ownsKind?: boolean
4689
4786
  }): ForeignObject {
4690
- const { root, manifest, projection, webTemplate, viaRecommendation, nevent, folded = {} } = args
4787
+ const { root, manifest, projection, webTemplate, viaRecommendation, nevent, folded = {}, ownsKind = false } = args
4691
4788
  const identifier = tagValue(root, 'd')
4692
4789
  const addressable = identifier !== undefined
4693
4790
  const pointer: AddressPointer = {
@@ -4733,9 +4830,12 @@ function buildChildObject(args: {
4733
4830
  single template serve both, and what stops a message linking to nothing.
4734
4831
  */
4735
4832
  openUrl: (naddr ?? nevent) ? webTemplate?.replace('<bech32>', (naddr ?? nevent) as string) : undefined,
4736
- // See the note above: nothing can be declared to act on a regular event.
4737
- actions: [],
4833
+ // See the note above: nothing can be declared to act on a regular event, and an event read by its id
4834
+ // (`nevent`) may be an older version of its file, its changes unread, so it is offered none either.
4835
+ // A child drawn through an app that does not own its kind gets none: they are not its owner's (`childOwnersOf`).
4836
+ actions: addressable && !nevent && ownsKind ? actionsOfFile(manifest, projection, root, folded) : [],
4738
4837
  viaRecommendation,
4838
+ changedAt: changedAtOf(root, folded),
4739
4839
  }
4740
4840
  }
4741
4841