@estiva-app/interop 0.54.0 → 0.55.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.54.0",
3
+ "version": "0.55.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
@@ -1390,7 +1390,14 @@ const BARE_FILE_MANIFEST: Manifest = {
1390
1390
  widget: 'card',
1391
1391
  slots: {
1392
1392
  title: { tag: 'title', fold: 'title' },
1393
- body: { field: 'content' },
1393
+ /*
1394
+ The text is the `description` fold, seeded from `content` (SPEC §6.7,
1395
+ Leaf 1): anyone in the Folder saves it with the `describe` action
1396
+ below, the author included — a republished root would lose silently
1397
+ to an older change. Ship's body slot is the same fold, minus the
1398
+ `tag`: a `30840` carries its text in `content`, never in a tag.
1399
+ */
1400
+ body: { fold: 'description', field: 'content' },
1394
1401
  // A bare file may hold bare files — a sub-topic under a topic. Children
1395
1402
  // of *other* kinds are found the other way round, by their own `a`
1396
1403
  // (`parentRefOf` below), which is FOL-4's generic direction; this slot
@@ -1425,8 +1432,8 @@ const BARE_FILE_MANIFEST: Manifest = {
1425
1432
  },
1426
1433
  },
1427
1434
  /*
1428
- Four actions, and the manifest is the only place a consumer learns of any
1429
- of them (FOL-33; `move` from FOL-4). A Peek page offering Rename and Delete on a bare file and
1435
+ The manifest is the only place a consumer learns of any of these actions
1436
+ (FOL-33; `move` from FOL-4, `describe` from Leaf 1). A Peek page offering Rename and Delete on a bare file and
1430
1437
  nothing on a Ship issue does so because *this* list says `rename` and
1431
1438
  `delete` and Ship's does not — never because the kind is 30840. The rule is
1432
1439
  the one FOL-31 set for `comment`: a control is drawn from a declaration.
@@ -1463,6 +1470,25 @@ const BARE_FILE_MANIFEST: Manifest = {
1463
1470
  emits: { kind: 1851, field: 'title' },
1464
1471
  input: { type: 'string' },
1465
1472
  },
1473
+ /*
1474
+ `describe` replaces the file's text with a whole §13.3 block document —
1475
+ a snapshot, last save wins (SPEC §6.7, decided 2026-10-13; live merging
1476
+ between open windows is a later layer). The shape of Ship's
1477
+ `describe-issue`, so a consumer that edits one edits both, and finds it
1478
+ by `emits.field` rather than by this id. Every save is a full copy, so a
1479
+ writer saves on leave, never per keystroke.
1480
+ */
1481
+ {
1482
+ id: 'describe',
1483
+ label: 'Edit',
1484
+ description:
1485
+ "Replace this file's text with new text. A change event, so anyone in the Folder may, and every app " +
1486
+ 'reading the file folds it over the text it was made with; the later save wins.',
1487
+ effect: 'writes',
1488
+ appliesTo: [String(KIND_BARE_FILE)],
1489
+ emits: { kind: 1851, field: 'description' },
1490
+ input: { type: 'string', format: BLOCK_DOCUMENT_FORMAT },
1491
+ },
1466
1492
  /*
1467
1493
  `move` is the `parent` field SPEC §6.7 already defines, declared so a
1468
1494
  consumer draws the control from here as it draws Rename (FOL-4). The value
@@ -2119,9 +2145,64 @@ import { contentFormatOf, type ContentFormat } from '@estiva-app/protocol'
2119
2145
  export const BODY_SLOT = 'body'
2120
2146
 
2121
2147
 
2122
- function foldChanges(changes: SignedEvent[], rule: RecordsRule) {
2148
+ /**
2149
+ * Does this change sit in the Folder its target is filed in — SPEC §6.2.
2150
+ *
2151
+ * The relay checks a change only against its own `h`: the signer must be a
2152
+ * member of *that* Folder. Nothing on the relay ties it to the target's Folder,
2153
+ * so before this a member of any Folder could rename, move, archive or rewrite
2154
+ * a file in a Folder they cannot read, and every reader who could see the
2155
+ * change folded it in. Probed on production 2026-10-13: QA-2's `description`
2156
+ * change to QA-1's page, signed with another Folder's `h`, was accepted. So
2157
+ * the reader ignores it, for every kind (Miky, 2026-10-13).
2158
+ *
2159
+ * The target's Folder is any placement its root carries — `h`, or Ship's
2160
+ * `buzz-channel` (§7.3), whichever the root has; about half of Ship's projects
2161
+ * carry one and half the other — or, for a `kind:39000`, the Folder itself.
2162
+ * A change's own Folder is read the same way. Measured before this shipped:
2163
+ * of 2,790 changes whose roots were readable, none would be dropped but two
2164
+ * duplicated project changes and four Folder archives `folderArchiveOf`
2165
+ * already ignored.
2166
+ *
2167
+ * A change's Folder is its `h` alone: that is the tag the relay checks the
2168
+ * signer's membership against, so a `buzz-channel` on a change proves nothing.
2169
+ *
2170
+ * Without the root there is nothing to compare, so every change counts: the
2171
+ * caller that has only an address (an archived parent read by address) is no
2172
+ * worse than before. Nor does a root that names no Folder (an early topic,
2173
+ * from when `h` was SHOULD) — it has no Folder to be outside of.
2174
+ *
2175
+ * Built once per root, and asked once per change.
2176
+ */
2177
+ function targetFolders(root: SignedEvent | undefined): ReadonlySet<string> | undefined {
2178
+ if (!root) return undefined
2179
+ const folders = new Set(PLACEMENTS.flatMap((name) => root.tags.filter((t) => t[0] === name && t[1]).map((t) => t[1]!)))
2180
+ if (root.kind === KIND_CHANNEL_METADATA) {
2181
+ const own = tagValue(root, 'd')
2182
+ if (own) folders.add(own)
2183
+ }
2184
+ return folders.size ? folders : undefined
2185
+ }
2186
+
2187
+ function inTargetFolder(change: SignedEvent, folders: ReadonlySet<string> | undefined): boolean {
2188
+ if (!folders) return true
2189
+ // The first `h` with a value, as the relay reads it: an empty `["h"]` ahead
2190
+ // of a real one must not make this read a different Folder from the one the
2191
+ // relay checked the signer against.
2192
+ const own = change.tags.find((t) => t[0] === 'h' && t[1])?.[1]
2193
+ return own !== undefined && folders.has(own)
2194
+ }
2195
+
2196
+ /**
2197
+ * Fold `changes` under `rule`, ignoring any not in `root`'s Folder
2198
+ * ({@link targetFolders}). `root` is required so every caller decides: pass
2199
+ * `undefined` only where the root genuinely is not at hand, and the newest
2200
+ * version where several are.
2201
+ */
2202
+ function foldChanges(changes: SignedEvent[], rule: RecordsRule, root: SignedEvent | undefined) {
2123
2203
  const fields: Record<string, { value: string; by: string; at: number; format: ContentFormat }> = {}
2124
- for (const change of [...changes].sort(byOrder)) {
2204
+ const folders = targetFolders(root)
2205
+ for (const change of [...changes].filter((c) => inTargetFolder(c, folders)).sort(byOrder)) {
2125
2206
  const field = tagValue(change, rule.fieldTag)
2126
2207
  const value = tagValue(change, rule.valueTag)
2127
2208
  if (!field || value === undefined) continue // a partial change sets nothing
@@ -2144,13 +2225,14 @@ function foldChanges(changes: SignedEvent[], rule: RecordsRule) {
2144
2225
  * the **first** target tag, as `archiveOf` reads it. Empty when the app declares
2145
2226
  * no change events — `foldRuleOf`'s substitute is never asked for.
2146
2227
  */
2147
- function foldOf(events: SignedEvent[], address: string, manifest: Manifest) {
2228
+ function foldOf(events: SignedEvent[], address: string, manifest: Manifest, root: SignedEvent | undefined) {
2148
2229
  const records = foldRuleOf(manifest)
2149
2230
  return foldChanges(
2150
2231
  manifest.records
2151
2232
  ? events.filter((e) => e.kind === records.changeKind && tagValue(e, records.targetTag) === address)
2152
2233
  : [],
2153
2234
  records,
2235
+ root,
2154
2236
  )
2155
2237
  }
2156
2238
 
@@ -2232,18 +2314,26 @@ function archiveOf(
2232
2314
  changes: SignedEvent[],
2233
2315
  address: string,
2234
2316
  rule: RecordsRule,
2317
+ /**
2318
+ * The target's newest root version (SPEC §6.2): an archive signed in another
2319
+ * Folder is ignored, as every fold ignores it. Required so every caller
2320
+ * decides; `undefined` only where only the address is held.
2321
+ */
2322
+ root: SignedEvent | undefined,
2235
2323
  folderAdmins?: ReadonlySet<string>,
2236
2324
  ): Archive | undefined {
2237
- const [kind, , folderId] = address.split(':')
2325
+ const [kind, , identifier] = address.split(':')
2238
2326
  if (Number(kind) === KIND_CHANNEL) {
2239
2327
  if (!folderAdmins?.size) return undefined
2240
- changes = changes.filter((change) => tagValue(change, 'h') === folderId && folderAdmins.has(change.pubkey))
2328
+ changes = changes.filter((change) => tagValue(change, 'h') === identifier && folderAdmins.has(change.pubkey))
2241
2329
  }
2330
+ const folders = targetFolders(root)
2242
2331
  let last: SignedEvent | undefined
2243
2332
  for (const change of changes) {
2244
2333
  // The target is the first target tag, as every other fold reads it: a
2245
2334
  // change archiving one file must not archive another it also mentions.
2246
2335
  if (change.kind !== rule.changeKind || tagValue(change, rule.targetTag) !== address) continue
2336
+ if (!inTargetFolder(change, folders)) continue
2247
2337
  if (tagValue(change, rule.fieldTag) !== ARCHIVED_FIELD || tagValue(change, rule.valueTag) === undefined) continue
2248
2338
  if (!last || byOrder(last, change) < 0) last = change
2249
2339
  }
@@ -3379,10 +3469,10 @@ export function projectEvents(
3379
3469
  pointer,
3380
3470
  manifest,
3381
3471
  projection: manifest.projections![String(root.kind)],
3382
- folded: foldOf(byTarget(foldRuleOf(manifest).targetTag).get(address) ?? [], address, manifest),
3472
+ folded: foldOf(byTarget(foldRuleOf(manifest).targetTag).get(address) ?? [], address, manifest, root),
3383
3473
  viaRecommendation: resolved.viaRecommendation,
3384
3474
  webTemplate: resolved.webTemplate,
3385
- archived: archiveOf(byTarget(archiveRule.targetTag).get(address) ?? [], address, archiveRule),
3475
+ archived: archiveOf(byTarget(archiveRule.targetTag).get(address) ?? [], address, archiveRule, root),
3386
3476
  })
3387
3477
  })
3388
3478
  }
@@ -3532,7 +3622,7 @@ export async function resolveParents(
3532
3622
  .sort(byOrder)
3533
3623
  .at(-1)
3534
3624
  if (!root) continue
3535
- const folded = foldOf(events, pointerToAddress(pointer), manifest)
3625
+ const folded = foldOf(events, pointerToAddress(pointer), manifest, root)
3536
3626
  results[reference] = parentRefOf(manifest, pointer.kind, root, folded) ?? null
3537
3627
  }
3538
3628
  return results
@@ -3579,7 +3669,8 @@ async function markArchivedParents(
3579
3669
  const parents = [...new Set(waiting.map(({ object }) => object.parentRef!))]
3580
3670
  const changes = await readArchiveChanges(parents, query, rules)
3581
3671
  for (const [index, { object }] of waiting.entries()) {
3582
- const archive = archiveOf(changes, object.parentRef!, rules[index]!)
3672
+ // Only the parent's address is held here, not its root (SPEC §6.2's exception).
3673
+ const archive = archiveOf(changes, object.parentRef!, rules[index]!, undefined)
3583
3674
  if (archive) object.archived = { ...archive, with: object.parentRef! }
3584
3675
  }
3585
3676
  }
@@ -3788,7 +3879,7 @@ function assembleObject(plan: ObjectPlan, answered: SignedEvent[], childChanges:
3788
3879
  }
3789
3880
  }
3790
3881
 
3791
- const folded = foldOf(events, address, manifest)
3882
+ const folded = foldOf(events, address, manifest, root)
3792
3883
 
3793
3884
  /*
3794
3885
  Matched on the comment filter's own criteria — the kind **and** the `a` tag.
@@ -3819,7 +3910,7 @@ function assembleObject(plan: ObjectPlan, answered: SignedEvent[], childChanges:
3819
3910
  viaRecommendation,
3820
3911
  webTemplate: resolved.webTemplate,
3821
3912
  comments,
3822
- archived: archiveOf(events, address, archiveRuleOf(manifest)),
3913
+ archived: archiveOf(events, address, archiveRuleOf(manifest), root),
3823
3914
  })
3824
3915
  /*
3825
3916
  The `list` slot — PRO-7.
@@ -4130,11 +4221,11 @@ function childrenFrom(args: {
4130
4221
  parent, so only a folded value that names it keeps it: the tag is how
4131
4222
  it was found, not proof that it is still here.
4132
4223
  */
4133
- const folded = address ? foldOf(childChanges, address, manifest) : {}
4224
+ const folded = address ? foldOf(childChanges, address, manifest, event) : {}
4134
4225
  if (movedBy && folded[movedBy] && folded[movedBy].value !== childFilter.parent) return []
4135
4226
  if (address && movedIn.has(address) && folded[movedBy!]?.value !== childFilter.parent) return []
4136
4227
  if (records.hiddenWhen && folded[records.hiddenWhen.field]?.value === records.hiddenWhen.equals) return []
4137
- if (address && manifest.records && archiveOf(childChanges, address, records)) return []
4228
+ if (address && manifest.records && archiveOf(childChanges, address, records, event)) return []
4138
4229
  return [
4139
4230
  buildChildObject({ root: event, manifest, projection: childProjection, records, webTemplate, viaRecommendation, folded }),
4140
4231
  ]
@@ -4722,7 +4813,7 @@ export async function resolveFolderProject(
4722
4813
  const applied = source.filter(
4723
4814
  (e) => e.kind === rule.changeKind && tagValue(e, rule.targetTag) === addressOfEvent(event),
4724
4815
  )
4725
- return foldChanges(applied, rule)[rule.hiddenWhen.field]?.value === rule.hiddenWhen.equals
4816
+ return foldChanges(applied, rule, event)[rule.hiddenWhen.field]?.value === rule.hiddenWhen.equals
4726
4817
  }
4727
4818
 
4728
4819
  const roots = known
@@ -4799,7 +4890,7 @@ export async function resolveFolderProject(
4799
4890
  pointer,
4800
4891
  manifest,
4801
4892
  projection,
4802
- folded: foldChanges(changesFor(address), records),
4893
+ folded: foldChanges(changesFor(address), records, root),
4803
4894
  viaRecommendation,
4804
4895
  webTemplate: resolved.webTemplate,
4805
4896
  })
@@ -4861,7 +4952,7 @@ export async function resolveFolderProject(
4861
4952
  relays: [],
4862
4953
  }
4863
4954
  const ticketChanges = changesFor(pointerToAddress(ticketPointer))
4864
- const folded = foldChanges(ticketChanges, records)
4955
+ const folded = foldChanges(ticketChanges, records, event)
4865
4956
  const status = statusSpec ? resolveSlot(statusSpec, event, folded, manifest) : null
4866
4957
  const raw = statusSpec ? rawSlotValue(statusSpec, event, folded, false)?.value : undefined
4867
4958
 
@@ -5507,7 +5598,8 @@ function folderAdminsOf(admins: SignedEvent | undefined, channel: SignedEvent |
5507
5598
  * change, and it means nothing.
5508
5599
  */
5509
5600
  function folderArchiveOf(changes: SignedEvent[], folder: Pick<FolderSummary, 'id' | 'channel' | 'admins'>): Archive | undefined {
5510
- return folder.channel ? archiveOf(changes, folder.channel, ARCHIVE_RULE, new Set(folder.admins ?? [])) : undefined
5601
+ // A Folder's own rule (h = the Folder, by its admins) stands in for the root check.
5602
+ return folder.channel ? archiveOf(changes, folder.channel, ARCHIVE_RULE, undefined, new Set(folder.admins ?? [])) : undefined
5511
5603
  }
5512
5604
 
5513
5605
  /** One folder, enough to draw a sidebar row. */
@@ -5702,12 +5794,12 @@ export async function listFolders(query: QueryFn): Promise<FolderSummary[]> {
5702
5794
  listedIn.set(identifier, containers)
5703
5795
  }
5704
5796
  }
5705
- const { recordsOf, archives } = await placeRecordChannels(events, byId, listedIn, query)
5797
+ const { recordsOf, archives, rootOf } = await placeRecordChannels(events, byId, listedIn, query)
5706
5798
  for (const [id, containers] of listedIn) {
5707
5799
  const folder = byId.get(id)
5708
5800
  if (folder) folder.listedIn = containers
5709
5801
  }
5710
- markArchivedFolders(byId, recordsOf, archives)
5802
+ markArchivedFolders(byId, recordsOf, archives, rootOf)
5711
5803
  return [...byId.values()].sort((a, b) => (a.name ?? a.id).localeCompare(b.name ?? b.id))
5712
5804
  }
5713
5805
 
@@ -5730,6 +5822,8 @@ function markArchivedFolders(
5730
5822
  byId: Map<string, FolderSummary>,
5731
5823
  recordsOf: Map<string, string[]>,
5732
5824
  changes: SignedEvent[],
5825
+ /** Each record's newest root, so an archive signed in another Folder is ignored (SPEC §6.2). */
5826
+ rootOf: ReadonlyMap<string, SignedEvent>,
5733
5827
  ): void {
5734
5828
  for (const folder of byId.values()) {
5735
5829
  const own = folderArchiveOf(changes, folder)
@@ -5738,7 +5832,7 @@ function markArchivedFolders(
5738
5832
  continue
5739
5833
  }
5740
5834
  const records = recordsOf.get(folder.id) ?? []
5741
- const archives = records.map((record) => archiveOf(changes, record, ARCHIVE_RULE))
5835
+ const archives = records.map((record) => archiveOf(changes, record, ARCHIVE_RULE, rootOf.get(record)))
5742
5836
  if (records.length && archives.every(Boolean)) folder.archived = { ...archives[0]!, with: records[0] }
5743
5837
  }
5744
5838
  }
@@ -5880,19 +5974,22 @@ async function countLiveChildren(
5880
5974
  for (let start = 0; start < filters.length; start += MAX_FILTERS_PER_QUERY) {
5881
5975
  events.push(...(await query(filters.slice(start, start + MAX_FILTERS_PER_QUERY))))
5882
5976
  }
5883
- const children = new Map<string, { kind: number; rule: RecordsRule }>()
5977
+ const children = new Map<string, { kind: number; rule: RecordsRule; root: SignedEvent }>()
5884
5978
  for (const event of events) {
5885
5979
  const identifier = tagValue(event, 'd')
5886
5980
  if (identifier === undefined) continue
5887
5981
  const match = wanted.find((w) => w.kind === event.kind && hasTagValue(event, w.via, w.parent))
5888
5982
  if (!match) continue
5889
5983
  const child = pointerToAddress({ kind: event.kind, pubkey: event.pubkey, identifier, relays: [] })
5890
- if (!counted.has(child)) children.set(child, { kind: event.kind, rule: match.rule })
5984
+ if (counted.has(child)) continue
5985
+ // The newest version is the root an archive is checked against (SPEC §6.2).
5986
+ const held = children.get(child)
5987
+ if (!held || event.created_at > held.root.created_at) children.set(child, { kind: event.kind, rule: match.rule, root: event })
5891
5988
  }
5892
5989
  if (children.size === 0) return byKind
5893
5990
  const changes = await readArchiveChanges([...children.keys()], query, [...children.values()].map((c) => c.rule))
5894
- for (const [child, { kind, rule }] of children) {
5895
- if (archiveOf(changes, child, rule)) continue
5991
+ for (const [child, { kind, rule, root }] of children) {
5992
+ if (archiveOf(changes, child, rule, root)) continue
5896
5993
  byKind.set(kind, (byKind.get(kind) ?? 0) + 1)
5897
5994
  }
5898
5995
  return byKind
@@ -5946,7 +6043,7 @@ async function placeRecordChannels(
5946
6043
  byId: Map<string, FolderSummary>,
5947
6044
  listedIn: Map<string, string[]>,
5948
6045
  query: QueryFn,
5949
- ): Promise<{ recordsOf: Map<string, string[]>; archives: SignedEvent[] }> {
6046
+ ): Promise<{ recordsOf: Map<string, string[]>; archives: SignedEvent[]; rootOf: Map<string, SignedEvent> }> {
5950
6047
  const containersOf = new Map<string, { pointer: AddressPointer; containers: string[] }>()
5951
6048
  for (const event of events) {
5952
6049
  if (event.kind !== KIND_FOLDER_STATE) continue
@@ -5977,7 +6074,7 @@ async function placeRecordChannels(
5977
6074
  for (let start = 0; start < archiveAsk.length; start += MAX_FILTERS_PER_QUERY) {
5978
6075
  archives.push(...(await query(archiveAsk.slice(start, start + MAX_FILTERS_PER_QUERY))))
5979
6076
  }
5980
- return { recordsOf: new Map(), archives }
6077
+ return { recordsOf: new Map(), archives, rootOf: new Map() }
5981
6078
  }
5982
6079
 
5983
6080
  const groups = new Map<string, { kind: number; pubkey: string; identifiers: string[] }>()
@@ -6025,7 +6122,7 @@ async function placeRecordChannels(
6025
6122
  listedIn.set(channel, placed)
6026
6123
  }
6027
6124
  }
6028
- return { recordsOf, archives }
6125
+ return { recordsOf, archives, rootOf: newest }
6029
6126
  }
6030
6127
 
6031
6128
  /**
@@ -6223,6 +6320,7 @@ export async function resolveFolderContents(
6223
6320
  const folded = foldChanges(
6224
6321
  events.filter((e) => e.kind === records.changeKind && hasTagValue(e, records.targetTag, address)),
6225
6322
  records,
6323
+ root,
6226
6324
  )
6227
6325
  const nestedAdmins =
6228
6326
  pointer.kind === KIND_CHANNEL
@@ -6233,7 +6331,7 @@ export async function resolveFolderContents(
6233
6331
  ),
6234
6332
  )
6235
6333
  : undefined
6236
- const archive = archiveOf(events, address, archiveRuleOf(resolved.manifest), nestedAdmins)
6334
+ const archive = archiveOf(events, address, archiveRuleOf(resolved.manifest), root, nestedAdmins)
6237
6335
  archiveByAddress.set(address, archive)
6238
6336
  const parent = parentRefOf(resolved.manifest, pointer.kind, root, folded)
6239
6337
  parentByAddress.set(address, parent)
@@ -6309,7 +6407,8 @@ export async function resolveFolderContents(
6309
6407
  if (outside.length) {
6310
6408
  const ruleFor = (parent: string) => parentRuleOf.get(parent) ?? ARCHIVE_RULE
6311
6409
  const changes = await readArchiveChanges(outside, query, outside.map(ruleFor))
6312
- for (const parent of outside) archiveByAddress.set(parent, archiveOf(changes, parent, ruleFor(parent)))
6410
+ // A parent in another Folder is held by address only (SPEC §6.2's exception).
6411
+ for (const parent of outside) archiveByAddress.set(parent, archiveOf(changes, parent, ruleFor(parent), undefined))
6313
6412
  }
6314
6413
  const files: ForeignObject[] = []
6315
6414
  for (const { file, archive } of listed) {