@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.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@estiva-app/interop",
3
- "version": "0.56.0",
3
+ "version": "0.58.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/folders.ts CHANGED
@@ -42,6 +42,8 @@
42
42
  * relay lets only the channel's owners and admins change that, while any
43
43
  * member may send a `kind:1852` — so a name on a command would let anyone
44
44
  * retitle the Folder for every reader that believed it.
45
+ *
46
+ * why: https://github.com/estiva-app/estiva-docs/blob/main/decisions/folders-belong-to-the-protocol.md
45
47
  */
46
48
  import {
47
49
  buildCreateChannel,
@@ -316,6 +318,8 @@ export function listedBeneath<T extends MovableFile>(listing: readonly T[], file
316
318
  * channel or absent (`target-is-private`, §3.1).
317
319
  *
318
320
  * A move to the same Folder, or of a set the source does not list, plans nothing.
321
+ *
322
+ * why: https://github.com/estiva-app/estiva-docs/blob/main/decisions/moving-a-file-never-changes-who-can-read-it.md
319
323
  */
320
324
  export function planMoveFile(
321
325
  pubkey: string,
package/src/index.ts CHANGED
@@ -38,6 +38,7 @@ export {
38
38
  listFolders,
39
39
  topLevelFolders,
40
40
  ARCHIVED_FIELD,
41
+ SUMMARY_FIELD,
41
42
  isArchived,
42
43
  isClosedStatus,
43
44
  archiveImpact,
@@ -47,6 +48,7 @@ export {
47
48
  KIND_FOLDER_STATE,
48
49
  KIND_CHANNEL_METADATA,
49
50
  KIND_BARE_FILE,
51
+ KIND_MESSAGE,
50
52
  MOVED_TO_TAG,
51
53
  BARE_FILE_MANIFEST_ADDRESS,
52
54
  FOLDER_ACTIONS_ADDRESS,
package/src/projection.ts CHANGED
@@ -209,6 +209,15 @@ const KIND_HANDLER_INFORMATION = 31990
209
209
  * finding comments the moment an app said something different.
210
210
  */
211
211
  const KIND_COMMENT = 1111
212
+ /**
213
+ * NIP-29's chat message, the one a Folder's conversation is made of — SPEC §7.8.
214
+ *
215
+ * Owned by no app, like a comment: the specification says how it draws and
216
+ * where it opens, so no manifest's `k` tag is asked about it.
217
+ *
218
+ * why: https://github.com/estiva-app/estiva-docs/blob/main/decisions/a-chat-message-belongs-to-the-protocol.md
219
+ */
220
+ export const KIND_MESSAGE = 9
212
221
  /**
213
222
  * NIP-09's deletion request. Protocol, like the two above, and the one kind an
214
223
  * action may emit that is neither a change nor a comment nor a creation: an
@@ -1374,6 +1383,19 @@ export const MOVED_TO_TAG = 'A'
1374
1383
  */
1375
1384
  export const ARCHIVED_FIELD = 'archived'
1376
1385
 
1386
+ /**
1387
+ * The field, and the root tag seeding it, that holds a file's one-line summary,
1388
+ * whatever its kind — SPEC §6.12.
1389
+ *
1390
+ * Plain text, one or two sentences, beside the title: what a card, a row or a
1391
+ * picker shows under it. Changed by a `kind:1851` like the title, last write
1392
+ * wins, and a value that is blank after trimming means no summary. Every file
1393
+ * kind's `subtitle` reads it ({@link defaultSubtitle}), so no manifest has to.
1394
+ *
1395
+ * why: https://github.com/estiva-app/estiva-docs/blob/main/decisions/a-files-summary-is-its-own-field.md
1396
+ */
1397
+ export const SUMMARY_FIELD = 'summary'
1398
+
1377
1399
  /**
1378
1400
  * Where a `ResolvedManifest.address` would name the manifest event, this names
1379
1401
  * the section of the specification the manifest is built from. Not an address,
@@ -1439,6 +1461,22 @@ const BARE_FILE_MANIFEST: Manifest = {
1439
1461
  body: { field: 'content' },
1440
1462
  },
1441
1463
  },
1464
+ /*
1465
+ A chat message, for the comment's reason: no app owns `kind:9` (SPEC
1466
+ §7.8). Peek's manifest claimed it until this release, and drew it exactly
1467
+ so — the author as the title, because the text carries structure and is
1468
+ no title; the text as the body, untruncated.
1469
+
1470
+ why: https://github.com/estiva-app/estiva-docs/blob/main/decisions/a-chat-message-belongs-to-the-protocol.md
1471
+ */
1472
+ [String(KIND_MESSAGE)]: {
1473
+ widget: ['message', 'card'],
1474
+ noun: 'message',
1475
+ slots: {
1476
+ title: { field: 'pubkey', as: 'pubkey' },
1477
+ body: { field: 'content' },
1478
+ },
1479
+ },
1442
1480
  },
1443
1481
  /*
1444
1482
  The manifest is the only place a consumer learns of any of these actions
@@ -1498,6 +1536,23 @@ const BARE_FILE_MANIFEST: Manifest = {
1498
1536
  emits: { kind: 1851, field: 'description' },
1499
1537
  input: { type: 'string', format: BLOCK_DOCUMENT_FORMAT },
1500
1538
  },
1539
+ /*
1540
+ `summarize` sets the file's one-line summary (SPEC §6.12): plain text, so
1541
+ its input declares no `format` (§7.3), and a consumer finds it by
1542
+ `emits.field`, not by this id. An empty value clears it, the summary the
1543
+ file was created with included.
1544
+ */
1545
+ {
1546
+ id: 'summarize',
1547
+ label: 'Summary',
1548
+ description:
1549
+ "Set this file's summary: one or two sentences of plain text, about 240 characters, shown under its " +
1550
+ 'title wherever it is met in one line. A change event, so anyone in the Folder may; an empty value clears it.',
1551
+ effect: 'writes',
1552
+ appliesTo: [String(KIND_BARE_FILE)],
1553
+ emits: { kind: 1851, field: SUMMARY_FIELD },
1554
+ input: { type: 'string' },
1555
+ },
1501
1556
  /*
1502
1557
  `move` is the `parent` field SPEC §6.7 already defines, declared so a
1503
1558
  consumer draws the control from here as it draws Rename (FOL-4). The value
@@ -1567,6 +1622,8 @@ function bareFileManifest(): ResolvedManifest {
1567
1622
  * What a Folder's built-in actions are declared by — SPEC §3.2, as
1568
1623
  * {@link BARE_FILE_MANIFEST_ADDRESS} is for the bare file. The
1569
1624
  * `declaredBy.address` of an action no app declared.
1625
+ *
1626
+ * why: https://github.com/estiva-app/estiva-docs/blob/main/decisions/folders-belong-to-the-protocol.md
1570
1627
  */
1571
1628
  export const FOLDER_ACTIONS_ADDRESS = 'spec:3.2'
1572
1629
 
@@ -1588,23 +1645,60 @@ export const FOLDER_ACTIONS_ADDRESS = 'spec:3.2'
1588
1645
  * is the bare file's own, so the created object is drawn the way every other
1589
1646
  * bare file is. Each consumer offers it only if it may sign `30840` and `1852`
1590
1647
  * (§3.3).
1648
+ *
1649
+ * Starting a conversation is the second, moved here from Peek's manifest: a
1650
+ * `kind:9` carrying the Folder in `h` and nothing else — never an `a` naming
1651
+ * the `39000`, which §3.2 reads as a mention. A consumer offers it only on a
1652
+ * Folder whose relay-signed `30890` it has read, since a group without one is
1653
+ * a DM or a channel, and only if it may sign `kind:9`.
1591
1654
  */
1592
1655
  const FOLDER_CREATOR: ResolvedManifest = {
1593
1656
  manifest: {
1594
1657
  name: 'Folder',
1595
1658
  about: 'What every app may do in a Folder, whichever app made it.',
1596
- projections: { [String(KIND_BARE_FILE)]: BARE_FILE_MANIFEST.projections![String(KIND_BARE_FILE)] },
1659
+ projections: {
1660
+ [String(KIND_BARE_FILE)]: BARE_FILE_MANIFEST.projections![String(KIND_BARE_FILE)],
1661
+ [String(KIND_MESSAGE)]: BARE_FILE_MANIFEST.projections![String(KIND_MESSAGE)],
1662
+ },
1597
1663
  actions: [
1598
1664
  {
1599
1665
  id: 'create-file',
1600
1666
  label: 'New file',
1601
1667
  description:
1602
- 'Put a new file in this Folder: a title, and nothing else yet. Everyone who can read the Folder can read ' +
1668
+ '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 ' +
1603
1669
  'it, and the Folder lists it straight away. The app opening files calls it by its own word — Peek says topic.',
1604
1670
  effect: 'writes',
1605
1671
  appliesTo: String(KIND_CHANNEL_METADATA),
1606
1672
  emits: { kind: KIND_BARE_FILE, listed: true },
1607
- input: { type: 'object', properties: { title: { type: 'string' } }, required: ['title'] },
1673
+ // `summary` is the root tag that seeds the new file's summary (SPEC
1674
+ // §3.2, §6.12); left empty, it is omitted (§7.3).
1675
+ input: {
1676
+ type: 'object',
1677
+ properties: { title: { type: 'string' }, [SUMMARY_FIELD]: { type: 'string' } },
1678
+ required: ['title'],
1679
+ },
1680
+ },
1681
+ /*
1682
+ `toAddressOf: 'self'` and no `setTag`: the message hangs under the
1683
+ Folder it was started in, and names it only with the `h` every created
1684
+ event gets. One property, the body, written to `content` — a `kind:9`
1685
+ has an author and a text and nothing else.
1686
+ */
1687
+ {
1688
+ id: 'start-a-conversation',
1689
+ label: 'Start a conversation',
1690
+ description:
1691
+ 'Start a new conversation in this Folder, as a root message that people can then reply to. ' +
1692
+ 'Use when something is worth its own thread rather than an answer inside an existing one — ' +
1693
+ 'this cannot reply to a message. Everyone who can read the Folder reads it.',
1694
+ effect: 'writes',
1695
+ appliesTo: String(KIND_CHANNEL_METADATA),
1696
+ emits: { kind: KIND_MESSAGE, toAddressOf: 'self' },
1697
+ input: {
1698
+ type: 'object',
1699
+ properties: { message: { type: 'string', target: 'content' } },
1700
+ required: ['message'],
1701
+ },
1608
1702
  },
1609
1703
  ],
1610
1704
  },
@@ -1612,6 +1706,59 @@ const FOLDER_CREATOR: ResolvedManifest = {
1612
1706
  viaRecommendation: false,
1613
1707
  }
1614
1708
 
1709
+ /**
1710
+ * How a Folder draws — SPEC §3.2, answered here before NIP-89 is asked, as the
1711
+ * bare file's is.
1712
+ *
1713
+ * No app owns a Folder, so no `kind:31990` may claim `39000`; until this
1714
+ * release Peek's did, and every app learned a Folder's name from it. The title
1715
+ * is the channel record's `name`, the subtitle its `about` (the built-in
1716
+ * subtitle, {@link defaultSubtitle}), and the noun "folder".
1717
+ *
1718
+ * **No `list` slot.** What a Folder holds is what its relay-signed `30890`
1719
+ * names, which no `children` declaration can say, and it is read by
1720
+ * {@link resolveFolderContents} — only the files this viewer resolves, never a
1721
+ * count of the rest. A card asks for them as its `children` with
1722
+ * {@link ArchiveReadOptions.folderFiles}; a chip does not, and pays nothing.
1723
+ * Peek's claim listed fifty chat messages instead, and every Folder chip paid
1724
+ * for them. A Folder is never inside another (SPEC §3.1), so no listing needs a
1725
+ * Folder's children drawn under its row.
1726
+ *
1727
+ * No actions of its own either: every app's way into a Folder is
1728
+ * {@link FOLDER_CREATOR}'s, offered beside the others with `declaredBy`
1729
+ * naming this section, so a consumer tells them apart as it always has.
1730
+ *
1731
+ * why: https://github.com/estiva-app/estiva-docs/blob/main/decisions/folders-belong-to-the-protocol.md
1732
+ */
1733
+ const FOLDER_MANIFEST: Manifest = {
1734
+ name: 'Folder',
1735
+ about: 'A Folder no app owns: its name, its one-liner, and the files its state lists.',
1736
+ projections: {
1737
+ [String(KIND_CHANNEL_METADATA)]: {
1738
+ widget: 'card',
1739
+ noun: 'folder',
1740
+ // The cut Peek's claim made, so no card grows when the claim goes.
1741
+ slots: { title: { tag: 'name' }, subtitle: { tag: 'about', truncate: 120 } },
1742
+ },
1743
+ },
1744
+ }
1745
+
1746
+ /**
1747
+ * The Folder's manifest, named by the app that opens it — the bare file's rule
1748
+ * ({@link bareFileOpenedBy}): its link goes to the app declaring the
1749
+ * conversation aspect, by its `naddr` template, so "Open in Peek" says where.
1750
+ * With no such app the Folder still draws, with nowhere to open.
1751
+ */
1752
+ function folderManifest(opener: ResolvedManifest | null): ResolvedManifest {
1753
+ const name = opener?.webTemplate ? wordOf(opener.manifest.name) : undefined
1754
+ return {
1755
+ manifest: name ? { ...FOLDER_MANIFEST, name } : FOLDER_MANIFEST,
1756
+ address: FOLDER_ACTIONS_ADDRESS,
1757
+ viaRecommendation: false,
1758
+ ...(opener?.webTemplate ? { webTemplate: opener.webTemplate } : {}),
1759
+ }
1760
+ }
1761
+
1615
1762
  /**
1616
1763
  * The built-in manifest, named by the app that opens it — PRO-24.
1617
1764
  *
@@ -1620,6 +1767,8 @@ const FOLDER_CREATOR: ResolvedManifest = {
1620
1767
  * runtime's, so a published manifest still cannot change how a bare file
1621
1768
  * behaves; it can only say what it is called where it opens. A comment takes
1622
1769
  * the name (it opens in the same app) and not the noun, which is the file's.
1770
+ *
1771
+ * why: https://github.com/estiva-app/estiva-docs/blob/main/decisions/a-file-is-labelled-by-its-type-not-its-app.md
1623
1772
  */
1624
1773
  function bareFileOpenedBy(opener: Manifest, template: string): ResolvedManifest {
1625
1774
  const name = wordOf(opener.name) ?? BARE_FILE_MANIFEST.name
@@ -1867,10 +2016,19 @@ export async function resolveManifest(
1867
2016
  // A comment resolves through the built-in manifest as a bare file does, and
1868
2017
  // opens in the same app — the one that renders every file's conversation
1869
2018
  // is the one that can show a thread in it (FOL-38).
1870
- if (pointer.kind === KIND_BARE_FILE || pointer.kind === KIND_COMMENT) {
1871
- const opener = await resolveAspectApp('conversation', query, cache, pointer.kind === KIND_COMMENT ? 'nevent' : 'naddr')
2019
+ // A chat message is the comment's case exactly (SPEC §7.8), and a Folder has
2020
+ // its own built-in that opens in the same app (§3.2): neither is asked of a
2021
+ // `k` tag, so a manifest still claiming one is not read for it.
2022
+ if (pointer.kind === KIND_BARE_FILE || pointer.kind === KIND_COMMENT || pointer.kind === KIND_MESSAGE) {
2023
+ const opener = await resolveAspectApp('conversation', query, cache, pointer.kind === KIND_BARE_FILE ? 'naddr' : 'nevent')
1872
2024
  return opener?.webTemplate ? bareFileOpenedBy(opener.manifest, opener.webTemplate) : bareFileManifest()
1873
2025
  }
2026
+ // A refused sweep costs a Folder its link, never its name: Peek's `#k` claim
2027
+ // was a read of its own, and the Folder still drew when the sweep failed.
2028
+ // Not remembered (`throughCache` keeps no failure), so the next resolve asks.
2029
+ if (pointer.kind === KIND_CHANNEL_METADATA) {
2030
+ return folderManifest(await resolveAspectApp('conversation', query, cache, 'naddr').catch(() => null))
2031
+ }
1874
2032
  return throughCache(cache, `${pointer.kind}:${pointer.pubkey}`, () => resolveManifestUncached(pointer, query))
1875
2033
  }
1876
2034
 
@@ -2012,6 +2170,8 @@ function creatorsOrNone(kind: number, query: QueryFn, cache?: ProjectionCache):
2012
2170
  * ({@link FOLDER_CREATOR}, INT-12): no app owns a Folder (SPEC §3.2), so no
2013
2171
  * app's claim to create the same kind there outranks the specification's —
2014
2172
  * a manifest declaring a bare file on a Folder is the second row, not this.
2173
+ * The Folder's owner is the specification's too ({@link FOLDER_MANIFEST}), and
2174
+ * declares no actions, so these are offered once.
2015
2175
  */
2016
2176
  function borrowedFrom(kind: number, owner: ResolvedManifest, creators: readonly ResolvedManifest[]): ResolvedManifest[] {
2017
2177
  const builtIn = kind === KIND_CHANNEL_METADATA ? [FOLDER_CREATOR] : []
@@ -2060,10 +2220,12 @@ export async function resolveActingManifest(
2060
2220
  query: QueryFn,
2061
2221
  cache?: ProjectionCache,
2062
2222
  ): Promise<ResolvedManifest | null> {
2223
+ // A Folder's built-in needs no sweep, so a refused one must not cost it
2224
+ // (INT-12). Asked before the owner, whose address is the same section and
2225
+ // whose manifest only draws: every Folder action is the creator's.
2226
+ if (pointer.kind === KIND_CHANNEL_METADATA && declaredBy === FOLDER_ACTIONS_ADDRESS) return FOLDER_CREATOR
2063
2227
  const owner = await resolveManifest(pointer, query, cache)
2064
2228
  if (!owner || !declaredBy || declaredBy === owner.address) return owner
2065
- // A Folder's built-in needs no sweep, so a refused one must not cost it (INT-12).
2066
- if (pointer.kind === KIND_CHANNEL_METADATA && declaredBy === FOLDER_ACTIONS_ADDRESS) return FOLDER_CREATOR
2067
2229
  const creators = await creatorsOn(pointer.kind, query, cache)
2068
2230
  return borrowedFrom(pointer.kind, owner, creators).find((creator) => creator.address === declaredBy) ?? null
2069
2231
  }
@@ -2153,6 +2315,9 @@ import { contentFormatOf, type ContentFormat } from '@estiva-app/protocol'
2153
2315
  */
2154
2316
  export const BODY_SLOT = 'body'
2155
2317
 
2318
+ /** The slot that is a file's summary, one line of plain text (SPEC §7.2). */
2319
+ const SUBTITLE_SLOT = 'subtitle'
2320
+
2156
2321
 
2157
2322
  /**
2158
2323
  * Does this change sit in the Folder its target is filed in — SPEC §6.2.
@@ -2215,6 +2380,9 @@ function foldChanges(changes: SignedEvent[], rule: RecordsRule, root: SignedEven
2215
2380
  const field = tagValue(change, rule.fieldTag)
2216
2381
  const value = tagValue(change, rule.valueTag)
2217
2382
  if (!field || value === undefined) continue // a partial change sets nothing
2383
+ // A summary is new, so it takes neither of §6.2's exceptions: a change the
2384
+ // reader cannot check against the root's Folder is not read (SPEC §6.12).
2385
+ if (field === SUMMARY_FIELD && !folders) continue
2218
2386
  // The format travels with the *winning* change, not with the object. SPEC
2219
2387
  // §13.4: "an app MUST read the tag from the event it took the value from,
2220
2388
  // never from the object's root" — a description created as marker text and
@@ -2780,7 +2948,19 @@ function resolveSlot(
2780
2948
  const source = rawSlotValue(spec, root, folded, name === BODY_SLOT)
2781
2949
 
2782
2950
  if (source === undefined || source.value === '') return null
2783
- const raw = source.value
2951
+ let raw = source.value
2952
+ /*
2953
+ `subtitle` is plain text on one line (SPEC §7.2, §6.12): line breaks fold to
2954
+ spaces, and a value that is blank once trimmed is no subtitle — a summary
2955
+ cleared with " " reads as cleared, and the seed does not show through it.
2956
+ Left to each consumer, `slots.subtitle &&` drew a blank one as an empty line
2957
+ (Peek's ForeignObjectWidget). A body-shaped value declared into the slot is
2958
+ left alone; the truncation guard below is what speaks to that.
2959
+ */
2960
+ if (name === SUBTITLE_SLOT && source.format !== 'blocks' && source.format !== 'unknown') {
2961
+ raw = raw.replace(/\s+/g, ' ').trim()
2962
+ if (raw === '') return null
2963
+ }
2784
2964
 
2785
2965
  /*
2786
2966
  PRO-8's rule, now enforceable rather than only written down.
@@ -2820,6 +3000,69 @@ function resolveSlot(
2820
3000
  }
2821
3001
  }
2822
3002
 
3003
+ /*
3004
+ `truncate` is the clamp SPEC §6.12 makes a reader's job: the relay does not
3005
+ hold a writer to about 240 characters, and with no manifest declaring the
3006
+ slot nothing else would cut a 1,000-character summary down to a line. A
3007
+ consumer still clamps it to its own room; this is the backstop.
3008
+ */
3009
+ const SUMMARY_TRUNCATE = 280
3010
+ const SUMMARY_SUBTITLE: SlotSpec = { tag: SUMMARY_FIELD, fold: SUMMARY_FIELD, truncate: SUMMARY_TRUNCATE }
3011
+ const FOLDER_SUBTITLE: SlotSpec = { tag: 'about' }
3012
+
3013
+ /**
3014
+ * Where a kind's `subtitle` comes from whatever its manifest says, or
3015
+ * `undefined` where the manifest decides — SPEC §7.2, §6.12, §3.2.
3016
+ *
3017
+ * - **A Folder** (`kind:39000`): the `about` of its channel record, NIP-29's
3018
+ * one-liner. A `summary` change aimed at one is not read.
3019
+ * - **Every other addressable kind is a file**, and its subtitle is its
3020
+ * summary: the `summary` fold over the root tag of that name. Built in, so an
3021
+ * app's files — an outside company's included — show their summary on every
3022
+ * card with nothing in its manifest, and no manifest can point the line at
3023
+ * another field (Miky, 2026-10-15, kickoff).
3024
+ * - NIP-29's other `39001`–`39009` records, and regular events (a message, a
3025
+ * comment), keep what their manifest declares.
3026
+ */
3027
+ function defaultSubtitle(kind: number): SlotSpec | undefined {
3028
+ if (kind === KIND_CHANNEL_METADATA) return FOLDER_SUBTITLE
3029
+ if (kind >= 39000 && kind <= 39009) return undefined
3030
+ return isAddressableKind(kind) ? SUMMARY_SUBTITLE : undefined
3031
+ }
3032
+
3033
+ /**
3034
+ * A projection's slots with `subtitle` taken from {@link defaultSubtitle}.
3035
+ *
3036
+ * A declaration naming the same source keeps its `label` and a `truncate`
3037
+ * tighter than the built-in one (Peek's Folder projection truncates `about` at
3038
+ * 120); one naming any other source, or an array, is replaced.
3039
+ */
3040
+ function withDefaultSubtitle(
3041
+ slots: Record<string, SlotSpec | SlotSpec[]>,
3042
+ kind: number,
3043
+ ): Record<string, SlotSpec | SlotSpec[]> {
3044
+ const builtIn = defaultSubtitle(kind)
3045
+ if (!builtIn) return slots
3046
+ const declared = slots[SUBTITLE_SLOT]
3047
+ const same =
3048
+ declared !== undefined &&
3049
+ !Array.isArray(declared) &&
3050
+ declared.tag === builtIn.tag &&
3051
+ declared.fold === builtIn.fold &&
3052
+ declared.field === undefined &&
3053
+ declared.default === undefined &&
3054
+ declared.map === undefined &&
3055
+ declared.as === undefined &&
3056
+ declared.children === undefined
3057
+ if (!same) return { ...slots, [SUBTITLE_SLOT]: builtIn }
3058
+ // Same source: its `label` and a tighter `truncate` stand, never a looser one.
3059
+ const truncate =
3060
+ declared.truncate === undefined || builtIn.truncate === undefined
3061
+ ? (declared.truncate ?? builtIn.truncate)
3062
+ : Math.min(declared.truncate, builtIn.truncate)
3063
+ return { ...slots, [SUBTITLE_SLOT]: { ...builtIn, label: declared.label, truncate } }
3064
+ }
3065
+
2823
3066
  /**
2824
3067
  * Every slot a projection declares, resolved.
2825
3068
  *
@@ -2835,7 +3078,7 @@ function resolveSlots(
2835
3078
  ): { slots: Record<string, ResolvedSlot>; meta: ResolvedSlot[] } {
2836
3079
  const slots: Record<string, ResolvedSlot> = {}
2837
3080
  const meta: ResolvedSlot[] = []
2838
- for (const [name, spec] of Object.entries(projection.slots)) {
3081
+ for (const [name, spec] of Object.entries(withDefaultSubtitle(projection.slots, root.kind))) {
2839
3082
  if (Array.isArray(spec)) {
2840
3083
  for (const one of spec) {
2841
3084
  // An array spec collects into `meta`, so the name it was declared under
@@ -3080,7 +3323,9 @@ function buildObject(args: {
3080
3323
  * nothing.
3081
3324
  */
3082
3325
  const held: Record<string, string> = {}
3083
- for (const spec of Object.values(projection.slots).flat()) {
3326
+ // The built-in subtitle too, or a summary seeded at creation shows on the
3327
+ // card while `summarize` offers a blank to edit (SPEC §6.12).
3328
+ for (const spec of Object.values(withDefaultSubtitle(projection.slots, root.kind)).flat()) {
3084
3329
  // `tag` may name several spellings (see `SlotSpec`); the field this slot
3085
3330
  // *is* keyed on is the first, which is the one the app writes today. The
3086
3331
  // rest are only there to keep older records rendering.
@@ -3235,14 +3480,24 @@ export async function resolveForeignObject(
3235
3480
 
3236
3481
  // Beside the object's own read, not after it: the sweep is cached, and cold
3237
3482
  // it would otherwise add a round trip to every resolve that pays for it.
3238
- const [answered, creators] = await Promise.all([query(plan.filters), creatorsOrNone(pointer.kind, query, cache)])
3483
+ // A Folder card's files too, for the same reason.
3484
+ const [answered, creators, files] = await Promise.all([
3485
+ query(plan.filters),
3486
+ creatorsOrNone(pointer.kind, query, cache),
3487
+ options.folderFiles && pointer.kind === KIND_CHANNEL_METADATA
3488
+ ? folderFilesOf(pointer.identifier, query, lookupPeople, cache)
3489
+ : undefined,
3490
+ ])
3239
3491
  const followUp = childChangeFilters(plan, answered)
3240
3492
  const assembled = assembleObject(plan, answered, followUp.length ? await queryChunked(followUp, query) : [])
3241
3493
  if (assembled.object.unreachable) return assembled.object
3242
3494
  if (options.archivedWith) await markArchivedParents([{ object: assembled.object, manifest: resolved.manifest }], query)
3243
- return withBorrowed(
3244
- withPeople(assembled, await (lookupPeople ?? peopleViaRelay(query))(peopleOf(assembled))),
3245
- borrowedActions(pointer.kind, resolved, creators),
3495
+ return withFiles(
3496
+ withBorrowed(
3497
+ withPeople(assembled, await (lookupPeople ?? peopleViaRelay(query))(peopleOf(assembled))),
3498
+ borrowedActions(pointer.kind, resolved, creators),
3499
+ ),
3500
+ files,
3246
3501
  )
3247
3502
  }
3248
3503
 
@@ -3344,11 +3599,21 @@ export async function resolveForeignObjects(
3344
3599
  // Who else creates on each kind in the set (MAN-8): one sweep per kind, not
3345
3600
  // per object, read beside the objects themselves.
3346
3601
  const kinds = [...new Set(plans.map(({ plan }) => plan.pointer.kind))]
3347
- const [events, creatorLists] = await Promise.all([
3602
+ // And each Folder card's files, once per Folder however it is spelled.
3603
+ const folders = options.folderFiles
3604
+ ? [
3605
+ ...new Set(
3606
+ plans.filter(({ plan }) => plan.pointer.kind === KIND_CHANNEL_METADATA).map(({ plan }) => plan.pointer.identifier),
3607
+ ),
3608
+ ]
3609
+ : []
3610
+ const [events, creatorLists, fileLists] = await Promise.all([
3348
3611
  queryChunked(filters, query),
3349
3612
  Promise.all(kinds.map((kind) => creatorsOrNone(kind, query, cache))),
3613
+ Promise.all(folders.map((folder) => folderFilesOf(folder, query, lookupPeople, cache))),
3350
3614
  ])
3351
3615
  const creatorsByKind = new Map(kinds.map((kind, i) => [kind, creatorLists[i]]))
3616
+ const filesByFolder = new Map(folders.map((folder, i) => [folder, fileLists[i]]))
3352
3617
 
3353
3618
  // Every card's children's changes in one more read for the whole set, not
3354
3619
  // one per card (MAN-7) — and none at all when no card has a fold to read.
@@ -3382,9 +3647,12 @@ export async function resolveForeignObjects(
3382
3647
  // it happened to be resolved beside.
3383
3648
  const own: People = {}
3384
3649
  for (const key of peopleOf(built)) if (key in people) own[key] = people[key]
3385
- results[reference] = withBorrowed(
3386
- withPeople(built, own),
3387
- borrowedActions(plan.pointer.kind, plan.resolved, creatorsByKind.get(plan.pointer.kind) ?? []),
3650
+ results[reference] = withFiles(
3651
+ withBorrowed(
3652
+ withPeople(built, own),
3653
+ borrowedActions(plan.pointer.kind, plan.resolved, creatorsByKind.get(plan.pointer.kind) ?? []),
3654
+ ),
3655
+ plan.pointer.kind === KIND_CHANNEL_METADATA ? filesByFolder.get(plan.pointer.identifier) : undefined,
3388
3656
  )
3389
3657
  }
3390
3658
  return results
@@ -3648,6 +3916,54 @@ export interface ArchiveReadOptions {
3648
3916
  * card would pay it every time (SHI-13's one request per tick).
3649
3917
  */
3650
3918
  archivedWith?: boolean
3919
+ /**
3920
+ * For a Folder's card: also list the files in it this reader can open, as
3921
+ * `children` — SPEC §3.2. What its relay-signed `30890` lists, read as
3922
+ * {@link resolveFolderContents} reads it, so a file this reader cannot
3923
+ * resolve is absent and nothing counts the rest. Off by default, so a Folder
3924
+ * chip in a sentence pays nothing for a list it does not draw; ignored for
3925
+ * anything that is not a Folder.
3926
+ *
3927
+ * A Folder with no `30890` (a DM has none) and one whose listing cannot be
3928
+ * read still draw, without `children`: no list, rather than an empty one
3929
+ * that says it holds nothing.
3930
+ *
3931
+ * The resolve returns once the files have, so read a card's files in a call
3932
+ * of their own: what else is on the page should not wait for them.
3933
+ *
3934
+ * **It costs what a Folder's page costs**, almost all of it its files'
3935
+ * change history (a description edit is a whole `kind:1851`, and no relay
3936
+ * can filter one by its `field`). Estiva HQ on 2026-10-16, 24 files: 11
3937
+ * requests and 7.6 MB cold, 3 and 7.6 MB warm, ~2 s — where the chip is 1
3938
+ * request and nothing warm. Read it on open and focus, not on a refresh tick.
3939
+ *
3940
+ * why: https://github.com/estiva-app/estiva-docs/blob/main/decisions/folders-belong-to-the-protocol.md
3941
+ */
3942
+ folderFiles?: boolean
3943
+ }
3944
+
3945
+ /**
3946
+ * The files a Folder's card lists ({@link ArchiveReadOptions.folderFiles}):
3947
+ * what its relay-signed `30890` names, never what files claim by naming the
3948
+ * Folder themselves. `undefined` — no list, not an empty one — for a Folder
3949
+ * with no listing (a DM is one) and when the listing could not be read.
3950
+ */
3951
+ async function folderFilesOf(
3952
+ folder: string,
3953
+ query: QueryFn,
3954
+ lookupPeople: PeopleFn | undefined,
3955
+ cache: ProjectionCache | undefined,
3956
+ ): Promise<ForeignObject[] | undefined> {
3957
+ try {
3958
+ const contents = await resolveFolderContents(folder, query, lookupPeople, cache, { listedOnly: true })
3959
+ return contents.hasState ? contents.files : undefined
3960
+ } catch {
3961
+ return undefined
3962
+ }
3963
+ }
3964
+
3965
+ function withFiles(object: ForeignObject, files: ForeignObject[] | undefined): ForeignObject {
3966
+ return files ? { ...object, children: files } : object
3651
3967
  }
3652
3968
 
3653
3969
  /**
@@ -5611,6 +5927,8 @@ const nameOf = (event: SignedEvent | undefined) => (event ? tagValue(event, 'nam
5611
5927
  /**
5612
5928
  * The owners and admins a `kind:39001` lists — kept only when the channel's own
5613
5929
  * signer, the relay, signed it: anybody can publish an event of that shape.
5930
+ *
5931
+ * why: https://github.com/estiva-app/estiva-docs/blob/main/decisions/only-owners-and-admins-rename-or-archive-a-folder.md
5614
5932
  */
5615
5933
  function folderAdminsOf(admins: SignedEvent | undefined, channel: SignedEvent | undefined): string[] {
5616
5934
  if (!admins || !channel || admins.pubkey !== channel.pubkey) return []
@@ -5646,9 +5964,15 @@ export interface FolderSummary {
5646
5964
  * The title: its `kind:39000`'s `name`, and only that (SPEC §3.2). A `name`
5647
5965
  * an older `kind:1852` left on the state is never read — any member may send
5648
5966
  * one, and only owners and admins may rename the channel.
5967
+ *
5968
+ * why: https://github.com/estiva-app/estiva-docs/blob/main/decisions/only-owners-and-admins-rename-or-archive-a-folder.md
5649
5969
  */
5650
5970
  name?: string
5651
- /** True once the relay maintains state for it, rather than it being a bare channel. */
5971
+ /**
5972
+ * True once the relay maintains state for it, rather than it being a bare channel.
5973
+ *
5974
+ * why: https://github.com/estiva-app/estiva-docs/blob/main/decisions/a-folder-is-a-group-the-relay-lists.md
5975
+ */
5652
5976
  hasState: boolean
5653
5977
  /**
5654
5978
  * Present when the Folder's relay-signed `kind:39000` carries `["private"]`
@@ -6216,6 +6540,12 @@ export async function resolveFolderContents(
6216
6540
  * Every other list wants the default.
6217
6541
  */
6218
6542
  includeArchived?: boolean
6543
+ /**
6544
+ * Only what the relay-signed `30890` lists: a Folder with none lists no
6545
+ * files, rather than the files that name it themselves. For a Folder's
6546
+ * card ({@link ArchiveReadOptions.folderFiles}).
6547
+ */
6548
+ listedOnly?: boolean
6219
6549
  } = {},
6220
6550
  ): Promise<FolderContents> {
6221
6551
  // 1. The folder itself. Both kinds in one trip: the state is the model and
@@ -6254,7 +6584,9 @@ export async function resolveFolderContents(
6254
6584
  addresses: [...new Set(state.tags.filter((t) => t[0] === 'a' && t[1]).map((t) => t[1]))],
6255
6585
  placed: new Map<string, SignedEvent[]>(),
6256
6586
  }
6257
- : await addressesByContainment(folder, query)
6587
+ : options.listedOnly
6588
+ ? { addresses: [], placed: new Map<string, SignedEvent[]>() }
6589
+ : await addressesByContainment(folder, query)
6258
6590
 
6259
6591
  if (addresses.length === 0) {
6260
6592
  // Nothing listed, so no change query to ride on: the Folder's own archive