@estiva-app/interop 0.56.0 → 0.58.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.
@@ -133,6 +133,15 @@ const KIND_HANDLER_INFORMATION = 31990;
133
133
  * finding comments the moment an app said something different.
134
134
  */
135
135
  const KIND_COMMENT = 1111;
136
+ /**
137
+ * NIP-29's chat message, the one a Folder's conversation is made of — SPEC §7.8.
138
+ *
139
+ * Owned by no app, like a comment: the specification says how it draws and
140
+ * where it opens, so no manifest's `k` tag is asked about it.
141
+ *
142
+ * why: https://github.com/estiva-app/estiva-docs/blob/main/decisions/a-chat-message-belongs-to-the-protocol.md
143
+ */
144
+ export const KIND_MESSAGE = 9;
136
145
  /**
137
146
  * NIP-09's deletion request. Protocol, like the two above, and the one kind an
138
147
  * action may emit that is neither a change nor a comment nor a creation: an
@@ -839,6 +848,18 @@ export const MOVED_TO_TAG = 'A';
839
848
  * not only the author.
840
849
  */
841
850
  export const ARCHIVED_FIELD = 'archived';
851
+ /**
852
+ * The field, and the root tag seeding it, that holds a file's one-line summary,
853
+ * whatever its kind — SPEC §6.12.
854
+ *
855
+ * Plain text, one or two sentences, beside the title: what a card, a row or a
856
+ * picker shows under it. Changed by a `kind:1851` like the title, last write
857
+ * wins, and a value that is blank after trimming means no summary. Every file
858
+ * kind's `subtitle` reads it ({@link defaultSubtitle}), so no manifest has to.
859
+ *
860
+ * why: https://github.com/estiva-app/estiva-docs/blob/main/decisions/a-files-summary-is-its-own-field.md
861
+ */
862
+ export const SUMMARY_FIELD = 'summary';
842
863
  /**
843
864
  * Where a `ResolvedManifest.address` would name the manifest event, this names
844
865
  * the section of the specification the manifest is built from. Not an address,
@@ -903,6 +924,22 @@ const BARE_FILE_MANIFEST = {
903
924
  body: { field: 'content' },
904
925
  },
905
926
  },
927
+ /*
928
+ A chat message, for the comment's reason: no app owns `kind:9` (SPEC
929
+ §7.8). Peek's manifest claimed it until this release, and drew it exactly
930
+ so — the author as the title, because the text carries structure and is
931
+ no title; the text as the body, untruncated.
932
+
933
+ why: https://github.com/estiva-app/estiva-docs/blob/main/decisions/a-chat-message-belongs-to-the-protocol.md
934
+ */
935
+ [String(KIND_MESSAGE)]: {
936
+ widget: ['message', 'card'],
937
+ noun: 'message',
938
+ slots: {
939
+ title: { field: 'pubkey', as: 'pubkey' },
940
+ body: { field: 'content' },
941
+ },
942
+ },
906
943
  },
907
944
  /*
908
945
  The manifest is the only place a consumer learns of any of these actions
@@ -959,6 +996,22 @@ const BARE_FILE_MANIFEST = {
959
996
  emits: { kind: 1851, field: 'description' },
960
997
  input: { type: 'string', format: BLOCK_DOCUMENT_FORMAT },
961
998
  },
999
+ /*
1000
+ `summarize` sets the file's one-line summary (SPEC §6.12): plain text, so
1001
+ its input declares no `format` (§7.3), and a consumer finds it by
1002
+ `emits.field`, not by this id. An empty value clears it, the summary the
1003
+ file was created with included.
1004
+ */
1005
+ {
1006
+ id: 'summarize',
1007
+ label: 'Summary',
1008
+ description: "Set this file's summary: one or two sentences of plain text, about 240 characters, shown under its " +
1009
+ 'title wherever it is met in one line. A change event, so anyone in the Folder may; an empty value clears it.',
1010
+ effect: 'writes',
1011
+ appliesTo: [String(KIND_BARE_FILE)],
1012
+ emits: { kind: 1851, field: SUMMARY_FIELD },
1013
+ input: { type: 'string' },
1014
+ },
962
1015
  /*
963
1016
  `move` is the `parent` field SPEC §6.7 already defines, declared so a
964
1017
  consumer draws the control from here as it draws Rename (FOL-4). The value
@@ -1023,6 +1076,8 @@ function bareFileManifest() {
1023
1076
  * What a Folder's built-in actions are declared by — SPEC §3.2, as
1024
1077
  * {@link BARE_FILE_MANIFEST_ADDRESS} is for the bare file. The
1025
1078
  * `declaredBy.address` of an action no app declared.
1079
+ *
1080
+ * why: https://github.com/estiva-app/estiva-docs/blob/main/decisions/folders-belong-to-the-protocol.md
1026
1081
  */
1027
1082
  export const FOLDER_ACTIONS_ADDRESS = 'spec:3.2';
1028
1083
  /**
@@ -1043,28 +1098,115 @@ export const FOLDER_ACTIONS_ADDRESS = 'spec:3.2';
1043
1098
  * is the bare file's own, so the created object is drawn the way every other
1044
1099
  * bare file is. Each consumer offers it only if it may sign `30840` and `1852`
1045
1100
  * (§3.3).
1101
+ *
1102
+ * Starting a conversation is the second, moved here from Peek's manifest: a
1103
+ * `kind:9` carrying the Folder in `h` and nothing else — never an `a` naming
1104
+ * the `39000`, which §3.2 reads as a mention. A consumer offers it only on a
1105
+ * Folder whose relay-signed `30890` it has read, since a group without one is
1106
+ * a DM or a channel, and only if it may sign `kind:9`.
1046
1107
  */
1047
1108
  const FOLDER_CREATOR = {
1048
1109
  manifest: {
1049
1110
  name: 'Folder',
1050
1111
  about: 'What every app may do in a Folder, whichever app made it.',
1051
- projections: { [String(KIND_BARE_FILE)]: BARE_FILE_MANIFEST.projections[String(KIND_BARE_FILE)] },
1112
+ projections: {
1113
+ [String(KIND_BARE_FILE)]: BARE_FILE_MANIFEST.projections[String(KIND_BARE_FILE)],
1114
+ [String(KIND_MESSAGE)]: BARE_FILE_MANIFEST.projections[String(KIND_MESSAGE)],
1115
+ },
1052
1116
  actions: [
1053
1117
  {
1054
1118
  id: 'create-file',
1055
1119
  label: 'New file',
1056
- description: 'Put a new file in this Folder: a title, and nothing else yet. Everyone who can read the Folder can read ' +
1120
+ description: 'Put a new file in this Folder: a title and, if you have one, a short summary. Everyone who can read the Folder can read ' +
1057
1121
  'it, and the Folder lists it straight away. The app opening files calls it by its own word — Peek says topic.',
1058
1122
  effect: 'writes',
1059
1123
  appliesTo: String(KIND_CHANNEL_METADATA),
1060
1124
  emits: { kind: KIND_BARE_FILE, listed: true },
1061
- input: { type: 'object', properties: { title: { type: 'string' } }, required: ['title'] },
1125
+ // `summary` is the root tag that seeds the new file's summary (SPEC
1126
+ // §3.2, §6.12); left empty, it is omitted (§7.3).
1127
+ input: {
1128
+ type: 'object',
1129
+ properties: { title: { type: 'string' }, [SUMMARY_FIELD]: { type: 'string' } },
1130
+ required: ['title'],
1131
+ },
1132
+ },
1133
+ /*
1134
+ `toAddressOf: 'self'` and no `setTag`: the message hangs under the
1135
+ Folder it was started in, and names it only with the `h` every created
1136
+ event gets. One property, the body, written to `content` — a `kind:9`
1137
+ has an author and a text and nothing else.
1138
+ */
1139
+ {
1140
+ id: 'start-a-conversation',
1141
+ label: 'Start a conversation',
1142
+ description: 'Start a new conversation in this Folder, as a root message that people can then reply to. ' +
1143
+ 'Use when something is worth its own thread rather than an answer inside an existing one — ' +
1144
+ 'this cannot reply to a message. Everyone who can read the Folder reads it.',
1145
+ effect: 'writes',
1146
+ appliesTo: String(KIND_CHANNEL_METADATA),
1147
+ emits: { kind: KIND_MESSAGE, toAddressOf: 'self' },
1148
+ input: {
1149
+ type: 'object',
1150
+ properties: { message: { type: 'string', target: 'content' } },
1151
+ required: ['message'],
1152
+ },
1062
1153
  },
1063
1154
  ],
1064
1155
  },
1065
1156
  address: FOLDER_ACTIONS_ADDRESS,
1066
1157
  viaRecommendation: false,
1067
1158
  };
1159
+ /**
1160
+ * How a Folder draws — SPEC §3.2, answered here before NIP-89 is asked, as the
1161
+ * bare file's is.
1162
+ *
1163
+ * No app owns a Folder, so no `kind:31990` may claim `39000`; until this
1164
+ * release Peek's did, and every app learned a Folder's name from it. The title
1165
+ * is the channel record's `name`, the subtitle its `about` (the built-in
1166
+ * subtitle, {@link defaultSubtitle}), and the noun "folder".
1167
+ *
1168
+ * **No `list` slot.** What a Folder holds is what its relay-signed `30890`
1169
+ * names, which no `children` declaration can say, and it is read by
1170
+ * {@link resolveFolderContents} — only the files this viewer resolves, never a
1171
+ * count of the rest. A card asks for them as its `children` with
1172
+ * {@link ArchiveReadOptions.folderFiles}; a chip does not, and pays nothing.
1173
+ * Peek's claim listed fifty chat messages instead, and every Folder chip paid
1174
+ * for them. A Folder is never inside another (SPEC §3.1), so no listing needs a
1175
+ * Folder's children drawn under its row.
1176
+ *
1177
+ * No actions of its own either: every app's way into a Folder is
1178
+ * {@link FOLDER_CREATOR}'s, offered beside the others with `declaredBy`
1179
+ * naming this section, so a consumer tells them apart as it always has.
1180
+ *
1181
+ * why: https://github.com/estiva-app/estiva-docs/blob/main/decisions/folders-belong-to-the-protocol.md
1182
+ */
1183
+ const FOLDER_MANIFEST = {
1184
+ name: 'Folder',
1185
+ about: 'A Folder no app owns: its name, its one-liner, and the files its state lists.',
1186
+ projections: {
1187
+ [String(KIND_CHANNEL_METADATA)]: {
1188
+ widget: 'card',
1189
+ noun: 'folder',
1190
+ // The cut Peek's claim made, so no card grows when the claim goes.
1191
+ slots: { title: { tag: 'name' }, subtitle: { tag: 'about', truncate: 120 } },
1192
+ },
1193
+ },
1194
+ };
1195
+ /**
1196
+ * The Folder's manifest, named by the app that opens it — the bare file's rule
1197
+ * ({@link bareFileOpenedBy}): its link goes to the app declaring the
1198
+ * conversation aspect, by its `naddr` template, so "Open in Peek" says where.
1199
+ * With no such app the Folder still draws, with nowhere to open.
1200
+ */
1201
+ function folderManifest(opener) {
1202
+ const name = opener?.webTemplate ? wordOf(opener.manifest.name) : undefined;
1203
+ return {
1204
+ manifest: name ? { ...FOLDER_MANIFEST, name } : FOLDER_MANIFEST,
1205
+ address: FOLDER_ACTIONS_ADDRESS,
1206
+ viaRecommendation: false,
1207
+ ...(opener?.webTemplate ? { webTemplate: opener.webTemplate } : {}),
1208
+ };
1209
+ }
1068
1210
  /**
1069
1211
  * The built-in manifest, named by the app that opens it — PRO-24.
1070
1212
  *
@@ -1073,6 +1215,8 @@ const FOLDER_CREATOR = {
1073
1215
  * runtime's, so a published manifest still cannot change how a bare file
1074
1216
  * behaves; it can only say what it is called where it opens. A comment takes
1075
1217
  * the name (it opens in the same app) and not the noun, which is the file's.
1218
+ *
1219
+ * why: https://github.com/estiva-app/estiva-docs/blob/main/decisions/a-file-is-labelled-by-its-type-not-its-app.md
1076
1220
  */
1077
1221
  function bareFileOpenedBy(opener, template) {
1078
1222
  const name = wordOf(opener.name) ?? BARE_FILE_MANIFEST.name;
@@ -1265,10 +1409,19 @@ export async function resolveManifest(pointer, query, cache) {
1265
1409
  // A comment resolves through the built-in manifest as a bare file does, and
1266
1410
  // opens in the same app — the one that renders every file's conversation
1267
1411
  // is the one that can show a thread in it (FOL-38).
1268
- if (pointer.kind === KIND_BARE_FILE || pointer.kind === KIND_COMMENT) {
1269
- const opener = await resolveAspectApp('conversation', query, cache, pointer.kind === KIND_COMMENT ? 'nevent' : 'naddr');
1412
+ // A chat message is the comment's case exactly (SPEC §7.8), and a Folder has
1413
+ // its own built-in that opens in the same app (§3.2): neither is asked of a
1414
+ // `k` tag, so a manifest still claiming one is not read for it.
1415
+ if (pointer.kind === KIND_BARE_FILE || pointer.kind === KIND_COMMENT || pointer.kind === KIND_MESSAGE) {
1416
+ const opener = await resolveAspectApp('conversation', query, cache, pointer.kind === KIND_BARE_FILE ? 'naddr' : 'nevent');
1270
1417
  return opener?.webTemplate ? bareFileOpenedBy(opener.manifest, opener.webTemplate) : bareFileManifest();
1271
1418
  }
1419
+ // A refused sweep costs a Folder its link, never its name: Peek's `#k` claim
1420
+ // was a read of its own, and the Folder still drew when the sweep failed.
1421
+ // Not remembered (`throughCache` keeps no failure), so the next resolve asks.
1422
+ if (pointer.kind === KIND_CHANNEL_METADATA) {
1423
+ return folderManifest(await resolveAspectApp('conversation', query, cache, 'naddr').catch(() => null));
1424
+ }
1272
1425
  return throughCache(cache, `${pointer.kind}:${pointer.pubkey}`, () => resolveManifestUncached(pointer, query));
1273
1426
  }
1274
1427
  async function resolveManifestUncached(pointer, query) {
@@ -1398,6 +1551,8 @@ function creatorsOrNone(kind, query, cache) {
1398
1551
  * ({@link FOLDER_CREATOR}, INT-12): no app owns a Folder (SPEC §3.2), so no
1399
1552
  * app's claim to create the same kind there outranks the specification's —
1400
1553
  * a manifest declaring a bare file on a Folder is the second row, not this.
1554
+ * The Folder's owner is the specification's too ({@link FOLDER_MANIFEST}), and
1555
+ * declares no actions, so these are offered once.
1401
1556
  */
1402
1557
  function borrowedFrom(kind, owner, creators) {
1403
1558
  const builtIn = kind === KIND_CHANNEL_METADATA ? [FOLDER_CREATOR] : [];
@@ -1434,12 +1589,14 @@ function borrowedActions(kind, owner, creators) {
1434
1589
  * creation there. The manifest returned holds only those creations.
1435
1590
  */
1436
1591
  export async function resolveActingManifest(pointer, declaredBy, query, cache) {
1592
+ // A Folder's built-in needs no sweep, so a refused one must not cost it
1593
+ // (INT-12). Asked before the owner, whose address is the same section and
1594
+ // whose manifest only draws: every Folder action is the creator's.
1595
+ if (pointer.kind === KIND_CHANNEL_METADATA && declaredBy === FOLDER_ACTIONS_ADDRESS)
1596
+ return FOLDER_CREATOR;
1437
1597
  const owner = await resolveManifest(pointer, query, cache);
1438
1598
  if (!owner || !declaredBy || declaredBy === owner.address)
1439
1599
  return owner;
1440
- // A Folder's built-in needs no sweep, so a refused one must not cost it (INT-12).
1441
- if (pointer.kind === KIND_CHANNEL_METADATA && declaredBy === FOLDER_ACTIONS_ADDRESS)
1442
- return FOLDER_CREATOR;
1443
1600
  const creators = await creatorsOn(pointer.kind, query, cache);
1444
1601
  return borrowedFrom(pointer.kind, owner, creators).find((creator) => creator.address === declaredBy) ?? null;
1445
1602
  }
@@ -1518,6 +1675,8 @@ import { contentFormatOf } from '@estiva-app/protocol';
1518
1675
  * and a consumer reads `slots.body` to find it.
1519
1676
  */
1520
1677
  export const BODY_SLOT = 'body';
1678
+ /** The slot that is a file's summary, one line of plain text (SPEC §7.2). */
1679
+ const SUBTITLE_SLOT = 'subtitle';
1521
1680
  /**
1522
1681
  * Does this change sit in the Folder its target is filed in — SPEC §6.2.
1523
1682
  *
@@ -1581,6 +1740,10 @@ function foldChanges(changes, rule, root) {
1581
1740
  const value = tagValue(change, rule.valueTag);
1582
1741
  if (!field || value === undefined)
1583
1742
  continue; // a partial change sets nothing
1743
+ // A summary is new, so it takes neither of §6.2's exceptions: a change the
1744
+ // reader cannot check against the root's Folder is not read (SPEC §6.12).
1745
+ if (field === SUMMARY_FIELD && !folders)
1746
+ continue;
1584
1747
  // The format travels with the *winning* change, not with the object. SPEC
1585
1748
  // §13.4: "an app MUST read the tag from the event it took the value from,
1586
1749
  // never from the object's root" — a description created as marker text and
@@ -2007,7 +2170,20 @@ function resolveSlot(spec, root, folded, manifest, name) {
2007
2170
  const source = rawSlotValue(spec, root, folded, name === BODY_SLOT);
2008
2171
  if (source === undefined || source.value === '')
2009
2172
  return null;
2010
- const raw = source.value;
2173
+ let raw = source.value;
2174
+ /*
2175
+ `subtitle` is plain text on one line (SPEC §7.2, §6.12): line breaks fold to
2176
+ spaces, and a value that is blank once trimmed is no subtitle — a summary
2177
+ cleared with " " reads as cleared, and the seed does not show through it.
2178
+ Left to each consumer, `slots.subtitle &&` drew a blank one as an empty line
2179
+ (Peek's ForeignObjectWidget). A body-shaped value declared into the slot is
2180
+ left alone; the truncation guard below is what speaks to that.
2181
+ */
2182
+ if (name === SUBTITLE_SLOT && source.format !== 'blocks' && source.format !== 'unknown') {
2183
+ raw = raw.replace(/\s+/g, ' ').trim();
2184
+ if (raw === '')
2185
+ return null;
2186
+ }
2011
2187
  /*
2012
2188
  PRO-8's rule, now enforceable rather than only written down.
2013
2189
 
@@ -2045,6 +2221,65 @@ function resolveSlot(spec, root, folded, manifest, name) {
2045
2221
  ...(source.format ? { format: source.format } : {}),
2046
2222
  };
2047
2223
  }
2224
+ /*
2225
+ `truncate` is the clamp SPEC §6.12 makes a reader's job: the relay does not
2226
+ hold a writer to about 240 characters, and with no manifest declaring the
2227
+ slot nothing else would cut a 1,000-character summary down to a line. A
2228
+ consumer still clamps it to its own room; this is the backstop.
2229
+ */
2230
+ const SUMMARY_TRUNCATE = 280;
2231
+ const SUMMARY_SUBTITLE = { tag: SUMMARY_FIELD, fold: SUMMARY_FIELD, truncate: SUMMARY_TRUNCATE };
2232
+ const FOLDER_SUBTITLE = { tag: 'about' };
2233
+ /**
2234
+ * Where a kind's `subtitle` comes from whatever its manifest says, or
2235
+ * `undefined` where the manifest decides — SPEC §7.2, §6.12, §3.2.
2236
+ *
2237
+ * - **A Folder** (`kind:39000`): the `about` of its channel record, NIP-29's
2238
+ * one-liner. A `summary` change aimed at one is not read.
2239
+ * - **Every other addressable kind is a file**, and its subtitle is its
2240
+ * summary: the `summary` fold over the root tag of that name. Built in, so an
2241
+ * app's files — an outside company's included — show their summary on every
2242
+ * card with nothing in its manifest, and no manifest can point the line at
2243
+ * another field (Miky, 2026-10-15, kickoff).
2244
+ * - NIP-29's other `39001`–`39009` records, and regular events (a message, a
2245
+ * comment), keep what their manifest declares.
2246
+ */
2247
+ function defaultSubtitle(kind) {
2248
+ if (kind === KIND_CHANNEL_METADATA)
2249
+ return FOLDER_SUBTITLE;
2250
+ if (kind >= 39000 && kind <= 39009)
2251
+ return undefined;
2252
+ return isAddressableKind(kind) ? SUMMARY_SUBTITLE : undefined;
2253
+ }
2254
+ /**
2255
+ * A projection's slots with `subtitle` taken from {@link defaultSubtitle}.
2256
+ *
2257
+ * A declaration naming the same source keeps its `label` and a `truncate`
2258
+ * tighter than the built-in one (Peek's Folder projection truncates `about` at
2259
+ * 120); one naming any other source, or an array, is replaced.
2260
+ */
2261
+ function withDefaultSubtitle(slots, kind) {
2262
+ const builtIn = defaultSubtitle(kind);
2263
+ if (!builtIn)
2264
+ return slots;
2265
+ const declared = slots[SUBTITLE_SLOT];
2266
+ const same = declared !== undefined &&
2267
+ !Array.isArray(declared) &&
2268
+ declared.tag === builtIn.tag &&
2269
+ declared.fold === builtIn.fold &&
2270
+ declared.field === undefined &&
2271
+ declared.default === undefined &&
2272
+ declared.map === undefined &&
2273
+ declared.as === undefined &&
2274
+ declared.children === undefined;
2275
+ if (!same)
2276
+ return { ...slots, [SUBTITLE_SLOT]: builtIn };
2277
+ // Same source: its `label` and a tighter `truncate` stand, never a looser one.
2278
+ const truncate = declared.truncate === undefined || builtIn.truncate === undefined
2279
+ ? (declared.truncate ?? builtIn.truncate)
2280
+ : Math.min(declared.truncate, builtIn.truncate);
2281
+ return { ...slots, [SUBTITLE_SLOT]: { ...builtIn, label: declared.label, truncate } };
2282
+ }
2048
2283
  /**
2049
2284
  * Every slot a projection declares, resolved.
2050
2285
  *
@@ -2055,7 +2290,7 @@ function resolveSlot(spec, root, folded, manifest, name) {
2055
2290
  function resolveSlots(projection, root, folded, manifest) {
2056
2291
  const slots = {};
2057
2292
  const meta = [];
2058
- for (const [name, spec] of Object.entries(projection.slots)) {
2293
+ for (const [name, spec] of Object.entries(withDefaultSubtitle(projection.slots, root.kind))) {
2059
2294
  if (Array.isArray(spec)) {
2060
2295
  for (const one of spec) {
2061
2296
  // An array spec collects into `meta`, so the name it was declared under
@@ -2094,7 +2329,9 @@ function buildObject(args) {
2094
2329
  * nothing.
2095
2330
  */
2096
2331
  const held = {};
2097
- for (const spec of Object.values(projection.slots).flat()) {
2332
+ // The built-in subtitle too, or a summary seeded at creation shows on the
2333
+ // card while `summarize` offers a blank to edit (SPEC §6.12).
2334
+ for (const spec of Object.values(withDefaultSubtitle(projection.slots, root.kind)).flat()) {
2098
2335
  // `tag` may name several spellings (see `SlotSpec`); the field this slot
2099
2336
  // *is* keyed on is the first, which is the one the app writes today. The
2100
2337
  // rest are only there to keep older records rendering.
@@ -2235,14 +2472,21 @@ cache, options = {}) {
2235
2472
  return null;
2236
2473
  // Beside the object's own read, not after it: the sweep is cached, and cold
2237
2474
  // it would otherwise add a round trip to every resolve that pays for it.
2238
- const [answered, creators] = await Promise.all([query(plan.filters), creatorsOrNone(pointer.kind, query, cache)]);
2475
+ // A Folder card's files too, for the same reason.
2476
+ const [answered, creators, files] = await Promise.all([
2477
+ query(plan.filters),
2478
+ creatorsOrNone(pointer.kind, query, cache),
2479
+ options.folderFiles && pointer.kind === KIND_CHANNEL_METADATA
2480
+ ? folderFilesOf(pointer.identifier, query, lookupPeople, cache)
2481
+ : undefined,
2482
+ ]);
2239
2483
  const followUp = childChangeFilters(plan, answered);
2240
2484
  const assembled = assembleObject(plan, answered, followUp.length ? await queryChunked(followUp, query) : []);
2241
2485
  if (assembled.object.unreachable)
2242
2486
  return assembled.object;
2243
2487
  if (options.archivedWith)
2244
2488
  await markArchivedParents([{ object: assembled.object, manifest: resolved.manifest }], query);
2245
- return withBorrowed(withPeople(assembled, await (lookupPeople ?? peopleViaRelay(query))(peopleOf(assembled))), borrowedActions(pointer.kind, resolved, creators));
2489
+ return withFiles(withBorrowed(withPeople(assembled, await (lookupPeople ?? peopleViaRelay(query))(peopleOf(assembled))), borrowedActions(pointer.kind, resolved, creators)), files);
2246
2490
  }
2247
2491
  /**
2248
2492
  * The object's own actions, then the ones other apps declare on it (MAN-8).
@@ -2338,11 +2582,19 @@ cache, options = {}) {
2338
2582
  // Who else creates on each kind in the set (MAN-8): one sweep per kind, not
2339
2583
  // per object, read beside the objects themselves.
2340
2584
  const kinds = [...new Set(plans.map(({ plan }) => plan.pointer.kind))];
2341
- const [events, creatorLists] = await Promise.all([
2585
+ // And each Folder card's files, once per Folder however it is spelled.
2586
+ const folders = options.folderFiles
2587
+ ? [
2588
+ ...new Set(plans.filter(({ plan }) => plan.pointer.kind === KIND_CHANNEL_METADATA).map(({ plan }) => plan.pointer.identifier)),
2589
+ ]
2590
+ : [];
2591
+ const [events, creatorLists, fileLists] = await Promise.all([
2342
2592
  queryChunked(filters, query),
2343
2593
  Promise.all(kinds.map((kind) => creatorsOrNone(kind, query, cache))),
2594
+ Promise.all(folders.map((folder) => folderFilesOf(folder, query, lookupPeople, cache))),
2344
2595
  ]);
2345
2596
  const creatorsByKind = new Map(kinds.map((kind, i) => [kind, creatorLists[i]]));
2597
+ const filesByFolder = new Map(folders.map((folder, i) => [folder, fileLists[i]]));
2346
2598
  // Every card's children's changes in one more read for the whole set, not
2347
2599
  // one per card (MAN-7) — and none at all when no card has a fold to read.
2348
2600
  const followUp = [];
@@ -2377,7 +2629,7 @@ cache, options = {}) {
2377
2629
  for (const key of peopleOf(built))
2378
2630
  if (key in people)
2379
2631
  own[key] = people[key];
2380
- results[reference] = withBorrowed(withPeople(built, own), borrowedActions(plan.pointer.kind, plan.resolved, creatorsByKind.get(plan.pointer.kind) ?? []));
2632
+ results[reference] = withFiles(withBorrowed(withPeople(built, own), borrowedActions(plan.pointer.kind, plan.resolved, creatorsByKind.get(plan.pointer.kind) ?? [])), plan.pointer.kind === KIND_CHANNEL_METADATA ? filesByFolder.get(plan.pointer.identifier) : undefined);
2381
2633
  }
2382
2634
  return results;
2383
2635
  }
@@ -2623,6 +2875,24 @@ cache) {
2623
2875
  }
2624
2876
  return results;
2625
2877
  }
2878
+ /**
2879
+ * The files a Folder's card lists ({@link ArchiveReadOptions.folderFiles}):
2880
+ * what its relay-signed `30890` names, never what files claim by naming the
2881
+ * Folder themselves. `undefined` — no list, not an empty one — for a Folder
2882
+ * with no listing (a DM is one) and when the listing could not be read.
2883
+ */
2884
+ async function folderFilesOf(folder, query, lookupPeople, cache) {
2885
+ try {
2886
+ const contents = await resolveFolderContents(folder, query, lookupPeople, cache, { listedOnly: true });
2887
+ return contents.hasState ? contents.files : undefined;
2888
+ }
2889
+ catch {
2890
+ return undefined;
2891
+ }
2892
+ }
2893
+ function withFiles(object, files) {
2894
+ return files ? { ...object, children: files } : object;
2895
+ }
2626
2896
  /**
2627
2897
  * Mark each object that is hidden with an archived parent — FOL-46.
2628
2898
  *
@@ -4302,6 +4572,8 @@ const nameOf = (event) => (event ? tagValue(event, 'name') : undefined);
4302
4572
  /**
4303
4573
  * The owners and admins a `kind:39001` lists — kept only when the channel's own
4304
4574
  * signer, the relay, signed it: anybody can publish an event of that shape.
4575
+ *
4576
+ * why: https://github.com/estiva-app/estiva-docs/blob/main/decisions/only-owners-and-admins-rename-or-archive-a-folder.md
4305
4577
  */
4306
4578
  function folderAdminsOf(admins, channel) {
4307
4579
  if (!admins || !channel || admins.pubkey !== channel.pubkey)
@@ -4810,7 +5082,9 @@ cache, options = {}) {
4810
5082
  addresses: [...new Set(state.tags.filter((t) => t[0] === 'a' && t[1]).map((t) => t[1]))],
4811
5083
  placed: new Map(),
4812
5084
  }
4813
- : await addressesByContainment(folder, query);
5085
+ : options.listedOnly
5086
+ ? { addresses: [], placed: new Map() }
5087
+ : await addressesByContainment(folder, query);
4814
5088
  if (addresses.length === 0) {
4815
5089
  // Nothing listed, so no change query to ride on: the Folder's own archive
4816
5090
  // is one small read of its own.