@recursiv/sdk 0.7.63 → 0.7.66

package/dist/resources/discovery.js

@@ -42,6 +42,26 @@ export const DISCOVERY_SOURCE_TIMEOUT_MS = 15_000;
  * "Minds posts didn't load" with Try again and which its Politics fallback (minds#1212) waits for.
  */
 export const DISCOVERY_SOURCE_RETRIES = 2;
+/**
+ * The longest the top of the feed holds the first page, counted from the page's start. The top's read and the reads of
+ * the posts its items need (Minds posts by id, a story's network posts) share this one deadline: a top that has not
+ * answered by then is left out, and an item whose post was not read by then shows only if the first hot page carries it.
+ */
+export const DISCOVERY_TOP_TIMEOUT_MS = 1500;
+/** What the top's deadline answers when it passes first. */
+const TOP_LATE = Symbol('top of the feed late');
+/** Top items a session asks for unless its options say otherwise: the top block. */
+export const DISCOVERY_TOP_LIMIT = 10;
+/** Stories whose network posts a top's items are read from, at most. */
+const TOP_MAX_STORY_READS = 3;
+/** A hot page the seen set (or the top) leaves under this many posts walks on to the next hot page... */
+export const DISCOVERY_SEEN_MIN_ITEMS = 5;
+/** ...up to this many more pages in one read; then the page is what it is and the next read goes on from there. */
+export const DISCOVERY_SEEN_WALK = 3;
+/** A story whose lead was on screen this many times with no open is skipped (DiscoveryFeedSessionOptions.seenClusters). */
+export const RADAR_REST_AFTER = 3;
+/** A visitor's page-0 story rotates by bucket among this many best breaking stories (or best stories when none is breaking). */
+export const RADAR_BUCKET_ROTATION = 5;
 /** The page deadline a source's read ran past. */
 class SourceTimedOut extends Error {
     constructor() { super('Discovery source timed out'); this.name = 'SourceTimedOut'; }
@@ -168,6 +188,103 @@ function radarCluster(value) {
     return { id: c.id, label: c.label.slice(0, 300), kind: c.kind, ...(theme ? { theme } : {}), outletCount: mainstream + independent, laneMix: { mainstream, independent }, sources,
         velocity: { normalized: typeof normalized === 'number' && Number.isFinite(normalized) && normalized >= 0 ? normalized : 0 }, newestAt, ...(lead ? { lead } : {}), links, memberKeys };
 }
+/**
+ * The top's lead story as a cluster, for a page whose radar snapshot does not hold it (the radar read failed or timed
+ * out): its label, kind, theme, sources and freshness, with no links or member posts (the app opens the story by id).
+ */
+function storyCluster(value) {
+    if (!value || typeof value !== 'object')
+        return null;
+    const s = value;
+    if (typeof s.id !== 'string' || !/^[0-9a-f]{64}$/.test(s.id) || !nonEmpty(s.label) || typeof s.kind !== 'string' || !RADAR_KINDS.has(s.kind))
+        return null;
+    const newestAt = (s.freshness ?? {}).newestAt;
+    if (typeof newestAt !== 'string' || !Number.isFinite(Date.parse(newestAt)))
+        return null;
+    const sources = {};
+    if (s.sources && typeof s.sources === 'object')
+        for (const [name, count] of Object.entries(s.sources)) {
+            const n = countOf(count);
+            if (n !== null && /^[a-z]{1,32}$/.test(name))
+                sources[name] = n;
+        }
+    const theme = typeof s.theme === 'string' && /^[a-z][a-z0-9-]{0,31}$/.test(s.theme) ? s.theme : undefined;
+    return { id: s.id, label: s.label.slice(0, 300), kind: s.kind, ...(theme ? { theme } : {}), outletCount: sources.outlet ?? 0,
+        laneMix: { mainstream: 0, independent: 0 }, sources, velocity: { normalized: 0 }, newestAt, links: [], memberKeys: [] };
+}
+/** Page 0: the top breaking story, else the top story. Later pages: the next unused story that is not breaking. */
+export function pickRadarCluster(clusters, page, options = {}) {
+    const rested = (cluster) => { const seen = options.seenClusters?.get(cluster.id); return !!seen && !seen.clicked && seen.n >= RADAR_REST_AFTER; };
+    const unused = clusters.filter(candidate => !options.used?.has(candidate.id) && !rested(candidate));
+    if (page !== 0)
+        return unused.find(candidate => candidate.kind !== 'breaking');
+    const breaking = unused.filter(candidate => candidate.kind === 'breaking');
+    if (options.bucket !== undefined && Number.isSafeInteger(options.bucket)) {
+        const turn = (breaking.length ? breaking : unused).slice(0, RADAR_BUCKET_ROTATION);
+        if (turn.length)
+            return turn[((options.bucket % turn.length) + turn.length) % turn.length];
+    }
+    return breaking[0] ?? unused[0];
+}
+const TOP_NETWORKS = new Set(['bluesky', 'activitypub', 'nostr']);
+const idString = (value) => typeof value === 'string' && value.length > 0 && value.length <= 4096;
+const counted = (value) => typeof value === 'number' && Number.isFinite(value) && value >= 0 ? value : null;
+/** The refs an app's seen set may hold for a post: its id, or '<protocol>/<nativeId>' (an ActivityPub id also without https://). */
+function seenRefsOf(protocol, id) {
+    if (protocol === 'minds')
+        return [id];
+    const ref = `${protocol}/${id}`;
+    return protocol === 'activitypub' && /^https:\/\//i.test(id) ? [ref, `${protocol}/${id.replace(/^https:\/\//i, '')}`] : [ref];
+}
+function topRow(value) {
+    if (!value || typeof value !== 'object')
+        return null;
+    const item = value;
+    const target = (item.target ?? {});
+    if (!idString(item.ref))
+        return null;
+    const explain = (item.explain ?? {});
+    const cluster = typeof explain.cluster === 'string' && /^[0-9a-f]{64}$/.test(explain.cluster) ? explain.cluster : null;
+    if (item.kind === 'post' && target.kind === 'post' && nonEmpty(target.id))
+        return { ref: item.ref, key: key('minds', target.id), kind: 'minds', id: target.id, cluster, seenRefs: seenRefsOf('minds', target.id) };
+    if (item.kind === 'network_post' && target.kind === 'network_post' && typeof target.protocol === 'string' && TOP_NETWORKS.has(target.protocol) && idString(target.nativeId)) {
+        return { ref: item.ref, key: key(target.protocol, target.nativeId), kind: 'social', id: target.nativeId, cluster, seenRefs: seenRefsOf(target.protocol, target.nativeId) };
+    }
+    return null;
+}
+/**
+ * One open-network lane entry as a post the session can show: the card's text, author, media and counts. The card
+ * carries no URL on the post's network, so neither does the post (`sourceUrl` and the author's `profileUrl` are empty):
+ * the app opens it by its ref, in the app.
+ */
+function laneItem(value, protocol) {
+    if (!value || typeof value !== 'object')
+        return null;
+    const entry = value;
+    const target = (entry.target ?? {});
+    const card = (entry.card ?? null);
+    const author = (card?.author ?? null);
+    if (entry.protocol !== protocol || !idString(entry.ref) || target.kind !== 'network_post' || target.protocol !== protocol || !idString(target.nativeId))
+        return null;
+    if (!card || typeof card.text !== 'string' || typeof card.createdAt !== 'string' || !author || !idString(author.nativeId) || !nonEmpty(author.handle))
+        return null;
+    const counts = (card.counts ?? {});
+    const sensitive = card.sensitive === true;
+    const media = [];
+    for (const raw of Array.isArray(card.media) ? card.media.slice(0, 8) : []) {
+        const m = (raw ?? {});
+        if ((m.type !== 'image' && m.type !== 'video') || !httpUrl(m.url))
+            continue;
+        media.push({ type: m.type, url: m.url, alt: typeof m.alt === 'string' ? m.alt : '', ...(httpUrl(m.poster) ? { poster: m.poster } : {}),
+            ...(dimension(m.width) && dimension(m.height) ? { width: dimension(m.width), height: dimension(m.height) } : {}), ...(sensitive ? { sensitive: true } : {}) });
+    }
+    const post = { protocol, nativeId: target.nativeId, sourceUrl: '', ...(nonEmpty(target.readRef) ? { readRef: target.readRef } : {}),
+        author: { protocol, nativeId: author.nativeId, handle: author.handle, displayName: nonEmpty(author.displayName) ? author.displayName : author.handle, description: '',
+            profileUrl: '', avatarUrl: httpUrl(author.avatarUrl) ? author.avatarUrl : null, followersCount: null, followingCount: null, postsCount: null },
+        text: card.text, createdAt: card.createdAt, replyCount: counted(counts.replies), likeCount: counted(counts.likes), repostCount: counted(counts.reposts),
+        media, hasAdditionalContent: card.hasQuote === true, ...(sensitive ? { sensitive: true } : {}) };
+    return { key: key(protocol, target.nativeId), kind: 'social', post, top: { ref: entry.ref, position: 0, block: 'top', lane: protocol } };
+}
 const FALLOVER_VIA = new Set(['personal', 'popular', 'static']);
 const filled = (value) => typeof value === 'string' && value.length > 0;
 /**
@@ -234,7 +351,17 @@ export class DiscoveryFeedSession {
     radarLoading = null;
     /** Member reads per story, started as soon as the story is known and shared by whichever page shows it. */
     memberReads = new Map();
-    constructor(posts, protocols, networks, category, source, learning, recommend, radar, members) {
+    /** The top of the feed (options.top with a reader), its read started with page 0's reads, and the keys it placed. */
+    top;
+    topLoading = null;
+    /** The story the top leads with, once its answer is in (null: it names none); undefined until then. */
+    topLead;
+    topKeys = new Set();
+    /** What the member already saw (options.seen): left out of the Minds hot pages. */
+    appSeen = null;
+    seenClusters;
+    bucket;
+    constructor(posts, protocols, networks, category, source, learning, recommend, radar, members, options = {}) {
         this.posts = posts;
         this.protocols = protocols;
         this.category = category;
@@ -247,6 +374,19 @@ export class DiscoveryFeedSession {
         const sources = [...new Set(networks.filter(n => n.capabilities.includes('public_trends')).map(n => n.protocol))].slice(0, 16);
         this.streams = ['minds', ...sources].filter(protocol => !source || source === 'all' || source === protocol)
             .map(protocol => ({ protocol, offset: 0, done: false, failed: false, used: [] }));
+        const { top, seen, seenClusters, bucket } = options;
+        if (top && typeof top.read === 'function' && nonEmpty(top.ref))
+            this.top = { ...top, read: top.read };
+        if (seen)
+            this.appSeen = new Set([...seen].filter((ref) => typeof ref === 'string').slice(0, 10_000));
+        this.seenClusters = seenClusters;
+        this.bucket = bucket;
+    }
+    /** The Minds hot pages leave out what the member saw or the top placed, and walk on past a page that leaves too little. */
+    get filtering() { return !!this.appSeen || this.topKeys.size > 0; }
+    /** A Minds hot item the page leaves out: shown on an earlier page, placed by the top, or in the member's seen set. */
+    hiddenFromHot(item) {
+        return this.seen.has(item.key) || this.topKeys.has(item.key) || (item.kind === 'minds' && !!this.appSeen?.has(item.post.id));
     }
     retryFailed() { for (const stream of this.streams) {
         stream.failed = false;
@@ -272,20 +412,44 @@ export class DiscoveryFeedSession {
             // opt-out rides in the params (ListPostsParams.retry), which a reader handed to a session forwards to read the
             // right page at all: a second argument was dropped by the Minds app's own wrappers (lib/discoverFeedResource,
             // lib/compassStatus withCompass, lib/watchSource), which pass the params alone (review of #4047).
-            const response = await this.posts.list({ ...params, sort: 'hot', ...(stream.cursor ? { cursor: stream.cursor } : { offset: stream.offset }), retry: false });
-            stream.offset += response.meta.scanned ?? response.meta.limit;
-            const next = response.meta.next_cursor ?? undefined;
-            stream.done = !response.meta.has_more || !!next && (next === stream.cursor || stream.used.includes(next));
-            if (stream.cursor)
-                stream.used = [...stream.used, stream.cursor].slice(-32);
-            stream.cursor = next;
-            // A category feed that ended a stage says where to go next; kept on the stream and reported on every page from here.
-            const fallover = readFallover(response.meta.fallover);
-            if (fallover)
-                stream.fallover = fallover;
-            return { items: response.data.map(post => ({ key: key('minds', post.id), kind: 'minds', post })),
-                layout: response.meta.discovery ?? ordinary, partial: response.meta.category_filter?.status === 'partial',
-                ...(response.meta.compass_filter ? { compass: response.meta.compass_filter } : {}) };
+            // With a seen set or a top, a hot page leaves out what the member saw or the top placed; one left under
+            // DISCOVERY_SEEN_MIN_ITEMS walks on to the next hot page, up to DISCOVERY_SEEN_WALK more, so the feed never looks
+            // ended while the ranking goes on. Each kept post keeps its own window's layout. Without either, one page as before.
+            const kept = [];
+            const layouts = [];
+            let head;
+            let partial = false;
+            let filtered = false;
+            for (let walked = 0;; walked++) {
+                const response = await this.posts.list({ ...params, sort: 'hot', ...(stream.cursor ? { cursor: stream.cursor } : { offset: stream.offset }), retry: false });
+                stream.offset += response.meta.scanned ?? response.meta.limit;
+                const next = response.meta.next_cursor ?? undefined;
+                stream.done = !response.meta.has_more || !!next && (next === stream.cursor || stream.used.includes(next));
+                if (stream.cursor)
+                    stream.used = [...stream.used, stream.cursor].slice(-32);
+                stream.cursor = next;
+                // A category feed that ended a stage says where to go next; kept on the stream and reported on every page from here.
+                const fallover = readFallover(response.meta.fallover);
+                if (fallover)
+                    stream.fallover = fallover;
+                const items = response.data.map(post => ({ key: key('minds', post.id), kind: 'minds', post }));
+                const read = { layout: response.meta.discovery ?? ordinary, partial: response.meta.category_filter?.status === 'partial',
+                    ...(response.meta.compass_filter ? { compass: response.meta.compass_filter } : {}) };
+                if (!this.filtering)
+                    return { items, ...read };
+                head ??= read;
+                partial ||= read.partial;
+                items.forEach((item, index) => {
+                    if (this.hiddenFromHot(item) || kept.some(row => row.key === item.key)) {
+                        filtered = true;
+                        return;
+                    }
+                    kept.push(item);
+                    layouts.push(windowLayout(read.layout, index));
+                });
+                if (kept.length >= DISCOVERY_SEEN_MIN_ITEMS || !filtered || stream.done || walked >= DISCOVERY_SEEN_WALK)
+                    return { items: kept, ...head, partial, layouts };
+            }
         }
         const validatePosts = (data) => {
             if (data.coverage !== 'provider_ranked_window' || data.items.length > 25 || data.items.some(post => post.protocol !== stream.protocol || post.author.protocol !== stream.protocol))
@@ -308,7 +472,7 @@ export class DiscoveryFeedSession {
             // not a round later, so the network's first page in a category is not empty by design.
             const previews = data.items.flatMap(topic => !this.category && topic.preview ? [{ key: key(topic.preview.protocol, topic.preview.nativeId), kind: 'social', post: topic.preview }] : []);
             if (previews.length || stream.done)
-                return { items: previews, layout: ordinary, partial };
+                return { items: previews, layout: ordinary, partial, ...(previews.length ? { previews: true } : {}) };
             return this.walkTopics(stream, params, validatePosts, partial, started);
         }
         validatePosts(data);
@@ -377,10 +541,21 @@ export class DiscoveryFeedSession {
     async readPage() {
         // The radar is one small snapshot read: start it with the page, not after the slowest provider,
         // and start the lead story's member reads the moment the snapshot names it.
+        // The top of the feed starts with them too, and holds the page at most DISCOVERY_TOP_TIMEOUT_MS from here (loadTop).
+        // Neither waits for the other: the radar's own pick reads its members as soon as the radar answers (unless the top
+        // already named its lead), and a lead the top names reads its own as soon as the top answers (readyTop). A lead that
+        // is the radar's pick shares the one read (memberPosts).
+        if (this.page === 0 && this.top && !this.topLoading)
+            this.topLoading = this.loadTop();
         if (this.page === 0 && this.radar && !this.radarLoading) {
             this.radarLoading = this.loadRadar();
-            void this.radarLoading.then(clusters => { const lead = this.pickCluster(clusters, 0); if (lead)
-                void this.memberPosts(lead); });
+            void this.radarLoading.then(clusters => {
+                if (this.topLead)
+                    return;
+                const lead = this.pickCluster(clusters, 0);
+                if (lead)
+                    void this.memberPosts(lead);
+            });
         }
         // A network that failed for a passing reason sat out the page after its failure; from this one it takes its turn
         // again. It stays failed, and named in retryingSources, until a page asks it: with more than three networks the
@@ -422,6 +597,9 @@ export class DiscoveryFeedSession {
                 cancel();
             }
         }));
+        // Page 0 opens with the top of the feed when it answered: its items lead, its lanes stand in for the networks' first reads.
+        const top = this.page === 0 && this.topLoading ? await this.topLoading : null;
+        const topItems = top ? this.placeTop(top, selected, reads) : [];
         // Round-robin before grouping: the largest network cannot occupy every slot.
         // Each item carries the judgment for its own window of its source response,
         // so one page can feature several modules instead of one per source batch.
@@ -432,18 +610,20 @@ export class DiscoveryFeedSession {
                 if (!item || this.seen.has(item.key))
                     continue;
                 this.seen.add(item.key);
-                mixed.push({ item, layout: windowLayout(read.layout, index) });
+                mixed.push({ item, layout: read.layouts?.[index] ?? windowLayout(read.layout, index) });
             }
         // Deduplication memory is bounded independently of the UI's virtual window.
         while (this.seen.size > 4096)
             this.seen.delete(this.seen.values().next().value);
-        const modules = [];
+        const modules = topItems.map((item, index) => this.topModule(this.page, index, item));
         const page = this.page++;
+        const topCount = modules.length;
         let remaining = mixed;
-        // The radar leads the first page with the top breaking story and returns
+        // The radar leads the first page with the top breaking story (the top's lead, when it names one) and returns
         // every second page with the next one. Its member posts move under the
         // story, on this page or on any later one, so the hot stream never repeats them.
-        const cluster = mixed.length ? await this.radarCluster(page) : null;
+        // A top that names a story leads with it even when no post came with the top or the reads (Codex review of #4205).
+        const cluster = mixed.length || topCount || top?.lead ? await this.radarCluster(page, top) : null;
         let clusterItems = [];
         if (cluster) {
             const members = new Set(cluster.memberKeys);
@@ -495,7 +675,7 @@ export class DiscoveryFeedSession {
         // the opening modules so the page still leads with content.
         const recommendation = modules.length ? await this.recommendation(page) : null;
         if (recommendation)
-            modules.splice(Math.min(2, modules.length), 0, recommendation);
+            modules.splice(Math.min(topCount + 2, modules.length), 0, recommendation);
         if (cluster)
             modules.splice(page === 0 ? 0 : Math.min(2, modules.length), 0, this.radarModule(page, cluster, clusterItems));
         const fallover = this.streams.find(stream => stream.protocol === 'minds')?.fallover;
@@ -507,12 +687,20 @@ export class DiscoveryFeedSession {
             ...(retrying.length ? { retryingSources: retrying } : {}), partialCategories: reads.some(read => read.partial),
             ...(fallover ? { fallover } : {}), ...(compass ? { compass } : {}) };
     }
-    /** Page 0: the top breaking cluster, else the top cluster. Every second later page: the next unused story or viral cluster. */
-    async radarCluster(page) {
+    /**
+     * Page 0: the top's lead when it names one, else the top breaking cluster, else the top cluster. Every second later
+     * page: the next unused story or viral cluster.
+     */
+    async radarCluster(page, top = null) {
         if (!this.radar)
             return null;
         if (page === 0)
             this.clusters = await (this.radarLoading ?? this.loadRadar());
+        if (page === 0 && top?.lead) {
+            const lead = this.leadOf(this.clusters ?? [], top);
+            this.radarUsed.add(lead.id);
+            return this.learning && this.learning.choose(lead.kind === 'breaking' ? 'breaking' : 'story', page) === 'posts' ? null : lead;
+        }
         if (!this.clusters?.length || (page !== 0 && page % 2 !== 0))
             return null;
         const cluster = this.pickCluster(this.clusters, page);
@@ -524,10 +712,139 @@ export class DiscoveryFeedSession {
             return null;
         return cluster;
     }
-    /** Page 0: the top breaking cluster, else the top cluster. Later pages: the next unused story or viral cluster. */
+    /** Page 0: the top breaking cluster, else the top cluster. Later pages: the next unused story or viral cluster (pickRadarCluster). */
     pickCluster(clusters, page) {
-        const unused = clusters.filter(candidate => !this.radarUsed.has(candidate.id));
-        return page === 0 ? unused.find(candidate => candidate.kind === 'breaking') ?? unused[0] : unused.find(candidate => candidate.kind !== 'breaking');
+        return pickRadarCluster(clusters, page, { used: this.radarUsed, seenClusters: this.seenClusters, bucket: this.bucket });
+    }
+    /** Page 0's story: the top's lead (from the radar snapshot when it holds it, so its links and members come along), else the client's pick. */
+    leadOf(clusters, top) {
+        if (top?.lead)
+            return clusters.find(candidate => candidate.id === top.lead.id) ?? top.lead;
+        return this.pickCluster(clusters, 0);
+    }
+    /** One top item as its own module, in the top's order: a video plays as a video module (unless the member's layouts say posts). */
+    topModule(page, index, item) {
+        const video = !!item.post.media?.some(media => media.type === 'video') && (this.learning?.choose('video', page) ?? 'video') === 'video';
+        return { id: `discovery-${page}-top-${index}-${item.key}`, presentation: video ? 'video' : 'posts', source: 'fallback', items: [item],
+            spec: { root: 'module', elements: { module: { type: video ? 'DiscoveryVideo' : 'DiscoveryPosts', props: { itemKeys: [item.key] }, children: [] } } } };
+    }
+    /**
+     * The top's read, then the posts its items need, all under one deadline of DISCOVERY_TOP_TIMEOUT_MS from the page's
+     * start: the reads of its posts get what is left of it, never a deadline of their own. Null when it failed, timed out
+     * or answered nothing usable: the page is then as without a top.
+     */
+    async loadTop() {
+        const top = this.top;
+        let timer;
+        const deadline = new Promise(resolve => { timer = setTimeout(() => resolve(TOP_LATE), DISCOVERY_TOP_TIMEOUT_MS); });
+        try {
+            const limit = Number.isSafeInteger(top.limit) && top.limit >= 1 && top.limit <= 25 ? top.limit : DISCOVERY_TOP_LIMIT;
+            const answer = await Promise.race([Promise.resolve().then(() => top.read({ ref: top.ref, limit, ...(nonEmpty(top.session) ? { session: top.session } : {}) })), deadline]);
+            if (answer === TOP_LATE)
+                return null;
+            return await this.readyTop(answer, deadline);
+        }
+        catch {
+            return null;
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+    /**
+     * Checks a top answer and reads what its items need before `deadline`: Minds posts by id, a story's network posts
+     * (lanes come with their cards). A lead it names starts reading its member posts at once.
+     */
+    async readyTop(answer, deadline) {
+        if (!answer || typeof answer !== 'object')
+            return null;
+        const value = answer;
+        if (!Array.isArray(value.items))
+            return null;
+        // Only what this session reads: a Minds item needs its Minds stream, a network's item or lane that network's stream.
+        const streams = new Set(this.streams.map(stream => stream.protocol));
+        const rows = [];
+        for (const raw of value.items.slice(0, 25)) {
+            const row = topRow(raw);
+            if (row && !rows.some(existing => existing.key === row.key) && streams.has(row.kind === 'minds' ? 'minds' : JSON.parse(row.key)[0]))
+                rows.push(row);
+        }
+        const lanes = new Map();
+        const networks = value.networks && typeof value.networks === 'object' ? value.networks : {};
+        for (const protocol of TOP_NETWORKS) {
+            const entries = networks[protocol];
+            if (!streams.has(protocol) || !Array.isArray(entries))
+                continue;
+            const lane = [];
+            for (const raw of entries.slice(0, 12)) {
+                const item = laneItem(raw, protocol);
+                if (item && !lane.some(existing => existing.key === item.key))
+                    lane.push({ ...item, top: { ...item.top, position: lane.length, block: lane.length < 10 ? 'top' : 'below' } });
+            }
+            if (lane.length)
+                lanes.set(protocol, lane);
+        }
+        const lead = this.radar ? storyCluster(value.lead) : null;
+        const impressions = (value.meta?.flag?.impressions) === 'on';
+        if (!rows.length && !lanes.size && !lead)
+            return null;
+        // The page's story is the top's lead: its member reads start now, alongside the reads below, not after them.
+        this.topLead = lead?.id ?? null;
+        if (lead && this.radarLoading)
+            void this.radarLoading.then(clusters => this.memberPosts(clusters.find(candidate => candidate.id === lead.id) ?? lead));
+        // The posts the rows need, read at once under the top's one deadline: a Minds post by id; a network post from its
+        // lane's card, else from its story's member posts. A row nothing read in time is left out (the first hot page may
+        // still carry it).
+        const inTime = (read, fallback) => Promise.race([Promise.resolve().then(read).catch(() => fallback), deadline.then(() => fallback)]);
+        const posts = new Map();
+        for (const lane of lanes.values())
+            for (const item of lane)
+                posts.set(item.key, { key: item.key, kind: 'social', post: item.post });
+        const readPost = this.top?.post ?? this.members?.minds;
+        const mindsReads = readPost ? rows.filter(row => row.kind === 'minds').map(row => inTime(() => readPost(row.id).then(({ data }) => data && data.id === row.id ? { key: row.key, kind: 'minds', post: data } : null), null)) : [];
+        const stories = [...new Set(rows.filter(row => row.kind === 'social' && !posts.has(row.key) && row.cluster).map(row => row.cluster))].slice(0, TOP_MAX_STORY_READS);
+        const wanted = new Set(rows.filter(row => row.kind === 'social').map(row => row.key));
+        const social = this.members?.social;
+        const storyReads = social ? stories.map(cluster => inTime(() => social({ cluster }).then(({ data }) => !data || data.cluster !== cluster || !Array.isArray(data.items) ? [] : data.items
+            .filter(post => post && idString(post.nativeId) && post.author?.protocol === post.protocol && wanted.has(key(post.protocol, post.nativeId)))
+            .map(post => ({ key: key(post.protocol, post.nativeId), kind: 'social', post }))), [])) : [];
+        const [minds, network] = await Promise.all([Promise.all(mindsReads), Promise.all(storyReads)]);
+        for (const item of [...minds, ...network.flat()])
+            if (item && !posts.has(item.key))
+                posts.set(item.key, item);
+        return { rows, posts, lanes, lead, impressions };
+    }
+    /**
+     * Places the top on page 0: each lane stands in for its network's first read (a topics network's catalog previews; a
+     * posts network's read follows its lane), and the top's items, read by id or carried by this page, become the page's
+     * first items, marked seen so no hot page repeats them. Without impressions in the top's order, the member's seen
+     * items follow the unseen ones.
+     */
+    placeTop(top, selected, reads) {
+        for (const [protocol, lane] of top.lanes) {
+            const at = selected.findIndex(stream => stream.protocol === protocol);
+            const read = at >= 0 ? reads[at] : null;
+            if (read) {
+                const kept = read.previews ? [] : read.items;
+                reads[at] = { ...read, items: [...lane, ...kept], layouts: [...lane.map(() => ordinary), ...kept.map((_item, index) => read.layouts?.[index] ?? windowLayout(read.layout, index))] };
+            }
+            else if (this.streams.some(stream => stream.protocol === protocol))
+                reads.push({ items: lane, layout: ordinary, partial: false });
+        }
+        const carried = new Map(reads.flatMap(read => read.items.map(item => [item.key, item])));
+        const seen = (row) => !!this.appSeen && row.seenRefs.some(ref => this.appSeen.has(ref));
+        const rows = top.impressions || !this.appSeen ? top.rows : [...top.rows.filter(row => !seen(row)), ...top.rows.filter(seen)];
+        const placed = [];
+        for (const row of rows) {
+            const found = top.posts.get(row.key) ?? carried.get(row.key);
+            if (!found || this.seen.has(row.key))
+                continue;
+            const position = placed.length;
+            placed.push({ ...found, top: { ref: row.ref, position, block: position < 10 ? 'top' : 'below' } });
+            this.seen.add(row.key);
+            this.topKeys.add(row.key);
+        }
+        return placed;
     }
     /** The story's members as feed items, read once per story and bounded to three seconds; a failed read is simply none. */
     memberPosts(cluster) {
@@ -645,11 +962,13 @@ export class DiscoveryResource {
     protocols;
     curator;
     http;
-    constructor(posts, protocols, curator, http) {
+    feeds;
+    constructor(posts, protocols, curator, http, feeds) {
         this.posts = posts;
         this.protocols = protocols;
         this.curator = curator;
         this.http = http;
+        this.feeds = feeds;
     }
     /**
      * Suggestions for the signed-in viewer from the app's one recommender: active or warm members, groups
@@ -726,12 +1045,23 @@ export class DiscoveryResource {
      * Discover's feed session. `compass` (a Politics choice, as `posts.list` takes it) goes on every Minds read, whose
      * pages then carry `meta.compass_filter`; the open networks' reads and the radar are not filtered by it, so a view
      * that leaves posts out (Hide politics, Choose sides) is best read with `source: 'minds'`.
+     *
+     * `top` opens the first page with the top of the feed (`feeds.top`, with the same `compass`, unless `top.read` is
+     * given); `seen` leaves what the member saw out of the hot pages; `seenClusters` and `bucket` rotate the story when
+     * the top names none (DiscoveryFeedSessionOptions). With none of them the session is what it was before they existed.
      */
     createFeed(options) {
         const compass = options.compass;
         const posts = compass ? { list: params => this.posts.list({ ...params, compass }) } : this.posts;
+        const feeds = this.feeds;
+        const http = this.http;
+        const read = options.top?.read ?? (feeds ? params => feeds.top({ ...params, ...(compass ? { compass } : {}) }, NO_RETRY) : undefined);
+        // A top item the first hot page does not carry is read by id once, never retried: the page holds its own deadline.
+        const post = options.top?.post ?? (http ? (id) => http.get(`/posts/${encodeURIComponent(id)}`, undefined, NO_RETRY) : undefined);
+        const top = options.top && read ? { ...options.top, read, ...(post ? { post } : {}) } : undefined;
         // The radar rides along by default; an older server answers 404 and the session simply shows no story module.
-        return new DiscoveryFeedSession(posts, this.protocols, options.networks, options.category, options.source, options.learning, options.recommend, params => this.protocols.getPublicRadar(params, NO_RETRY), { social: params => this.protocols.getPublicRadarPosts(params, NO_RETRY), minds: id => this.posts.get(id) });
+        return new DiscoveryFeedSession(posts, this.protocols, options.networks, options.category, options.source, options.learning, options.recommend, params => this.protocols.getPublicRadar(params, NO_RETRY), { social: params => this.protocols.getPublicRadarPosts(params, NO_RETRY), minds: id => this.posts.get(id) }, { ...(top ? { top } : {}), ...(options.seen ? { seen: options.seen } : {}), ...(options.seenClusters ? { seenClusters: options.seenClusters } : {}),
+            ...(options.bucket !== undefined ? { bucket: options.bucket } : {}) });
     }
 }
 /** A read bounded to three seconds; a late or failed one resolves to `fallback`, never an error. */