@estiva-app/interop 0.2.0 → 0.4.0

package/CHANGELOG.md

@@ -6,6 +6,92 @@ how a declaration is read, is a MAJOR — in `0.x`, a MINOR — even when no
 TypeScript signature moved. A consumer upgrading must be able to tell whether
 manifests already published still mean what they meant.
 
+## 0.4.0 — 2026-09-01
+
+**Manifest behaviour: unchanged.** Nothing a manifest may declare moved. What
+moves is a cache that had been living in one app.
+
+- **`createPeopleCache()`** — the foreign-profile cache, with its batching and
+  its two TTLs, lifted out of Peek.
+
+  It was written there for PEE-3, and the shape is the interesting part.
+  `PROFILE_HIT_TTL_MS` is ten minutes because names change rarely;
+  `PROFILE_MISS_TTL_MS` is one, because **a miss is somebody who has not
+  finished setting up their identity — precisely the person whose name is about
+  to arrive.** Cached as long as a hit, they render as `nostr:<8 chars>` until a
+  full reload, and a consumer that re-reads on a timer looks like its refresh is
+  broken.
+
+  Ship needed the same behaviour, and a second consumer is what moves something
+  out of one app rather than duplicating it. Without it Ship re-read `kind:0`
+  for every author of every child on every tick: a referenced Peek topic with 50
+  messages cost **2 requests a tick where a Ship object cost 1** — the cross-app
+  case PRO-7 exists for being the dearest rather than the cheapest.
+
+  **Store and lookup have different lifetimes**, which is why this is a cache
+  with `through(fromRelay)` rather than a wrapped function. A consumer builds
+  its query per call — Peek's carries the viewer's token — while the profiles it
+  finds are public and worth keeping across all of them. `viaRelay(query)` is
+  the common case. Caller-owned, like `createProjectionCache`; Peek's original
+  was a module-level `Map`, which worked but meant every test needed a reset
+  hook to undo the previous one.
+
+  Peek's seven cases travel with it, converted from vitest **by hand** — a regex
+  pass over an earlier suite produced assertions with no `assert` in them, which
+  read fine and test nothing — and five more pin the store's lifetime, which the
+  original could not express.
+
+Additive, so a MINOR by the rule ADR 0002 §4b sets for `0.x`.
+
+## 0.3.0 — 2026-09-01
+
+**Manifest behaviour: unchanged.** Nothing a manifest may declare moved, and
+nothing already published means anything different. What changes is how many
+round trips reading one costs.
+
+- **`createProjectionCache()`**, passed as the last argument to
+  `resolveForeignObject`, `resolveForeignEvent` and `resolveFolderProject`.
+  Omitting it is exactly the old behaviour.
+
+  A consumer that re-resolves on a timer paid the whole resolve every tick, and
+  **two of the four round trips were NIP-89 discovery** — the author's
+  `kind:31989` recommendation, then the `kind:31990` manifest. Those answer the
+  same thing until an app republishes. Memoised per kind and author with a
+  five-minute TTL; a negative answer is cached too, because "no app claims this
+  kind" costs the same two round trips and is just as stable.
+
+  **Owned by the caller.** A module-level cache would be invisible global state
+  shared by every consumer in a process, impossible to scope to a screen and
+  awkward to reset in a test.
+
+  Deliberately only the manifest. The object, its changes, its comments and its
+  children are what a refresh exists to notice — caching those is how a live
+  widget becomes a screenshot, which is the defect PRO-10 was filed for.
+
+- **A `list` slot no longer costs a round trip of its own.** The child filter is
+  built from the manifest and the *pointer*, and an addressable event's `d` is
+  `pointer.identifier` by definition — it is what the root filter matches on. So
+  the second query never needed to wait for the first, and the children now ride
+  in the same request.
+
+  The two together: **10 requests a tick to 3** for three references on one Ship
+  issue, measured against production — one per reference — rendering identically
+  (title, kind, comment count, child count, widget). A comment posted between
+  ticks appeared on the next one-request resolve, so the widget is still live.
+
+- **Comments and children are now matched on their filter's own criteria**, not
+  on kind. This is load-bearing rather than tidying: Peek's Topic declares
+  `kind:9` messages as children *and* `kind:9` as its comment kind, so merging
+  the two filters into one request puts both under one number and only the tag
+  separates them. Matching on kind alone would have made every message in a
+  Folder a comment on its own Topic. The predicate uses **any** matching tag,
+  as a relay's `#a` does — an event may carry several, and reading only the
+  first would silently drop a comment that references something else before its
+  parent.
+
+Additive, with a changed request pattern, so a MINOR: ADR 0002 §4b puts the
+break on MINOR within `0.x`.
+
 ## 0.2.0 — 2026-09-01
 
 **Manifest behaviour: unchanged for addressable objects.** What changes is that

package/dist/index.d.ts

@@ -24,5 +24,5 @@
  * of every app that installed it, which is the objection that rules out
  * iframes.
  */
-export { resolveManifest, resolveForeignObject, resolveForeignEvent, resolveFolderProject, commentKindsOf, buildActionEvent, pickWidget, widgetChainProblem, CLOSED_WIDGETS, peopleViaRelay, type QueryFn, type PeopleFn, type People, type ForeignObject, type FolderProject, type ResolvedSlot, type ResolvedAction, type ManifestAction, type UnsignedActionEvent, } from './projection.js';
+export { resolveManifest, resolveForeignObject, resolveForeignEvent, resolveFolderProject, commentKindsOf, buildActionEvent, pickWidget, widgetChainProblem, CLOSED_WIDGETS, peopleViaRelay, createProjectionCache, createPeopleCache, MANIFEST_TTL_MS, PROFILE_HIT_TTL_MS, PROFILE_MISS_TTL_MS, type PeopleCache, type PeopleCacheOptions, type ProjectionCache, type ResolvedManifest, type QueryFn, type PeopleFn, type People, type ForeignObject, type FolderProject, type ResolvedSlot, type ResolvedAction, type ManifestAction, type UnsignedActionEvent, } from './projection.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,OAAO,EACL,eAAe,EACf,oBAAoB,EACpB,mBAAmB,EACnB,oBAAoB,EACpB,cAAc,EACd,gBAAgB,EAChB,UAAU,EACV,kBAAkB,EAClB,cAAc,EACd,cAAc,EACd,KAAK,OAAO,EACZ,KAAK,QAAQ,EACb,KAAK,MAAM,EACX,KAAK,aAAa,EAClB,KAAK,aAAa,EAClB,KAAK,YAAY,EACjB,KAAK,cAAc,EACnB,KAAK,cAAc,EACnB,KAAK,mBAAmB,GACzB,MAAM,iBAAiB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,OAAO,EACL,eAAe,EACf,oBAAoB,EACpB,mBAAmB,EACnB,oBAAoB,EACpB,cAAc,EACd,gBAAgB,EAChB,UAAU,EACV,kBAAkB,EAClB,cAAc,EACd,cAAc,EACd,qBAAqB,EACrB,iBAAiB,EACjB,eAAe,EACf,kBAAkB,EAClB,mBAAmB,EACnB,KAAK,WAAW,EAChB,KAAK,kBAAkB,EACvB,KAAK,eAAe,EACpB,KAAK,gBAAgB,EACrB,KAAK,OAAO,EACZ,KAAK,QAAQ,EACb,KAAK,MAAM,EACX,KAAK,aAAa,EAClB,KAAK,aAAa,EAClB,KAAK,YAAY,EACjB,KAAK,cAAc,EACnB,KAAK,cAAc,EACnB,KAAK,mBAAmB,GACzB,MAAM,iBAAiB,CAAA"}

package/dist/index.js

@@ -24,5 +24,5 @@
  * of every app that installed it, which is the objection that rules out
  * iframes.
  */
-export { resolveManifest, resolveForeignObject, resolveForeignEvent, resolveFolderProject, commentKindsOf, buildActionEvent, pickWidget, widgetChainProblem, CLOSED_WIDGETS, peopleViaRelay, } from './projection.js';
+export { resolveManifest, resolveForeignObject, resolveForeignEvent, resolveFolderProject, commentKindsOf, buildActionEvent, pickWidget, widgetChainProblem, CLOSED_WIDGETS, peopleViaRelay, createProjectionCache, createPeopleCache, MANIFEST_TTL_MS, PROFILE_HIT_TTL_MS, PROFILE_MISS_TTL_MS, } from './projection.js';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,OAAO,EACL,eAAe,EACf,oBAAoB,EACpB,mBAAmB,EACnB,oBAAoB,EACpB,cAAc,EACd,gBAAgB,EAChB,UAAU,EACV,kBAAkB,EAClB,cAAc,EACd,cAAc,GAUf,MAAM,iBAAiB,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,OAAO,EACL,eAAe,EACf,oBAAoB,EACpB,mBAAmB,EACnB,oBAAoB,EACpB,cAAc,EACd,gBAAgB,EAChB,UAAU,EACV,kBAAkB,EAClB,cAAc,EACd,cAAc,EACd,qBAAqB,EACrB,iBAAiB,EACjB,eAAe,EACf,kBAAkB,EAClB,mBAAmB,GAcpB,MAAM,iBAAiB,CAAA"}

package/dist/projection.d.ts

@@ -45,6 +45,51 @@ export type People = Record<string, Profile>;
  */
 export type PeopleFn = (pubkeys: string[]) => Promise<People>;
 /** The default: one kind:0 query, straight to the relay. */
+/**
+ * How long a *name* may be believed.
+ *
+ * Names change rarely, so this is generous. See {@link PROFILE_MISS_TTL_MS} for
+ * the half that matters.
+ */
+export declare const PROFILE_HIT_TTL_MS: number;
+/**
+ * How long an *absent* profile may be believed, and it is deliberately short.
+ *
+ * A miss is somebody who has not finished setting up their identity — which is
+ * to say, precisely the person whose name is about to arrive. Cached as long as
+ * a hit, they render as `nostr:<8 chars>` until a full reload, and a consumer
+ * that re-reads on a timer looks like its refresh is broken. That is PEE-3,
+ * found in Peek once its panels started polling.
+ */
+export declare const PROFILE_MISS_TTL_MS = 60000;
+export interface PeopleCacheOptions {
+    hitTtlMs?: number;
+    missTtlMs?: number;
+    /** Injectable clock. A test needs to move time, not wait ten minutes. */
+    now?: () => number;
+}
+/**
+ * A profile store that outlives any one lookup.
+ *
+ * The store and the lookup have different lifetimes, which is why this is not
+ * simply a wrapped {@link PeopleFn}: a consumer builds its query per call —
+ * Peek's carries the viewer's token — while the profiles it finds are public
+ * and worth keeping across all of them. `through` takes the lookup of the
+ * moment and answers from one store.
+ *
+ * **Caller-owned**, like {@link createProjectionCache}. Peek's original lived in
+ * a module-level `Map`, which worked but meant every test needed a reset hook
+ * to undo the previous one.
+ */
+export interface PeopleCache {
+    /** Wrap a lookup so it batches and expires against this store. */
+    through(fromRelay: PeopleFn): PeopleFn;
+    /** The common case: {@link peopleViaRelay}, cached. */
+    viaRelay(query: QueryFn): PeopleFn;
+    /** Forget everything. What a sign-out should call. */
+    clear(): void;
+}
+export declare function createPeopleCache(options?: PeopleCacheOptions): PeopleCache;
 export declare function peopleViaRelay(query: QueryFn): PeopleFn;
 /**
  * Every kind an app's comments might be under — what it publishes **now**, plus
@@ -223,13 +268,62 @@ interface Manifest {
         stage?: string;
     }[]>;
 }
-export declare function resolveManifest(pointer: AddressPointer, query: QueryFn): Promise<{
+/** What {@link resolveManifest} answers with. */
+export interface ResolvedManifest {
     manifest: Manifest;
     address: string;
     viaRecommendation: boolean;
     /** NIP-89 `web` template, `<bech32>` not yet substituted. */
     webTemplate?: string;
-} | null>;
+}
+/**
+ * A memo for the half of a resolve that does not change between refreshes.
+ *
+ * Resolving one reference costs four round trips, and **two of them are NIP-89
+ * discovery** — the author's `kind:31989` recommendation, then the `kind:31990`
+ * manifest itself. A consumer that re-resolves on a timer pays for both every
+ * time, and they answer the same thing until an app republishes its manifest.
+ * Measured on Ship, where a reference widget re-resolves on the poll: 4
+ * requests per reference per tick, identical on the second resolve, against a
+ * relay that meters reads at 300 a minute.
+ *
+ * **Owned by the caller, not this module.** A module-level cache would be
+ * invisible global state shared by every consumer in the process, impossible to
+ * scope to a screen and awkward to reset in a test. A caller that wants no
+ * caching passes nothing and gets exactly the old behaviour.
+ *
+ * Deliberately only the manifest. The object, its changes, its comments and its
+ * children are the parts a refresh exists to notice, and caching those is how
+ * a live widget becomes a screenshot.
+ */
+export interface ProjectionCache {
+    /** Forget everything. Worth calling after publishing a manifest. */
+    clear(): void;
+    /** @internal */
+    lookup(key: string, now: number): {
+        value: ResolvedManifest | null;
+    } | undefined;
+    /** @internal */
+    remember(key: string, value: ResolvedManifest | null, now: number): void;
+}
+/**
+ * How long a manifest may be believed without asking again.
+ *
+ * Five minutes is a compromise with one real cost: republish a manifest and
+ * consumers keep drawing the old projection for up to that long. That is
+ * recoverable and self-correcting, where the alternative — asking twice per
+ * reference per tick, for ever — is neither.
+ */
+export declare const MANIFEST_TTL_MS: number;
+export declare function createProjectionCache(ttlMs?: number): ProjectionCache;
+/**
+ * A negative answer is cached too.
+ *
+ * "No app claims this kind" costs the same two round trips as a hit and is just
+ * as stable. Caching only successes would leave the expensive case — a
+ * reference nothing can draw — paying full price on every tick for ever.
+ */
+export declare function resolveManifest(pointer: AddressPointer, query: QueryFn, cache?: ProjectionCache): Promise<ResolvedManifest | null>;
 /**
  * Which layout to draw, from a declared type or an ordered chain of them.
  *
@@ -456,7 +550,9 @@ export interface ForeignObject {
  */
 export declare function resolveForeignEvent(reference: string, query: QueryFn, 
 /** Defaults to asking the relay. The browser passes a cached lookup. */
-lookupPeople?: PeopleFn): Promise<ForeignObject | null>;
+lookupPeople?: PeopleFn, 
+/** See {@link ProjectionCache}. Omitting it is exactly the old behaviour. */
+cache?: ProjectionCache): Promise<ForeignObject | null>;
 export declare function resolveForeignObject(naddr: string, query: QueryFn, 
 /** Defaults to asking the relay. The browser passes a cached lookup. */
 lookupPeople?: PeopleFn, 
@@ -465,7 +561,12 @@ lookupPeople?: PeopleFn,
  * module leave it at 0; it is the budget that stops a child's own `list`
  * recursing forever. See `MAX_LIST_DEPTH`.
  */
-depth?: number): Promise<ForeignObject | null>;
+depth?: number, 
+/**
+ * Optional memo for the NIP-89 discovery half. See {@link ProjectionCache} —
+ * omitting it is exactly the old behaviour.
+ */
+cache?: ProjectionCache): Promise<ForeignObject | null>;
 /**
  * A Folder's project and the tickets in motion in it.
  *
@@ -513,7 +614,9 @@ lookupPeople?: PeopleFn,
  * outside this module leave it at 0; it exists so that following a child's
  * own `list` is a budget check rather than a thing nobody remembered.
  */
-depth?: number): Promise<FolderProject | null>;
+depth?: number, 
+/** See {@link ProjectionCache}. Omitting it is exactly the old behaviour. */
+cache?: ProjectionCache): Promise<FolderProject | null>;
 /**
  * Build the event that performs a manifest-declared action.
  *

package/dist/projection.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"projection.d.ts","sourceRoot":"","sources":["../src/projection.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"projection.d.ts","sourceRoot":"","sources":["../src/projection.ts"],"names":[],"mappings":"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"}

package/dist/projection.js

@@ -15,6 +15,57 @@
 import { decodeNevent, encodeNaddr, encodeNevent, pointerToAddress, referenceToPointer } from '@estiva-app/protocol';
 import { parseProfile } from '@estiva-app/protocol';
 /** The default: one kind:0 query, straight to the relay. */
+/**
+ * How long a *name* may be believed.
+ *
+ * Names change rarely, so this is generous. See {@link PROFILE_MISS_TTL_MS} for
+ * the half that matters.
+ */
+export const PROFILE_HIT_TTL_MS = 10 * 60_000;
+/**
+ * How long an *absent* profile may be believed, and it is deliberately short.
+ *
+ * A miss is somebody who has not finished setting up their identity — which is
+ * to say, precisely the person whose name is about to arrive. Cached as long as
+ * a hit, they render as `nostr:<8 chars>` until a full reload, and a consumer
+ * that re-reads on a timer looks like its refresh is broken. That is PEE-3,
+ * found in Peek once its panels started polling.
+ */
+export const PROFILE_MISS_TTL_MS = 60_000;
+/** A profile with nothing in it is a miss — the relay had no `kind:0`. */
+const isMiss = (person) => Object.keys(person).length === 0;
+export function createPeopleCache(options = {}) {
+    const hitTtlMs = options.hitTtlMs ?? PROFILE_HIT_TTL_MS;
+    const missTtlMs = options.missTtlMs ?? PROFILE_MISS_TTL_MS;
+    const now = options.now ?? Date.now;
+    const known = new Map();
+    const through = (fromRelay) => async (pubkeys) => {
+        const at = now();
+        /*
+          One lookup for the whole unknown set, never one per key. A screen with ten
+          reference widgets asks about the same handful of people, and asking
+          separately would turn one request into N — which is the cost this exists
+          to avoid, not a detail of it.
+        */
+        const unknown = pubkeys.filter((key) => {
+            const cached = known.get(key);
+            return cached === undefined || cached.expiresAt <= at;
+        });
+        if (unknown.length > 0) {
+            const found = await fromRelay(unknown);
+            for (const key of unknown) {
+                const person = found[key] ?? {};
+                known.set(key, { person, expiresAt: at + (isMiss(person) ? missTtlMs : hitTtlMs) });
+            }
+        }
+        return Object.fromEntries(pubkeys.map((key) => [key, known.get(key)?.person ?? {}]));
+    };
+    return {
+        through,
+        viaRelay: (query) => through(peopleViaRelay(query)),
+        clear: () => known.clear(),
+    };
+}
 export function peopleViaRelay(query) {
     return async (pubkeys) => {
         if (pubkeys.length === 0)
@@ -124,6 +175,17 @@ function resolveActions(manifest, kind, folded) {
     return out;
 }
 const tagValue = (e, name) => e.tags.find((t) => t[0] === name)?.[1];
+/**
+ * Does the event carry this tag with this value — on **any** of them?
+ *
+ * `tagValue` reads the first tag with a given name, which is the wrong test for
+ * deciding whether an event would have matched a filter: a relay's `#a` matches
+ * if *any* `a` tag equals the wanted value, and an event may legitimately carry
+ * several. Used where a filter's own predicate is re-applied to a merged
+ * response (SHI-13), so that "did this come back because of that filter?" is
+ * answered the way the relay answered it.
+ */
+const hasTagValue = (e, name, value) => e.tags.some((t) => t[0] === name && t[1] === value);
 /** A manifest event's `content`, or null when it is not parseable JSON. */
 function parseManifest(event) {
     try {
@@ -172,7 +234,54 @@ function webTemplate(event, entity) {
     }
     return undefined;
 }
-export async function resolveManifest(pointer, query) {
+/**
+ * How long a manifest may be believed without asking again.
+ *
+ * Five minutes is a compromise with one real cost: republish a manifest and
+ * consumers keep drawing the old projection for up to that long. That is
+ * recoverable and self-correcting, where the alternative — asking twice per
+ * reference per tick, for ever — is neither.
+ */
+export const MANIFEST_TTL_MS = 5 * 60_000;
+export function createProjectionCache(ttlMs = MANIFEST_TTL_MS) {
+    const entries = new Map();
+    return {
+        clear: () => entries.clear(),
+        lookup(key, now) {
+            const found = entries.get(key);
+            if (!found)
+                return undefined;
+            // `>=`, not `>`: a TTL of 0 must mean "never believe it", and an entry
+            // exactly at the boundary has expired rather than being on its last tick.
+            if (now - found.at >= ttlMs) {
+                entries.delete(key);
+                return undefined;
+            }
+            return { value: found.value };
+        },
+        remember(key, value, now) {
+            entries.set(key, { at: now, value });
+        },
+    };
+}
+/**
+ * A negative answer is cached too.
+ *
+ * "No app claims this kind" costs the same two round trips as a hit and is just
+ * as stable. Caching only successes would leave the expensive case — a
+ * reference nothing can draw — paying full price on every tick for ever.
+ */
+export async function resolveManifest(pointer, query, cache) {
+    const key = `${pointer.kind}:${pointer.pubkey}`;
+    const now = Date.now();
+    const memo = cache?.lookup(key, now);
+    if (memo)
+        return memo.value;
+    const answer = await resolveManifestUncached(pointer, query);
+    cache?.remember(key, answer, now);
+    return answer;
+}
+async function resolveManifestUncached(pointer, query) {
     const parse = parseManifest;
     const addressOf = (event) => `${event.kind}:${event.pubkey}:${tagValue(event, 'd') ?? ''}`;
     const recommended = await query([
@@ -554,7 +663,9 @@ function buildObject(args) {
  */
 export async function resolveForeignEvent(reference, query, 
 /** Defaults to asking the relay. The browser passes a cached lookup. */
-lookupPeople) {
+lookupPeople, 
+/** See {@link ProjectionCache}. Omitting it is exactly the old behaviour. */
+cache) {
     let pointer;
     try {
         pointer = /^[0-9a-f]{64}$/i.test(reference.replace(/^nostr:/i, ''))
@@ -574,7 +685,7 @@ lookupPeople) {
     // Whoever signed it is the app's own author, which is what a `#k` lookup
     // needs when no recommendation exists. The pointer's `author` is a hint and
     // may disagree with the event; the event wins, because it is the thing.
-    const resolved = await resolveManifest({ kind: root.kind, pubkey: root.pubkey, identifier: '', relays: pointer.relays }, query);
+    const resolved = await resolveManifest({ kind: root.kind, pubkey: root.pubkey, identifier: '', relays: pointer.relays }, query, cache);
     if (!resolved)
         return null;
     const projection = resolved.manifest.projections?.[String(root.kind)];
@@ -603,7 +714,12 @@ lookupPeople,
  * module leave it at 0; it is the budget that stops a child's own `list`
  * recursing forever. See `MAX_LIST_DEPTH`.
  */
-depth = 0) {
+depth = 0, 
+/**
+ * Optional memo for the NIP-89 discovery half. See {@link ProjectionCache} —
+ * omitting it is exactly the old behaviour.
+ */
+cache) {
     let pointer;
     try {
         // Either form: a body carries `naddr1…`, an `a` tag carries the plain
@@ -614,7 +730,7 @@ depth = 0) {
         return null;
     }
     const address = pointerToAddress(pointer);
-    const resolved = await resolveManifest(pointer, query);
+    const resolved = await resolveManifest(pointer, query, cache);
     if (!resolved)
         return null;
     const { manifest, viaRecommendation } = resolved;
@@ -626,15 +742,29 @@ depth = 0) {
     if (!projection)
         return null;
     const records = foldRuleOf(manifest);
-    // One round trip for the root, its changes and its comments. `#a` on both the
-    // change and the comment kind, because both point at the object by *address*
-    // rather than by event id — which is what makes them survive the author
-    // replacing the root event.
+    /*
+      One round trip for the root, its changes, its comments **and its children**.
+  
+      `#a` on both the change and the comment kind, because both point at the
+      object by *address* rather than by event id — which is what makes them
+      survive the author replacing the root event.
+  
+      The children used to be a second round trip, issued after the root came
+      back. They never needed to be: the child filter is built from the manifest
+      and the *pointer*, and an addressable event's `d` is `pointer.identifier` by
+      definition — it is what we just queried by. So once the manifest is known,
+      nothing about the child filter depends on the root's contents (SHI-13).
+  
+      That is the difference between two requests per reference per refresh and
+      one, and with the manifest memoised it is the whole cost of a tick.
+    */
+    const childFilter = childFilterFor({ projection, manifest, pointer, depth });
     const events = await query([
         { kinds: [pointer.kind], authors: [pointer.pubkey], '#d': [pointer.identifier], limit: 1 },
         // Only when the app actually declares a change kind — see `foldRuleOf`.
         ...(manifest.records ? [{ kinds: [manifest.records.changeKind], '#a': [address], limit: 500 }] : []),
         { kinds: commentKinds, '#a': [address], limit: 200 },
+        ...(childFilter ? [childFilter.filter] : []),
     ]);
     const root = events.find((e) => e.kind === pointer.kind && tagValue(e, 'd') === pointer.identifier);
     if (!root) {
@@ -662,8 +792,19 @@ depth = 0) {
         };
     }
     const folded = foldChanges(events.filter((e) => e.kind === records.changeKind && tagValue(e, records.targetTag) === address), records);
+    /*
+      Matched on the comment filter's own criteria — the kind **and** the `a` tag.
+  
+      Kind alone was safe while this was its own query: the relay only returned
+      what the comment filter asked for. Now that the children ride in the same
+      request (SHI-13), a child sharing the comment kind would arrive here too and
+      be counted as a comment on its own parent. Peek is exactly that shape: its
+      Topic declares `kind:9` messages as children and `kind:9` as its comment
+      kind, so every message in the Folder would have become a comment on the
+      Topic — a widget silently showing a conversation twice.
+    */
     const comments = events
-        .filter((e) => commentKinds.includes(e.kind))
+        .filter((e) => commentKinds.includes(e.kind) && hasTagValue(e, 'a', address))
         .sort(byOrder)
         .map((e) => ({ id: e.id, author: e.pubkey, body: e.content, createdAt: e.created_at }));
     const object = buildObject({
@@ -691,12 +832,10 @@ depth = 0) {
       A child may be a regular event with no address of its own (Peek's messages
       are), so this builds by event rather than by pointer.
     */
-    const children = await resolveChildren({
-        projection,
-        root,
+    const children = childrenFrom({
+        events,
+        childFilter,
         manifest,
-        query,
-        depth,
         webTemplate: resolved.webTemplate,
         viaRecommendation,
     });
@@ -713,36 +852,69 @@ depth = 0) {
     return { ...object, people, ...(children ? { children: children.map((c) => ({ ...c, people })) } : {}) };
 }
 /**
- * Resolve a projection's `list` slot into child objects.
+ * The filter for a projection's `list` slot, or nothing.
+ *
+ * Split out from fetching so it can be built **before** the root event is in
+ * hand and merged into the object's own round trip (SHI-13). Everything it
+ * needs is in the manifest and the pointer: an addressable event's `d` *is*
+ * `pointer.identifier`, since that is what the root filter matches on, so
+ * reading it back off the root taught us nothing we did not already know.
  *
- * Returns undefined when no `list` is declared — distinct from `[]`, which
- * means "declared, and nothing matched". A renderer needs to tell "this holds
- * nothing" from "this holds no list".
+ * Returns undefined when no `list` is declared — distinct from a declared list
+ * that matches nothing, which a renderer must be able to tell apart. The two
+ * other "declared but not renderable" cases are folded in here too, and both
+ * come back as `[]` from {@link childrenFrom}: a depth budget already spent,
+ * and a child kind the manifest never says how to draw.
  */
-async function resolveChildren(args) {
-    const { projection, root, manifest, query, depth, webTemplate, viaRecommendation } = args;
+function childFilterFor(args) {
+    const { projection, manifest, pointer, depth } = args;
     const spec = projection.slots.list;
     const children = !Array.isArray(spec) ? spec?.children : undefined;
     if (!children)
         return undefined;
     // The consumer's budget, not the manifest's — see MAX_LIST_DEPTH.
     if (depth >= MAX_LIST_DEPTH)
-        return [];
-    const childProjection = manifest.projections?.[String(children.kind)];
+        return null;
     // A declared list whose child kind has no projection is not renderable, and
     // an empty list is the honest answer: the objects exist, this app has not
     // said how to draw them.
+    if (!manifest.projections?.[String(children.kind)])
+        return null;
+    const parent = children.match === 'identifier'
+        ? pointer.identifier
+        : pointerToAddress({ ...pointer, relays: [] });
+    return {
+        filter: { kinds: [children.kind], [`#${children.via}`]: [parent], limit: children.limit ?? 100 },
+        kind: children.kind,
+        via: children.via,
+        parent,
+    };
+}
+/**
+ * The child objects, picked back out of the merged result set.
+ *
+ * **Matched on the filter's own criteria, never on kind alone.** Peek's Topic
+ * declares `kind:9` messages as its children and `kind:9` as its comment kind,
+ * so a merged response carries both under one number and only the tag tells
+ * them apart. An event can honestly be both — Ship writes a `kind:9` with an
+ * `a` naming the object *and* an `h` naming the Folder — and it appeared in
+ * both result sets when these were two queries. Re-applying each filter's own
+ * predicate reproduces that, rather than making them compete.
+ */
+function childrenFrom(args) {
+    const { events, childFilter, manifest, webTemplate, viaRecommendation } = args;
+    if (childFilter === undefined)
+        return undefined;
+    if (childFilter === null)
+        return [];
+    const childProjection = manifest.projections?.[String(childFilter.kind)];
     if (!childProjection)
         return [];
-    const identifier = tagValue(root, 'd') ?? '';
-    const parent = children.match === 'identifier'
-        ? identifier
-        : pointerToAddress({ kind: root.kind, pubkey: root.pubkey, identifier, relays: [] });
-    const found = await query([
-        { kinds: [children.kind], [`#${children.via}`]: [parent], limit: children.limit ?? 100 },
-    ]);
     const records = foldRuleOf(manifest);
-    return found.sort(byOrder).map((event) => buildChildObject({ root: event, manifest, projection: childProjection, records, webTemplate, viaRecommendation }));
+    return events
+        .filter((e) => e.kind === childFilter.kind && hasTagValue(e, childFilter.via, childFilter.parent))
+        .sort(byOrder)
+        .map((event) => buildChildObject({ root: event, manifest, projection: childProjection, records, webTemplate, viaRecommendation }));
 }
 /**
  * Build a `ForeignObject` from an event that may have no address of its own.
@@ -996,7 +1168,9 @@ lookupPeople,
  * outside this module leave it at 0; it exists so that following a child's
  * own `list` is a budget check rather than a thing nobody remembered.
  */
-depth = 0) {
+depth = 0, 
+/** See {@link ProjectionCache}. Omitting it is exactly the old behaviour. */
+cache) {
     // The render loop this forbids is not hypothetical: two folders naming each
     // other's projects resolve forever, and the manifest declaring them is
     // another app's. See MAX_LIST_DEPTH.
@@ -1191,7 +1365,7 @@ depth = 0) {
     const address = pointerToAddress(pointer);
     // 3. Now the authoritative manifest — the object's author gets to say which
     //    app renders their project (kind:31989), same as for an inline reference.
-    const resolved = await resolveManifest(pointer, query);
+    const resolved = await resolveManifest(pointer, query, cache);
     if (!resolved) {
         return null;
     }