@estiva-app/interop 0.43.0 → 0.45.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
+ * Every object in a set of events the caller already holds, projected — PER-21.
3151
+ * **No requests.**
3152
+ *
3153
+ * {@link resolveForeignObjects} reads each object's own filters, which is the
3154
+ * right price for a sidebar holding a few dozen and the wrong one for a reader
3155
+ * that wants a whole app's workspace: interop's own measurement put 110 issues
3156
+ * at 20 POSTs and a megabyte (FOL-50), and estiva-agent re-reads its workspace
3157
+ * on every command. A reader like that can fetch the roots and the app's change
3158
+ * kind in bulk — a few paged queries — and hand them here.
3159
+ *
3160
+ * Each root of a kind the manifest projects becomes exactly the object
3161
+ * `resolveForeignObject` builds for it: the same fold (`records`, §6.2–6.3),
3162
+ * the same archive read, the same slots, meta, parent and actions. What is
3163
+ * deliberately absent is everything that would need another read:
3164
+ *
3165
+ * - **`comments` is `[]`.** A comment is a separate event in a Folder, and
3166
+ * which comments the caller fetched says nothing about which it did not.
3167
+ * Read conversations with {@link conversationsOf} and {@link threadsOf}.
3168
+ * - **No `children`.** A `list` slot is containment, and the children are
3169
+ * other objects in the same answer: nest them by `parentRef`.
3170
+ * - **No `people`, and no borrowed actions** (MAN-8) — both are reads.
3171
+ *
3172
+ * - **No archive inherited from a parent.** `archived` is the object's own
3173
+ * change; `resolveForeignObjects`'s `archivedWith` reads the parents' too,
3174
+ * and here the parent is simply another object in the answer, whose
3175
+ * `archived` the consumer can read by `parentRef`.
3176
+ *
3177
+ * Two versions of one root (a replay, two relays) collapse by NIP-01's rule,
3178
+ * as the relay's own replacement does: later `created_at`, then the lower id.
3179
+ * Objects come back in no particular order; sort them as the consumer draws.
3180
+ *
3181
+ * Linear in the events: the changes are grouped by target once, so a
3182
+ * workspace of hundreds of roots does not rescan thousands of changes per root.
3183
+ */
3184
+ export function projectEvents(
3185
+ events: readonly SignedEvent[],
3186
+ /**
3187
+ * The manifest each root is read through, **per author** — what
3188
+ * {@link resolveManifest} answered for that root's `kind:pubkey`, from the
3189
+ * caller's own resolution (a {@link ProjectionCache} keeps it to one read per
3190
+ * author). Per author, not one for all, because that is the trust anchor
3191
+ * `resolveForeignObject` keeps: an object is drawn by the app *its author*
3192
+ * recommended, and `viaRecommendation` says whether they did. A root this
3193
+ * answers `undefined` for, or whose kind its manifest does not project, is
3194
+ * not an object here.
3195
+ */
3196
+ manifestFor: (pointer: AddressPointer) => ResolvedManifest | undefined,
3197
+ ): ForeignObject[] {
3198
+ const roots = new Map<string, { root: SignedEvent; pointer: AddressPointer; resolved: ResolvedManifest }>()
3199
+ for (const event of events) {
3200
+ const identifier = tagValue(event, 'd')
3201
+ if (identifier === undefined) continue
3202
+ const pointer: AddressPointer = { kind: event.kind, pubkey: event.pubkey, identifier, relays: [] }
3203
+ const resolved = manifestFor(pointer)
3204
+ if (!resolved?.manifest.projections?.[String(event.kind)]) continue
3205
+ const address = `${event.kind}:${event.pubkey}:${identifier}`
3206
+ const held = roots.get(address)?.root
3207
+ if (!held || event.created_at > held.created_at || (event.created_at === held.created_at && event.id < held.id)) {
3208
+ roots.set(address, { root: event, pointer, resolved })
3209
+ }
3210
+ }
3211
+
3212
+ // Each helper still applies its own kind and target test to what it is
3213
+ // handed; grouping by target once only narrows what it has to look at.
3214
+ const grouped = new Map<string, Map<string, SignedEvent[]>>()
3215
+ const byTarget = (targetTag: string) => {
3216
+ let byAddress = grouped.get(targetTag)
3217
+ if (byAddress) return byAddress
3218
+ byAddress = new Map()
3219
+ for (const event of events) {
3220
+ const target = tagValue(event, targetTag)
3221
+ if (target === undefined || !roots.has(target)) continue
3222
+ const list = byAddress.get(target)
3223
+ if (list) list.push(event)
3224
+ else byAddress.set(target, [event])
3225
+ }
3226
+ grouped.set(targetTag, byAddress)
3227
+ return byAddress
3228
+ }
3229
+
3230
+ return [...roots].map(([address, { root, pointer, resolved }]) => {
3231
+ const { manifest } = resolved
3232
+ const archiveRule = archiveRuleOf(manifest)
3233
+ return buildObject({
3234
+ root,
3235
+ pointer,
3236
+ manifest,
3237
+ projection: manifest.projections![String(root.kind)],
3238
+ folded: foldOf(byTarget(foldRuleOf(manifest).targetTag).get(address) ?? [], address, manifest),
3239
+ viaRecommendation: resolved.viaRecommendation,
3240
+ webTemplate: resolved.webTemplate,
3241
+ archived: archiveOf(byTarget(archiveRule.targetTag).get(address) ?? [], address, archiveRule),
3242
+ })
3243
+ })
3244
+ }
3245
+
3093
3246
  /**
3094
3247
  * The parent each file sits under, and nothing else — FOL-50.
3095
3248
  *