@estiva-app/interop 0.57.0 → 0.59.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.
@@ -6,7 +6,8 @@
6
6
  * resolved object into a row, and typed text into the search tier — so Peek
7
7
  * and Ship draw the same rows from the same reads.
8
8
  *
9
- * A row is the type word and the current title; an issue is captioned with its
9
+ * A row is the type word, the current title and, when it has one, the file's
10
+ * summary (SPEC §6.12, SUM-7); an issue is captioned with its
10
11
  * project's title, and nothing names a Folder (Miky, 2026-10-03). Only what the
11
12
  * reader resolved is offered: an object the relay did not hand back to them is
12
13
  * never a row, so nothing unreadable is offered. An archived file is offered
@@ -14,7 +15,11 @@
14
15
  */
15
16
  import { type ReferenceCandidate, type ReferenceType } from '@estiva-app/conversation';
16
17
  import { type ForeignObject, type ProjectionCache, type QueryFn } from './projection.js';
17
- /** The kinds `[` offers as files, and the type word each draws as. */
18
+ /**
19
+ * The kinds `[` offers as files, and the type word each draws as. A Leaf page
20
+ * is offered in every app, beside topics, projects and issues (Miky, SUM-7
21
+ * kickoff, 2026-10-16).
22
+ */
18
23
  export declare const REFERENCE_FILE_TYPES: Readonly<Record<number, ReferenceType>>;
19
24
  export interface FileCandidatesOptions {
20
25
  cache?: ProjectionCache;
@@ -1 +1 @@
1
- {"version":3,"file":"references.d.ts","sourceRoot":"","sources":["../src/references.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,EAML,KAAK,kBAAkB,EACvB,KAAK,aAAa,EACnB,MAAM,0BAA0B,CAAA;AACjC,OAAO,EAIL,KAAK,aAAa,EAClB,KAAK,eAAe,EACpB,KAAK,OAAO,EACb,MAAM,iBAAiB,CAAA;AAKxB,sEAAsE;AACtE,eAAO,MAAM,oBAAoB,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,CAIxE,CAAA;AAqBD,MAAM,WAAW,qBAAqB;IACpC,KAAK,CAAC,EAAE,eAAe,CAAA;IACvB,0FAA0F;IAC1F,EAAE,CAAC,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CACjC;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,cAAc,CAClC,OAAO,EAAE,SAAS,CAAC,aAAa,GAAG,IAAI,GAAG,SAAS,CAAC,EAAE,EACtD,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,OAAO,EACd,EAAE,KAAK,EAAE,EAAE,EAAE,GAAE,qBAA0B,GACxC,OAAO,CAAC,kBAAkB,EAAE,CAAC,CA6B/B;AAED,MAAM,WAAW,2BAA4B,SAAQ,IAAI,CAAC,qBAAqB,EAAE,IAAI,CAAC;IACpF,2FAA2F;IAC3F,KAAK,CAAC,EAAE,MAAM,CAAA;CACf;AAWD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,oBAAoB,CACxC,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,OAAO,EACd,EAAE,KAAU,EAAE,GAAG,OAAO,EAAE,GAAE,2BAAgC,GAC3D,OAAO,CAAC,kBAAkB,EAAE,CAAC,CAqB/B"}
1
+ {"version":3,"file":"references.d.ts","sourceRoot":"","sources":["../src/references.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,OAAO,EAML,KAAK,kBAAkB,EACvB,KAAK,aAAa,EACnB,MAAM,0BAA0B,CAAA;AACjC,OAAO,EAIL,KAAK,aAAa,EAClB,KAAK,eAAe,EACpB,KAAK,OAAO,EACb,MAAM,iBAAiB,CAAA;AAMxB;;;;GAIG;AACH,eAAO,MAAM,oBAAoB,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,CAKxE,CAAA;AA2BD,MAAM,WAAW,qBAAqB;IACpC,KAAK,CAAC,EAAE,eAAe,CAAA;IACvB,0FAA0F;IAC1F,EAAE,CAAC,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CACjC;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,cAAc,CAClC,OAAO,EAAE,SAAS,CAAC,aAAa,GAAG,IAAI,GAAG,SAAS,CAAC,EAAE,EACtD,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,OAAO,EACd,EAAE,KAAK,EAAE,EAAE,EAAE,GAAE,qBAA0B,GACxC,OAAO,CAAC,kBAAkB,EAAE,CAAC,CA+B/B;AAED,MAAM,WAAW,2BAA4B,SAAQ,IAAI,CAAC,qBAAqB,EAAE,IAAI,CAAC;IACpF,2FAA2F;IAC3F,KAAK,CAAC,EAAE,MAAM,CAAA;CACf;AAWD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,oBAAoB,CACxC,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,OAAO,EACd,EAAE,KAAU,EAAE,GAAG,OAAO,EAAE,GAAE,2BAAgC,GAC3D,OAAO,CAAC,kBAAkB,EAAE,CAAC,CAqB/B"}
@@ -6,7 +6,8 @@
6
6
  * resolved object into a row, and typed text into the search tier — so Peek
7
7
  * and Ship draw the same rows from the same reads.
8
8
  *
9
- * A row is the type word and the current title; an issue is captioned with its
9
+ * A row is the type word, the current title and, when it has one, the file's
10
+ * summary (SPEC §6.12, SUM-7); an issue is captioned with its
10
11
  * project's title, and nothing names a Folder (Miky, 2026-10-03). Only what the
11
12
  * reader resolved is offered: an object the relay did not hand back to them is
12
13
  * never a row, so nothing unreadable is offered. An archived file is offered
@@ -16,11 +17,22 @@ import { FILE_TIER, fileReference, KIND_CHANGE, referenceMatch, refMatch, } from
16
17
  import { isClosedStatus, KIND_BARE_FILE, resolveForeignRoots, } from './projection.js';
17
18
  const KIND_PROJECT = 30850;
18
19
  const KIND_ISSUE = 30851;
19
- /** The kinds `[` offers as files, and the type word each draws as. */
20
+ const KIND_DOCUMENT = 30842;
21
+ /**
22
+ * The kinds `[` offers as files, and the type word each draws as. A Leaf page
23
+ * is offered in every app, beside topics, projects and issues (Miky, SUM-7
24
+ * kickoff, 2026-10-16).
25
+ */
20
26
  export const REFERENCE_FILE_TYPES = {
21
27
  [KIND_PROJECT]: 'project',
22
28
  [KIND_ISSUE]: 'issue',
23
29
  [KIND_BARE_FILE]: 'topic',
30
+ [KIND_DOCUMENT]: 'document',
31
+ };
32
+ /** A file's summary as a row's second line: plain text, never a body declared into the slot. */
33
+ const summaryOf = (object) => {
34
+ const slot = object.slots.subtitle;
35
+ return slot && !slot.format ? slot.value.replace(/\s+/g, ' ').trim() || undefined : undefined;
24
36
  };
25
37
  const typeOf = (kind) => REFERENCE_FILE_TYPES[kind];
26
38
  /** An object `[` may offer: a file kind it knows, resolved, with a title. */
@@ -63,6 +75,7 @@ export async function fileCandidates(objects, tier, query, { cache, at } = {}) {
63
75
  return files.map((o) => {
64
76
  const parent = o.kind === KIND_ISSUE && o.parentRef ? parents.get(o.parentRef) : undefined;
65
77
  const ref = refOf(o);
78
+ const summary = summaryOf(o);
66
79
  return {
67
80
  id: o.address,
68
81
  uri: fileReference(o.address),
@@ -71,6 +84,7 @@ export async function fileCandidates(objects, tier, query, { cache, at } = {}) {
71
84
  title: o.slots.title.value,
72
85
  // An issue reads "CON-33 · Conversation standard": the ref first, so a hit by ref shows it (Miky, 2026-10-05).
73
86
  caption: [ref, parent?.slots.title?.value].filter(Boolean).join(' · '),
87
+ ...(summary ? { summary } : {}),
74
88
  tier,
75
89
  ...(ref ? { search: ref } : {}),
76
90
  ...(isClosedStatus(o.slots.status) ? { closed: true } : {}),
@@ -1 +1 @@
1
- {"version":3,"file":"references.js","sourceRoot":"","sources":["../src/references.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"references.js","sourceRoot":"","sources":["../src/references.ts"],"names":[],"mappings":"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"}
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@estiva-app/interop",
3
- "version": "0.57.0",
3
+ "version": "0.59.0",
4
4
  "description": "Render and act on another app's objects from its published NIP-89 manifest. The owner defines the projection; the consumer decides how it looks.",
5
5
  "license": "MIT",
6
6
  "type": "module",
package/src/index.ts CHANGED
@@ -48,6 +48,7 @@ export {
48
48
  KIND_FOLDER_STATE,
49
49
  KIND_CHANNEL_METADATA,
50
50
  KIND_BARE_FILE,
51
+ KIND_MESSAGE,
51
52
  MOVED_TO_TAG,
52
53
  BARE_FILE_MANIFEST_ADDRESS,
53
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
@@ -1452,6 +1461,22 @@ const BARE_FILE_MANIFEST: Manifest = {
1452
1461
  body: { field: 'content' },
1453
1462
  },
1454
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
+ },
1455
1480
  },
1456
1481
  /*
1457
1482
  The manifest is the only place a consumer learns of any of these actions
@@ -1620,12 +1645,21 @@ export const FOLDER_ACTIONS_ADDRESS = 'spec:3.2'
1620
1645
  * is the bare file's own, so the created object is drawn the way every other
1621
1646
  * bare file is. Each consumer offers it only if it may sign `30840` and `1852`
1622
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`.
1623
1654
  */
1624
1655
  const FOLDER_CREATOR: ResolvedManifest = {
1625
1656
  manifest: {
1626
1657
  name: 'Folder',
1627
1658
  about: 'What every app may do in a Folder, whichever app made it.',
1628
- 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
+ },
1629
1663
  actions: [
1630
1664
  {
1631
1665
  id: 'create-file',
@@ -1644,12 +1678,87 @@ const FOLDER_CREATOR: ResolvedManifest = {
1644
1678
  required: ['title'],
1645
1679
  },
1646
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
+ },
1702
+ },
1647
1703
  ],
1648
1704
  },
1649
1705
  address: FOLDER_ACTIONS_ADDRESS,
1650
1706
  viaRecommendation: false,
1651
1707
  }
1652
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
+
1653
1762
  /**
1654
1763
  * The built-in manifest, named by the app that opens it — PRO-24.
1655
1764
  *
@@ -1907,10 +2016,19 @@ export async function resolveManifest(
1907
2016
  // A comment resolves through the built-in manifest as a bare file does, and
1908
2017
  // opens in the same app — the one that renders every file's conversation
1909
2018
  // is the one that can show a thread in it (FOL-38).
1910
- if (pointer.kind === KIND_BARE_FILE || pointer.kind === KIND_COMMENT) {
1911
- 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')
1912
2024
  return opener?.webTemplate ? bareFileOpenedBy(opener.manifest, opener.webTemplate) : bareFileManifest()
1913
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
+ }
1914
2032
  return throughCache(cache, `${pointer.kind}:${pointer.pubkey}`, () => resolveManifestUncached(pointer, query))
1915
2033
  }
1916
2034
 
@@ -2052,6 +2170,8 @@ function creatorsOrNone(kind: number, query: QueryFn, cache?: ProjectionCache):
2052
2170
  * ({@link FOLDER_CREATOR}, INT-12): no app owns a Folder (SPEC §3.2), so no
2053
2171
  * app's claim to create the same kind there outranks the specification's —
2054
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.
2055
2175
  */
2056
2176
  function borrowedFrom(kind: number, owner: ResolvedManifest, creators: readonly ResolvedManifest[]): ResolvedManifest[] {
2057
2177
  const builtIn = kind === KIND_CHANNEL_METADATA ? [FOLDER_CREATOR] : []
@@ -2100,10 +2220,12 @@ export async function resolveActingManifest(
2100
2220
  query: QueryFn,
2101
2221
  cache?: ProjectionCache,
2102
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
2103
2227
  const owner = await resolveManifest(pointer, query, cache)
2104
2228
  if (!owner || !declaredBy || declaredBy === owner.address) return owner
2105
- // A Folder's built-in needs no sweep, so a refused one must not cost it (INT-12).
2106
- if (pointer.kind === KIND_CHANNEL_METADATA && declaredBy === FOLDER_ACTIONS_ADDRESS) return FOLDER_CREATOR
2107
2229
  const creators = await creatorsOn(pointer.kind, query, cache)
2108
2230
  return borrowedFrom(pointer.kind, owner, creators).find((creator) => creator.address === declaredBy) ?? null
2109
2231
  }
@@ -3358,14 +3480,24 @@ export async function resolveForeignObject(
3358
3480
 
3359
3481
  // Beside the object's own read, not after it: the sweep is cached, and cold
3360
3482
  // it would otherwise add a round trip to every resolve that pays for it.
3361
- 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
+ ])
3362
3491
  const followUp = childChangeFilters(plan, answered)
3363
3492
  const assembled = assembleObject(plan, answered, followUp.length ? await queryChunked(followUp, query) : [])
3364
3493
  if (assembled.object.unreachable) return assembled.object
3365
3494
  if (options.archivedWith) await markArchivedParents([{ object: assembled.object, manifest: resolved.manifest }], query)
3366
- return withBorrowed(
3367
- withPeople(assembled, await (lookupPeople ?? peopleViaRelay(query))(peopleOf(assembled))),
3368
- 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,
3369
3501
  )
3370
3502
  }
3371
3503
 
@@ -3467,11 +3599,21 @@ export async function resolveForeignObjects(
3467
3599
  // Who else creates on each kind in the set (MAN-8): one sweep per kind, not
3468
3600
  // per object, read beside the objects themselves.
3469
3601
  const kinds = [...new Set(plans.map(({ plan }) => plan.pointer.kind))]
3470
- 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([
3471
3611
  queryChunked(filters, query),
3472
3612
  Promise.all(kinds.map((kind) => creatorsOrNone(kind, query, cache))),
3613
+ Promise.all(folders.map((folder) => folderFilesOf(folder, query, lookupPeople, cache))),
3473
3614
  ])
3474
3615
  const creatorsByKind = new Map(kinds.map((kind, i) => [kind, creatorLists[i]]))
3616
+ const filesByFolder = new Map(folders.map((folder, i) => [folder, fileLists[i]]))
3475
3617
 
3476
3618
  // Every card's children's changes in one more read for the whole set, not
3477
3619
  // one per card (MAN-7) — and none at all when no card has a fold to read.
@@ -3505,9 +3647,12 @@ export async function resolveForeignObjects(
3505
3647
  // it happened to be resolved beside.
3506
3648
  const own: People = {}
3507
3649
  for (const key of peopleOf(built)) if (key in people) own[key] = people[key]
3508
- results[reference] = withBorrowed(
3509
- withPeople(built, own),
3510
- 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,
3511
3656
  )
3512
3657
  }
3513
3658
  return results
@@ -3771,6 +3916,54 @@ export interface ArchiveReadOptions {
3771
3916
  * card would pay it every time (SHI-13's one request per tick).
3772
3917
  */
3773
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
3774
3967
  }
3775
3968
 
3776
3969
  /**
@@ -6347,6 +6540,12 @@ export async function resolveFolderContents(
6347
6540
  * Every other list wants the default.
6348
6541
  */
6349
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
6350
6549
  } = {},
6351
6550
  ): Promise<FolderContents> {
6352
6551
  // 1. The folder itself. Both kinds in one trip: the state is the model and
@@ -6385,7 +6584,9 @@ export async function resolveFolderContents(
6385
6584
  addresses: [...new Set(state.tags.filter((t) => t[0] === 'a' && t[1]).map((t) => t[1]))],
6386
6585
  placed: new Map<string, SignedEvent[]>(),
6387
6586
  }
6388
- : await addressesByContainment(folder, query)
6587
+ : options.listedOnly
6588
+ ? { addresses: [], placed: new Map<string, SignedEvent[]>() }
6589
+ : await addressesByContainment(folder, query)
6389
6590
 
6390
6591
  if (addresses.length === 0) {
6391
6592
  // Nothing listed, so no change query to ride on: the Folder's own archive
package/src/references.ts CHANGED
@@ -6,7 +6,8 @@
6
6
  * resolved object into a row, and typed text into the search tier — so Peek
7
7
  * and Ship draw the same rows from the same reads.
8
8
  *
9
- * A row is the type word and the current title; an issue is captioned with its
9
+ * A row is the type word, the current title and, when it has one, the file's
10
+ * summary (SPEC §6.12, SUM-7); an issue is captioned with its
10
11
  * project's title, and nothing names a Folder (Miky, 2026-10-03). Only what the
11
12
  * reader resolved is offered: an object the relay did not hand back to them is
12
13
  * never a row, so nothing unreadable is offered. An archived file is offered
@@ -32,12 +33,24 @@ import {
32
33
 
33
34
  const KIND_PROJECT = 30850
34
35
  const KIND_ISSUE = 30851
36
+ const KIND_DOCUMENT = 30842
35
37
 
36
- /** The kinds `[` offers as files, and the type word each draws as. */
38
+ /**
39
+ * The kinds `[` offers as files, and the type word each draws as. A Leaf page
40
+ * is offered in every app, beside topics, projects and issues (Miky, SUM-7
41
+ * kickoff, 2026-10-16).
42
+ */
37
43
  export const REFERENCE_FILE_TYPES: Readonly<Record<number, ReferenceType>> = {
38
44
  [KIND_PROJECT]: 'project',
39
45
  [KIND_ISSUE]: 'issue',
40
46
  [KIND_BARE_FILE]: 'topic',
47
+ [KIND_DOCUMENT]: 'document',
48
+ }
49
+
50
+ /** A file's summary as a row's second line: plain text, never a body declared into the slot. */
51
+ const summaryOf = (object: ForeignObject): string | undefined => {
52
+ const slot = object.slots.subtitle
53
+ return slot && !slot.format ? slot.value.replace(/\s+/g, ' ').trim() || undefined : undefined
41
54
  }
42
55
 
43
56
  const typeOf = (kind: number): ReferenceType | undefined => REFERENCE_FILE_TYPES[kind]
@@ -95,6 +108,7 @@ export async function fileCandidates(
95
108
  return files.map((o) => {
96
109
  const parent = o.kind === KIND_ISSUE && o.parentRef ? parents.get(o.parentRef) : undefined
97
110
  const ref = refOf(o)
111
+ const summary = summaryOf(o)
98
112
  return {
99
113
  id: o.address,
100
114
  uri: fileReference(o.address),
@@ -103,6 +117,7 @@ export async function fileCandidates(
103
117
  title: o.slots.title!.value,
104
118
  // An issue reads "CON-33 · Conversation standard": the ref first, so a hit by ref shows it (Miky, 2026-10-05).
105
119
  caption: [ref, parent?.slots.title?.value].filter(Boolean).join(' · '),
120
+ ...(summary ? { summary } : {}),
106
121
  tier,
107
122
  ...(ref ? { search: ref } : {}),
108
123
  ...(isClosedStatus(o.slots.status) ? { closed: true } : {}),