@estiva-app/interop 0.42.0 → 0.44.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 +57 -0
- package/README.md +20 -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 +46 -6
- package/dist/projection.d.ts.map +1 -1
- package/dist/projection.js +154 -8
- package/dist/projection.js.map +1 -1
- package/package.json +1 -1
- package/src/index.ts +1 -0
- package/src/projection.ts +170 -10
package/src/projection.ts
CHANGED
|
@@ -901,10 +901,26 @@ interface Projection {
|
|
|
901
901
|
* while a menu draws. Anything else reads as "this app does not say" (§7.9).
|
|
902
902
|
*/
|
|
903
903
|
function nounOf(projection: Projection): { noun?: string } {
|
|
904
|
-
const noun =
|
|
904
|
+
const noun = wordOf(projection.noun)
|
|
905
905
|
return noun ? { noun } : {}
|
|
906
906
|
}
|
|
907
907
|
|
|
908
|
+
const WORD_MAX = 32
|
|
909
|
+
|
|
910
|
+
/**
|
|
911
|
+
* A manifest's word, trimmed — or undefined unless it is a short name: at most
|
|
912
|
+
* {@link WORD_MAX} letters, digits, spaces, hyphens and apostrophes.
|
|
913
|
+
*
|
|
914
|
+
* A consumer drops a noun into its own sentences ("Delete this issue?"), and a
|
|
915
|
+
* bare file's noun and name come from whichever manifest declares the aspect
|
|
916
|
+
* newest (PRO-24 review). Capped, a hostile manifest can put a wrong word
|
|
917
|
+
* there, but not a sentence of its own that reads as the consumer's.
|
|
918
|
+
*/
|
|
919
|
+
function wordOf(value: unknown): string | undefined {
|
|
920
|
+
const word = typeof value === 'string' ? value.trim() : ''
|
|
921
|
+
return word.length <= WORD_MAX && /^[\p{L}\p{N}][\p{L}\p{N}\p{M} '’-]*$/u.test(word) ? word : undefined
|
|
922
|
+
}
|
|
923
|
+
|
|
908
924
|
interface Manifest {
|
|
909
925
|
name?: string
|
|
910
926
|
about?: string
|
|
@@ -926,6 +942,17 @@ interface Manifest {
|
|
|
926
942
|
* where a link to it should land. Nothing else consults it yet.
|
|
927
943
|
*/
|
|
928
944
|
aspect?: string
|
|
945
|
+
/**
|
|
946
|
+
* What this app calls a file nobody owns when it opens one, lower case and
|
|
947
|
+
* singular: Peek's is "topic" (PRO-24). Read only beside `aspect`, from the
|
|
948
|
+
* same manifest a bare file's link comes from, and resolved onto that bare
|
|
949
|
+
* file's {@link ForeignObject.noun}.
|
|
950
|
+
*
|
|
951
|
+
* The opener's word and not the protocol's, Miky's call on 2026-10-02: a
|
|
952
|
+
* company running its own conversation app calls these whatever its people
|
|
953
|
+
* call them, and the specification never has to pick.
|
|
954
|
+
*/
|
|
955
|
+
fileNoun?: string
|
|
929
956
|
}
|
|
930
957
|
|
|
931
958
|
/**
|
|
@@ -1243,10 +1270,11 @@ export interface ResolvedManifest {
|
|
|
1243
1270
|
* folds the way an issue's `project` field does — a root tag seeds the value,
|
|
1244
1271
|
* a change event overrides it.
|
|
1245
1272
|
*
|
|
1246
|
-
*
|
|
1247
|
-
* name
|
|
1248
|
-
*
|
|
1249
|
-
*
|
|
1273
|
+
* What a person reads on it comes from that app too (PRO-24). Its `appName` is
|
|
1274
|
+
* the opener's name, because that is where its link goes — "Open in File" told
|
|
1275
|
+
* nobody anything. Its `noun` is the opener's `fileNoun`, so Peek's topic says
|
|
1276
|
+
* "topic". `name` below is "File" only for the file nothing can open, where a
|
|
1277
|
+
* consumer has no app to print.
|
|
1250
1278
|
*/
|
|
1251
1279
|
export const KIND_BARE_FILE = 30840
|
|
1252
1280
|
|
|
@@ -1323,9 +1351,14 @@ const BARE_FILE_MANIFEST: Manifest = {
|
|
|
1323
1351
|
null, and a pasted thread link stayed a plain link. Drawn the way Peek
|
|
1324
1352
|
draws a `kind:9` — the author as the title, the text as the body — so a
|
|
1325
1353
|
consumer that already has a `message` widget draws a comment with it.
|
|
1354
|
+
|
|
1355
|
+
Its noun is the protocol's own word, unlike a bare file's (PRO-24, Miky
|
|
1356
|
+
2026-10-02): NIP-22 and SPEC §6.4 already call it a comment, so there is
|
|
1357
|
+
no app whose word it would be.
|
|
1326
1358
|
*/
|
|
1327
1359
|
[String(KIND_COMMENT)]: {
|
|
1328
1360
|
widget: ['message', 'card'],
|
|
1361
|
+
noun: 'comment',
|
|
1329
1362
|
slots: {
|
|
1330
1363
|
title: { field: 'pubkey', as: 'pubkey' },
|
|
1331
1364
|
body: { field: 'content' },
|
|
@@ -1430,6 +1463,31 @@ function bareFileManifest(): ResolvedManifest {
|
|
|
1430
1463
|
return { manifest: BARE_FILE_MANIFEST, address: BARE_FILE_MANIFEST_ADDRESS, viaRecommendation: false }
|
|
1431
1464
|
}
|
|
1432
1465
|
|
|
1466
|
+
/**
|
|
1467
|
+
* The built-in manifest, named by the app that opens it — PRO-24.
|
|
1468
|
+
*
|
|
1469
|
+
* Only the name and the bare file's noun are the opener's. The address stays
|
|
1470
|
+
* the specification's, and every rule — fold, slots, actions — stays this
|
|
1471
|
+
* runtime's, so a published manifest still cannot change how a bare file
|
|
1472
|
+
* behaves; it can only say what it is called where it opens. A comment takes
|
|
1473
|
+
* the name (it opens in the same app) and not the noun, which is the file's.
|
|
1474
|
+
*/
|
|
1475
|
+
function bareFileOpenedBy(opener: Manifest, template: string): ResolvedManifest {
|
|
1476
|
+
const name = wordOf(opener.name) ?? BARE_FILE_MANIFEST.name
|
|
1477
|
+
const fileNoun = wordOf(opener.fileNoun)
|
|
1478
|
+
const projections = BARE_FILE_MANIFEST.projections!
|
|
1479
|
+
const bare = String(KIND_BARE_FILE)
|
|
1480
|
+
return {
|
|
1481
|
+
...bareFileManifest(),
|
|
1482
|
+
manifest: {
|
|
1483
|
+
...BARE_FILE_MANIFEST,
|
|
1484
|
+
name,
|
|
1485
|
+
...(fileNoun ? { projections: { ...projections, [bare]: { ...projections[bare], noun: fileNoun } } } : {}),
|
|
1486
|
+
},
|
|
1487
|
+
webTemplate: template,
|
|
1488
|
+
}
|
|
1489
|
+
}
|
|
1490
|
+
|
|
1433
1491
|
/**
|
|
1434
1492
|
* How many handler events a sweep of the relay asks for.
|
|
1435
1493
|
*
|
|
@@ -1662,9 +1720,7 @@ export async function resolveManifest(
|
|
|
1662
1720
|
// is the one that can show a thread in it (FOL-38).
|
|
1663
1721
|
if (pointer.kind === KIND_BARE_FILE || pointer.kind === KIND_COMMENT) {
|
|
1664
1722
|
const opener = await resolveAspectApp('conversation', query, cache, pointer.kind === KIND_COMMENT ? 'nevent' : 'naddr')
|
|
1665
|
-
return opener?.webTemplate
|
|
1666
|
-
? { ...bareFileManifest(), webTemplate: opener.webTemplate }
|
|
1667
|
-
: bareFileManifest()
|
|
1723
|
+
return opener?.webTemplate ? bareFileOpenedBy(opener.manifest, opener.webTemplate) : bareFileManifest()
|
|
1668
1724
|
}
|
|
1669
1725
|
return throughCache(cache, `${pointer.kind}:${pointer.pubkey}`, () => resolveManifestUncached(pointer, query))
|
|
1670
1726
|
}
|
|
@@ -2680,8 +2736,8 @@ export interface ForeignObject {
|
|
|
2680
2736
|
* issue", a confirm's "Delete this project?". Without it Peek called a Ship
|
|
2681
2737
|
* issue a topic, because the only way to know better was to check the kind
|
|
2682
2738
|
* number, which is the check a manifest exists to replace. Absent when the
|
|
2683
|
-
* owner declares none
|
|
2684
|
-
*
|
|
2739
|
+
* owner declares none. A bare file's is the `fileNoun` of the app that
|
|
2740
|
+
* opens it (PRO-24), and absent when that app declares none.
|
|
2685
2741
|
*/
|
|
2686
2742
|
noun?: string
|
|
2687
2743
|
/** Named single slots: title, subtitle, status. */
|
|
@@ -3090,6 +3146,103 @@ export async function resolveForeignObjects(
|
|
|
3090
3146
|
return results
|
|
3091
3147
|
}
|
|
3092
3148
|
|
|
3149
|
+
/**
|
|
3150
|
+
* The parent each file sits under, and nothing else — FOL-50.
|
|
3151
|
+
*
|
|
3152
|
+
* {@link resolveForeignObjects} answers this on the way to a whole object, and
|
|
3153
|
+
* for a caller that needs only the parent that is the wrong price: it reads
|
|
3154
|
+
* every object's comments and children too. Peek's Folder dots place an
|
|
3155
|
+
* issue's talk by its project, and on production on 2026-09-30 the 110 issues
|
|
3156
|
+
* the dots name cost 20 POSTs and a megabyte that way. This asks for the roots,
|
|
3157
|
+
* and for the changes only of a kind whose app declares a `movedBy` — a filter
|
|
3158
|
+
* per 100 roots and one per movable file, so a POST per ~120 files: one for the
|
|
3159
|
+
* set the dots held on production.
|
|
3160
|
+
*
|
|
3161
|
+
* Folded by the rule the card and the listing use (`parentRefOf`), so a moved
|
|
3162
|
+
* issue is under the project it was moved to here as everywhere else, and a
|
|
3163
|
+
* file is answered only when its app draws its kind — as it is by the object
|
|
3164
|
+
* readers.
|
|
3165
|
+
*
|
|
3166
|
+
* Keyed by the reference as given: the parent's address, or `null` for a file
|
|
3167
|
+
* at the top. **Absent** when there is nothing to tell — not an address, no
|
|
3168
|
+
* manifest, or a root this reader cannot see — because "at the top" and
|
|
3169
|
+
* "unknown" are different sentences.
|
|
3170
|
+
*
|
|
3171
|
+
* **A failed read rejects the whole call**, as {@link resolveForeignObjects}
|
|
3172
|
+
* does.
|
|
3173
|
+
*/
|
|
3174
|
+
export async function resolveParents(
|
|
3175
|
+
references: readonly string[],
|
|
3176
|
+
query: QueryFn,
|
|
3177
|
+
/** See {@link ProjectionCache}. Omitting it still reads each app's manifest once per call. */
|
|
3178
|
+
cache?: ProjectionCache,
|
|
3179
|
+
): Promise<Record<string, string | null>> {
|
|
3180
|
+
const results: Record<string, string | null> = {}
|
|
3181
|
+
const asked: { reference: string; pointer: AddressPointer }[] = []
|
|
3182
|
+
for (const reference of new Set(references)) {
|
|
3183
|
+
const pointer = addressPointerOf(reference)
|
|
3184
|
+
if (pointer) asked.push({ reference, pointer })
|
|
3185
|
+
}
|
|
3186
|
+
if (asked.length === 0) return results
|
|
3187
|
+
|
|
3188
|
+
const byApp = new Map<string, AddressPointer>()
|
|
3189
|
+
for (const { pointer } of asked) byApp.set(manifestKeyOf(pointer), pointer)
|
|
3190
|
+
const manifests = new Map<string, Manifest>()
|
|
3191
|
+
await Promise.all(
|
|
3192
|
+
[...byApp].map(async ([key, pointer]) => {
|
|
3193
|
+
const resolved = await resolveManifest(pointer, query, cache)
|
|
3194
|
+
if (resolved) manifests.set(key, resolved.manifest)
|
|
3195
|
+
}),
|
|
3196
|
+
)
|
|
3197
|
+
|
|
3198
|
+
// The roots by author and kind, the one filter shape that names many; the
|
|
3199
|
+
// moves by the app's change shape, only where the kind can be moved at all.
|
|
3200
|
+
const roots = new Map<string, { kind: number; pubkey: string; identifiers: Set<string> }>()
|
|
3201
|
+
const moves = new Map<string, { rule: RecordsRule; addresses: Set<string> }>()
|
|
3202
|
+
for (const { pointer } of asked) {
|
|
3203
|
+
const manifest = manifests.get(manifestKeyOf(pointer))
|
|
3204
|
+
if (!manifest?.projections?.[String(pointer.kind)]) continue
|
|
3205
|
+
const group = `${pointer.kind}:${pointer.pubkey}`
|
|
3206
|
+
const held = roots.get(group) ?? { kind: pointer.kind, pubkey: pointer.pubkey, identifiers: new Set<string>() }
|
|
3207
|
+
held.identifiers.add(pointer.identifier)
|
|
3208
|
+
roots.set(group, held)
|
|
3209
|
+
if (!manifest.records || !movedByOf(manifest, pointer.kind)) continue
|
|
3210
|
+
const shape = `${manifest.records.changeKind}:${manifest.records.targetTag}`
|
|
3211
|
+
const movable = moves.get(shape) ?? { rule: manifest.records, addresses: new Set<string>() }
|
|
3212
|
+
movable.addresses.add(pointerToAddress(pointer))
|
|
3213
|
+
moves.set(shape, movable)
|
|
3214
|
+
}
|
|
3215
|
+
const filters: Record<string, unknown>[] = []
|
|
3216
|
+
for (const { kind, pubkey, identifiers } of roots.values()) {
|
|
3217
|
+
const all = [...identifiers]
|
|
3218
|
+
for (let start = 0; start < all.length; start += PARENT_ROOT_GROUP) {
|
|
3219
|
+
const group = all.slice(start, start + PARENT_ROOT_GROUP)
|
|
3220
|
+
filters.push({ kinds: [kind], authors: [pubkey], '#d': group, limit: group.length })
|
|
3221
|
+
}
|
|
3222
|
+
}
|
|
3223
|
+
// One filter per file, with the object reader's own limit: a group sharing a
|
|
3224
|
+
// page could push an old move out of it behind newer statuses and edits, and
|
|
3225
|
+
// this would then disagree with `parentRef`.
|
|
3226
|
+
for (const { rule, addresses } of moves.values()) {
|
|
3227
|
+
for (const address of addresses) filters.push({ kinds: [rule.changeKind], [`#${rule.targetTag}`]: [address], limit: 500 })
|
|
3228
|
+
}
|
|
3229
|
+
if (filters.length === 0) return results
|
|
3230
|
+
const events = await queryChunked(filters, query)
|
|
3231
|
+
|
|
3232
|
+
for (const { reference, pointer } of asked) {
|
|
3233
|
+
const manifest = manifests.get(manifestKeyOf(pointer))
|
|
3234
|
+
if (!manifest?.projections?.[String(pointer.kind)]) continue
|
|
3235
|
+
const root = events
|
|
3236
|
+
.filter((e) => e.kind === pointer.kind && e.pubkey === pointer.pubkey && tagValue(e, 'd') === pointer.identifier)
|
|
3237
|
+
.sort(byOrder)
|
|
3238
|
+
.at(-1)
|
|
3239
|
+
if (!root) continue
|
|
3240
|
+
const folded = foldOf(events, pointerToAddress(pointer), manifest)
|
|
3241
|
+
results[reference] = parentRefOf(manifest, pointer.kind, root, folded) ?? null
|
|
3242
|
+
}
|
|
3243
|
+
return results
|
|
3244
|
+
}
|
|
3245
|
+
|
|
3093
3246
|
/** What {@link resolveForeignObject} and {@link resolveForeignObjects} may read beyond the file itself. */
|
|
3094
3247
|
export interface ArchiveReadOptions {
|
|
3095
3248
|
/**
|
|
@@ -3154,6 +3307,13 @@ function relatedRuleOf(manifest: Pick<Manifest, 'records' | 'projections'> | und
|
|
|
3154
3307
|
*/
|
|
3155
3308
|
const ARCHIVE_READ_GROUP = 25
|
|
3156
3309
|
|
|
3310
|
+
/**
|
|
3311
|
+
* Identifiers per root filter in {@link resolveParents}. A root read answers
|
|
3312
|
+
* one event per identifier, so it needs no room kept for a page — only a `#d`
|
|
3313
|
+
* list short enough for a relay to take.
|
|
3314
|
+
*/
|
|
3315
|
+
const PARENT_ROOT_GROUP = 100
|
|
3316
|
+
|
|
3157
3317
|
/**
|
|
3158
3318
|
* The filters asking for every change naming these addresses, once per distinct
|
|
3159
3319
|
* change shape among `rules` — SPEC's alone unless an app writes its own.
|