@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/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 = typeof projection.noun === 'string' ? projection.noun.trim() : ''
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
- * `name` is what a consumer prints where it would print the owning app's
1247
- * name. "File" rather than "Bare file", because that word is for the
1248
- * specification and a person looking at a card next to a Ship issue is better
1249
- * served by the plain noun.
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, and for the bare file, whose manifest lives here: a
2684
- * consumer says its own word for a file nobody owns.
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.