@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/CHANGELOG.md +80 -0
- package/README.md +10 -0
- package/dist/folders.d.ts +4 -0
- package/dist/folders.d.ts.map +1 -1
- package/dist/folders.js +4 -0
- package/dist/folders.js.map +1 -1
- package/dist/index.d.ts +1 -1
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +1 -1
- package/dist/index.js.map +1 -1
- package/dist/projection.d.ts +60 -1
- package/dist/projection.d.ts.map +1 -1
- package/dist/projection.js +290 -16
- package/dist/projection.js.map +1 -1
- package/package.json +1 -1
- package/src/folders.ts +4 -0
- package/src/index.ts +2 -0
- package/src/projection.ts +352 -20
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@estiva-app/interop",
|
|
3
|
-
"version": "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: {
|
|
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
|
|
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
|
-
|
|
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
|
-
|
|
1871
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
|
3244
|
-
|
|
3245
|
-
|
|
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
|
-
|
|
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] =
|
|
3386
|
-
|
|
3387
|
-
|
|
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
|
-
/**
|
|
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
|
-
:
|
|
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
|