@estiva-app/interop 0.65.0 → 0.66.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/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@estiva-app/interop",
3
- "version": "0.65.0",
3
+ "version": "0.66.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
@@ -36,6 +36,7 @@ export {
36
36
  resolveFolderProject,
37
37
  resolveFolderContents,
38
38
  listFolders,
39
+ listFolderRecords,
39
40
  topLevelFolders,
40
41
  ARCHIVED_FIELD,
41
42
  SUMMARY_FIELD,
@@ -93,6 +94,7 @@ export {
93
94
  type FolderProject,
94
95
  type FolderContents,
95
96
  type FolderSummary,
97
+ type FolderRecord,
96
98
  type ResolvedSlot,
97
99
  type ResolvedAction,
98
100
  type ActionFormField,
package/src/projection.ts CHANGED
@@ -4031,21 +4031,41 @@ async function markArchivedParents(
4031
4031
  query: QueryFn,
4032
4032
  cache?: ProjectionCache,
4033
4033
  ): Promise<void> {
4034
- type Walk = { object: ForeignObject; manifest?: Manifest; at: string; seen: Set<string> }
4035
- // An `naddr` parent names the same file as its plain address (FEE-2), and
4036
- // only the plain one is what a change's target tag and `with` carry.
4037
- const plain = (reference: string) => {
4038
- const pointer = addressPointerOf(reference)
4039
- return pointer ? `${pointer.kind}:${pointer.pubkey}:${pointer.identifier}` : undefined
4040
- }
4041
- let walking: Walk[] = entries
4042
- .filter(({ object: o }) => !o.unreachable && !o.archived && o.parentRef && plain(o.parentRef))
4043
- .map(({ object, manifest }) => ({
4044
- object,
4045
- manifest,
4046
- at: plain(object.parentRef!)!,
4047
- seen: new Set([plain(object.address ?? '') ?? '']),
4048
- }))
4034
+ await walkArchivedAbove(
4035
+ entries
4036
+ .filter(({ object: o }) => !o.unreachable && !o.archived && o.parentRef && plainAddress(o.parentRef))
4037
+ .map(({ object, manifest }) => ({
4038
+ manifest,
4039
+ at: plainAddress(object.parentRef!)!,
4040
+ seen: new Set([plainAddress(object.address ?? '') ?? '']),
4041
+ mark: (archive: Archive) => {
4042
+ object.archived = archive
4043
+ },
4044
+ })),
4045
+ query,
4046
+ cache,
4047
+ )
4048
+ }
4049
+
4050
+ // An `naddr` parent names the same file as its plain address (FEE-2), and
4051
+ // only the plain one is what a change's target tag and `with` carry.
4052
+ function plainAddress(reference: string) {
4053
+ const pointer = addressPointerOf(reference)
4054
+ return pointer ? `${pointer.kind}:${pointer.pubkey}:${pointer.identifier}` : undefined
4055
+ }
4056
+
4057
+ /**
4058
+ * {@link markArchivedParents}'s walk, from `at` upwards: `mark` is called with
4059
+ * the closest archived file's archive, `with` its address, and not at all when
4060
+ * none is. `manifest` is the app of the file below `at`, `seen` what is below.
4061
+ */
4062
+ async function walkArchivedAbove(
4063
+ starts: { at: string; manifest?: Manifest; seen: Set<string>; mark: (archive: Archive) => void }[],
4064
+ query: QueryFn,
4065
+ cache?: ProjectionCache,
4066
+ ): Promise<void> {
4067
+ type Walk = (typeof starts)[number]
4068
+ let walking: Walk[] = starts
4049
4069
  while (walking.length) {
4050
4070
  // Each child's ancestor is read by that child's app when it draws the
4051
4071
  // ancestor's kind — a project is Ship's as its issue is — and by the
@@ -4057,18 +4077,26 @@ async function markArchivedParents(
4057
4077
  if (own && !drawnBy.includes(own)) drawnBy.push(own)
4058
4078
  return { walk, key: `${walk.at}|${own ? drawnBy.indexOf(own) : ''}`, own }
4059
4079
  })
4060
- // A manifest that cannot be read is an ancestor read by SPEC's rule with no
4061
- // parent: the walk ends there rather than the whole open failing.
4080
+ // A level whose manifest cannot be read ends the walk, its own archive
4081
+ // uncounted (SPEC §6.5): which change archives it is the manifest's to say.
4082
+ // A bare file's is a constant, so a refused opener sweep never ends it.
4062
4083
  const theirOwn = new Map<string, Promise<Manifest | undefined>>()
4063
- const ancestors = await Promise.all(
4084
+ const resolved = await Promise.all(
4064
4085
  [...new Map(keyed.map((entry) => [entry.key, entry])).values()].map(async ({ key, walk, own }) => {
4065
4086
  const pointer = addressPointerOf(walk.at)!
4066
4087
  if (!own && !theirOwn.has(walk.at)) {
4067
- theirOwn.set(walk.at, resolveManifest(pointer, query, cache).then((r) => r?.manifest, () => undefined))
4088
+ theirOwn.set(
4089
+ walk.at,
4090
+ resolveManifest(pointer, query, cache).then(
4091
+ (r) => r?.manifest,
4092
+ () => (pointer.kind === KIND_BARE_FILE ? bareFileManifest().manifest : undefined),
4093
+ ),
4094
+ )
4068
4095
  }
4069
4096
  return { key, address: walk.at, pointer, manifest: own ?? (await theirOwn.get(walk.at)) }
4070
4097
  }),
4071
4098
  )
4099
+ const ancestors = resolved.filter((a): a is typeof a & { manifest: Manifest } => !!a.manifest)
4072
4100
  const rules = ancestors.map(({ manifest }) => archiveRuleOf(manifest))
4073
4101
  const addresses = [...new Set(ancestors.map(({ address }) => address))]
4074
4102
  const roots = new Map<string, { kinds: number[]; authors: string[]; '#d': string[] }>()
@@ -4108,11 +4136,11 @@ async function markArchivedParents(
4108
4136
  const found = read.get(key)
4109
4137
  if (!found) continue
4110
4138
  if (found.archive) {
4111
- walk.object.archived = { ...found.archive, with: walk.at }
4139
+ walk.mark({ ...found.archive, with: walk.at })
4112
4140
  continue
4113
4141
  }
4114
4142
  walk.seen.add(walk.at)
4115
- const parent = found.parent && plain(found.parent)
4143
+ const parent = found.parent && plainAddress(found.parent)
4116
4144
  if (parent && !walk.seen.has(parent)) {
4117
4145
  next.push({ ...walk, manifest: found.manifest, at: parent })
4118
4146
  }
@@ -4121,16 +4149,6 @@ async function markArchivedParents(
4121
4149
  }
4122
4150
  }
4123
4151
 
4124
- /**
4125
- * The rule another file's archive is read by, from an app known to hold it:
4126
- * that app's own, when it draws the file's kind — an issue's project is Ship's,
4127
- * a hive's inspection the hive log's — and SPEC's otherwise.
4128
- */
4129
- function relatedRuleOf(manifest: Pick<Manifest, 'records' | 'projections'> | undefined, address: string): RecordsRule {
4130
- const kind = addressPointerOf(address)?.kind
4131
- return manifest && kind !== undefined && manifest.projections?.[String(kind)] ? archiveRuleOf(manifest) : ARCHIVE_RULE
4132
- }
4133
-
4134
4152
  /**
4135
4153
  * Addresses per filter when reading archive changes. A filter's `limit` caps
4136
4154
  * every change naming its addresses — titles, statuses, moves — not only the
@@ -6303,6 +6321,63 @@ export interface FolderContents extends FolderSummary {
6303
6321
  * This asks for folders by kind.
6304
6322
  */
6305
6323
  export async function listFolders(query: QueryFn): Promise<FolderSummary[]> {
6324
+ const { events, byId } = await readFolderRecords(query)
6325
+ /*
6326
+ A folder listed in another folder's state is a file there. Read off the
6327
+ states already in hand: an `a` naming a `kind:39000` is a channel, and its
6328
+ `d` is the folder's id. Both `KIND_CHANNEL` and the state's own `d` are
6329
+ uuids, so no address has to be built to compare them.
6330
+ */
6331
+ const listedIn = new Map<string, string[]>()
6332
+ for (const event of events) {
6333
+ if (event.kind !== KIND_FOLDER_STATE) continue
6334
+ const container = tagValue(event, 'd')
6335
+ if (!container) continue
6336
+ for (const tag of event.tags) {
6337
+ if (tag[0] !== 'a' || !tag[1]) continue
6338
+ const [kind, , identifier] = tag[1].split(':')
6339
+ if (Number(kind) !== KIND_CHANNEL || !identifier || identifier === container) continue
6340
+ const containers: string[] = listedIn.get(identifier) ?? []
6341
+ if (!containers.includes(container)) containers.push(container)
6342
+ listedIn.set(identifier, containers)
6343
+ }
6344
+ }
6345
+ const { recordsOf, archives, rootOf } = await placeRecordChannels(events, byId, listedIn, query)
6346
+ for (const [id, containers] of listedIn) {
6347
+ const folder = byId.get(id)
6348
+ if (folder) folder.listedIn = containers
6349
+ }
6350
+ markArchivedFolders(byId, recordsOf, archives, rootOf)
6351
+ return [...byId.values()].sort(byFolderName)
6352
+ }
6353
+
6354
+ /** A Folder as its own records say it: a {@link FolderSummary} before anything is read about the files Folders list. */
6355
+ export type FolderRecord = Omit<FolderSummary, 'listedIn' | 'archived'>
6356
+
6357
+ /**
6358
+ * Every Folder this identity can see, from the Folders' own records only — one
6359
+ * request: the name, privacy and admins (§3.2), the state's list and the
6360
+ * channel's address, as {@link listFolders} gives them.
6361
+ *
6362
+ * **Without `listedIn` and `archived`**, which are what {@link listFolders}
6363
+ * pays for: placing a record's channel and reading archives fetches every
6364
+ * change to every file a Folder lists, and a text save is a whole document.
6365
+ * Measured as the agent on production 2026-10-26: 22.9 MB and 112 s, of which
6366
+ * the `archived` changes it looks for were 44 KB; the Folders' records were
6367
+ * 66 KB in 0.7 s. So this is for finding a Folder by its name or id (the
6368
+ * agent's `file create`), never for a sidebar, which must leave archived and
6369
+ * nested Folders out. The full cost goes when a file's text moves out of its
6370
+ * change log (record a-files-type-is-a-shared-meaning-any-app-extends).
6371
+ */
6372
+ export async function listFolderRecords(query: QueryFn): Promise<FolderRecord[]> {
6373
+ const { byId } = await readFolderRecords(query)
6374
+ return [...byId.values()].sort(byFolderName)
6375
+ }
6376
+
6377
+ const byFolderName = (a: FolderRecord, b: FolderRecord) => (a.name ?? a.id).localeCompare(b.name ?? b.id)
6378
+
6379
+ /** The Folders' own records, read in one request, as summaries without `listedIn` and `archived`. */
6380
+ async function readFolderRecords(query: QueryFn): Promise<{ events: SignedEvent[]; byId: Map<string, FolderSummary> }> {
6306
6381
  const events = await query([
6307
6382
  { kinds: [KIND_FOLDER_STATE], limit: 500 },
6308
6383
  { kinds: [KIND_CHANNEL], limit: 500 },
@@ -6337,33 +6412,7 @@ export async function listFolders(query: QueryFn): Promise<FolderSummary[]> {
6337
6412
  if (admins.length) folder.admins = admins
6338
6413
  folder.channel = pointerToAddress({ kind: KIND_CHANNEL, pubkey: channel.pubkey, identifier: id, relays: [] })
6339
6414
  }
6340
- /*
6341
- A folder listed in another folder's state is a file there. Read off the
6342
- states already in hand: an `a` naming a `kind:39000` is a channel, and its
6343
- `d` is the folder's id. Both `KIND_CHANNEL` and the state's own `d` are
6344
- uuids, so no address has to be built to compare them.
6345
- */
6346
- const listedIn = new Map<string, string[]>()
6347
- for (const event of events) {
6348
- if (event.kind !== KIND_FOLDER_STATE) continue
6349
- const container = tagValue(event, 'd')
6350
- if (!container) continue
6351
- for (const tag of event.tags) {
6352
- if (tag[0] !== 'a' || !tag[1]) continue
6353
- const [kind, , identifier] = tag[1].split(':')
6354
- if (Number(kind) !== KIND_CHANNEL || !identifier || identifier === container) continue
6355
- const containers: string[] = listedIn.get(identifier) ?? []
6356
- if (!containers.includes(container)) containers.push(container)
6357
- listedIn.set(identifier, containers)
6358
- }
6359
- }
6360
- const { recordsOf, archives, rootOf } = await placeRecordChannels(events, byId, listedIn, query)
6361
- for (const [id, containers] of listedIn) {
6362
- const folder = byId.get(id)
6363
- if (folder) folder.listedIn = containers
6364
- }
6365
- markArchivedFolders(byId, recordsOf, archives, rootOf)
6366
- return [...byId.values()].sort((a, b) => (a.name ?? a.id).localeCompare(b.name ?? b.id))
6415
+ return { events, byId }
6367
6416
  }
6368
6417
 
6369
6418
  /**
@@ -6873,8 +6922,8 @@ export async function resolveFolderContents(
6873
6922
  const listed: { file: ForeignObject; archive?: Archive }[] = []
6874
6923
  const archiveByAddress = new Map<string, Archive | undefined>()
6875
6924
  const parentByAddress = new Map<string, string | undefined>()
6876
- // How a parent outside this listing is read: its child's app's rule when that app draws it.
6877
- const parentRuleOf = new Map<string, RecordsRule>()
6925
+ // Whose app reads a parent outside this listing: its child's, when that app draws it.
6926
+ const manifestByAddress = new Map<string, Manifest>()
6878
6927
  for (const { address, pointer } of pointers) {
6879
6928
  const resolved = manifests.get(manifestKeyOf(pointer))
6880
6929
  // No app claims this kind, so there is no projection to draw it with.
@@ -6905,8 +6954,9 @@ export async function resolveFolderContents(
6905
6954
  const archive = archiveOf(events, address, archiveRuleOf(resolved.manifest), root, nestedAdmins)
6906
6955
  archiveByAddress.set(address, archive)
6907
6956
  const parent = parentRefOf(resolved.manifest, pointer.kind, root, folded)
6908
- parentByAddress.set(address, parent)
6909
- if (parent) parentRuleOf.set(parent, relatedRuleOf(resolved.manifest, parent))
6957
+ // Plain, as the listing's own addresses are, so an `naddr` parent listed here is found here.
6958
+ parentByAddress.set(address, parent && (plainAddress(parent) ?? parent))
6959
+ manifestByAddress.set(address, resolved.manifest)
6910
6960
  // An app hiding a record from its own lists is saying it is not part of the
6911
6961
  // folder any more. `hiddenWhen` is the app's own declaration of that — the
6912
6962
  // archive above is the same statement for a kind whose app declared none.
@@ -6958,36 +7008,63 @@ export async function resolveFolderContents(
6958
7008
  never written to the children, so unarchiving the parent restores
6959
7009
  exactly what was there.
6960
7010
 
6961
- The chain is walked through everything this Folder lists. A parent that
6962
- lives in another Folder is read once for all such parents, one level: a
6963
- project whose record channel lists its issues is the case that matters,
6964
- and there the project is listed too.
7011
+ The chain is walked through everything this Folder lists. Where it
7012
+ leaves the Folder, the rest is walked as a link reads it (SPEC §6.5,
7013
+ PEEKM-2): each ancestor with its root, so its archive is folded by
7014
+ §6.2's `h` rule, at any depth. One read per level for every such exit,
7015
+ and none when the chain stays here or meets an archived file first.
6965
7016
 
6966
7017
  Only by parent. A file this Folder lists is never hidden because some
6967
7018
  *other* Folder that lists it is archived — that is what lets a file
6968
7019
  placed in two Folders stay visible in the one that is not archived.
6969
7020
  */
6970
- const outside = [
6971
- ...new Set(
6972
- listed.flatMap(({ file }) => {
6973
- const parent = file.address && parentByAddress.get(file.address)
6974
- return parent && !archiveByAddress.has(parent) && addressPointerOf(parent) ? [parent] : []
6975
- }),
6976
- ),
6977
- ]
6978
- if (outside.length) {
6979
- const ruleFor = (parent: string) => parentRuleOf.get(parent) ?? ARCHIVE_RULE
6980
- const changes = await readArchiveChanges(outside, query, outside.map(ruleFor))
6981
- // A parent in another Folder is held by address only (SPEC §6.2's exception).
6982
- for (const parent of outside) archiveByAddress.set(parent, archiveOf(changes, parent, ruleFor(parent), undefined))
7021
+ // One walk per exit and the app reading it, as walkArchivedAbove keys its
7022
+ // reads: two children of one outside parent, drawn by different apps, each
7023
+ // read it by their own app's rule.
7024
+ const exits = new Map<string, { at: string; manifest: Manifest | undefined; seen: Set<string>; archive?: Archive }>()
7025
+ const exitOf = new Map<string, string>()
7026
+ const drawnBy: Manifest[] = []
7027
+ for (const { file, archive } of listed) {
7028
+ if (archive || !file.address) continue
7029
+ const seen = new Set([file.address])
7030
+ let child = file.address
7031
+ for (let at = parentByAddress.get(child); at && !seen.has(at); child = at, at = parentByAddress.get(at)) {
7032
+ if (!archiveByAddress.has(at)) {
7033
+ const plain = plainAddress(at)
7034
+ if (!plain) break
7035
+ const manifest = manifestByAddress.get(child)
7036
+ const own = manifest?.projections?.[String(addressPointerOf(plain)!.kind)] ? manifest : undefined
7037
+ if (own && !drawnBy.includes(own)) drawnBy.push(own)
7038
+ const key = `${plain}|${own ? drawnBy.indexOf(own) : ''}`
7039
+ if (!exits.has(key)) exits.set(key, { at: plain, manifest, seen })
7040
+ exitOf.set(file.address, key)
7041
+ break
7042
+ }
7043
+ if (archiveByAddress.get(at)) break
7044
+ seen.add(at)
7045
+ }
6983
7046
  }
7047
+ await walkArchivedAbove(
7048
+ [...exits.values()].map((exit) => ({
7049
+ at: exit.at,
7050
+ manifest: exit.manifest,
7051
+ seen: exit.seen,
7052
+ mark: (found: Archive) => {
7053
+ exit.archive = found
7054
+ },
7055
+ })),
7056
+ query,
7057
+ cache,
7058
+ )
6984
7059
  const files: ForeignObject[] = []
6985
7060
  for (const { file, archive } of listed) {
7061
+ const exit = file.address ? exitOf.get(file.address) : undefined
6986
7062
  const effective =
6987
7063
  archive ??
6988
7064
  (file.address
6989
7065
  ? archivedAncestorOf(file.address, (a) => parentByAddress.get(a), (a) => archiveByAddress.get(a))
6990
- : undefined)
7066
+ : undefined) ??
7067
+ (exit ? exits.get(exit)?.archive : undefined)
6991
7068
  if (!effective) files.push(file)
6992
7069
  else if (options.includeArchived) files.push({ ...file, archived: effective })
6993
7070
  }