@recursiv/sdk 0.7.70 → 0.7.72

package/dist/resources/discovery.d.ts

@@ -2,9 +2,15 @@ import type { HttpClient } from '../client.js';
 import type { CompassFilterMeta, DiscoveryLayout, FalloverStep, MediaItem, Post } from '../types.js';
 import type { CuratorResource } from './curator.js';
 import type { DiscoveryLearning } from './discovery-learning.js';
+import { type ProgressiveDiscoveryFeed, type ProgressiveFeedSettings } from './discovery-progressive.js';
 import type { FeedStory, FeedTopItem, FeedTopNetwork, FeedTopNetworkEntry, FeedsResource } from './feeds.js';
 import type { PostsResource } from './posts.js';
 import type { ProtocolsResource, SocialNetwork, SocialPost, SocialRadar, SocialRadarPosts } from './protocols.js';
+export * from './discovery-fallover.js';
+export * from './discovery-first-screen.js';
+export * from './discovery-merge.js';
+export * from './discovery-progressive.js';
+export * from './discovery-safety.js';
 export type DiscoveryRecommendationKind = 'groups' | 'people' | 'tags';
 /** A page of Watch's Minds videos (`discovery.videos`). */
 export interface WatchVideosParams {
@@ -142,7 +148,7 @@ export interface CategorySurfaceSection<T> {
     reason?: string;
 }
 /** A radar cluster themed into the category, with up to six members (headline or excerpt and link only). */
-export type CategoryStory = Pick<SocialRadar['clusters'][number], 'id' | 'label' | 'kind' | 'theme' | 'sources' | 'corroboration' | 'laneMix' | 'velocity' | 'media' | 'freshness' | 'score' | 'members'>;
+export type CategoryStory = Pick<SocialRadar['clusters'][number], 'id' | 'label' | 'kind' | 'theme' | 'sources' | 'corroboration' | 'laneMix' | 'outlets' | 'velocity' | 'media' | 'freshness' | 'score' | 'members'>;
 export interface CategoryClip {
     id: string;
     title: string | null;
@@ -240,6 +246,7 @@ export interface DiscoveryCluster {
     label: string;
     kind: 'breaking' | 'viral' | 'story';
     theme?: string;
+    /** The story's outlets (StoryOutlets.total from 0.7.71's servers, else the lanes' sum): the number to show beside it. */
     outletCount: number;
     laneMix: {
         mainstream: number;
@@ -366,16 +373,30 @@ export interface DiscoveryFeedSessionOptions {
     top?: DiscoveryTopOptions;
     /**
      * What the member already saw (Minds post ids and '<protocol>/<nativeId>' refs, as the app records visible views): left
-     * out of the Minds hot pages. A page the filter leaves under DISCOVERY_SEEN_MIN_ITEMS walks on, up to
+     * out of the Minds hot pages, and out of the networks' trend pages, topic previews and topic pages (the top's own lanes
+     * stay: the top ranks them by impressions). A page the filter leaves under DISCOVERY_SEEN_MIN_ITEMS walks on, up to
      * DISCOVERY_SEEN_WALK more hot pages, and the stream's fall-through (`fallover`) still reports when it ends. When the
      * top's order did not use impressions (`meta.flag.impressions` not 'on'), the top's seen items follow its unseen ones.
      */
     seen?: Iterable<string>;
-    /** The client's own story rotation, for a session with no server lead: a story shown RADAR_REST_AFTER times with no open is skipped. */
+    /** The client's own story rotation: a story shown RADAR_REST_AFTER times with no open is skipped, the top's lead included (the session's own pick leads instead). */
     seenClusters?: ReadonlyMap<string, DiscoverySeenCluster>;
     /** A visitor's rotation bucket (e.g. floor(now / 15 min)): page 0's story rotates among the breaking stories by it. */
     bucket?: number;
 }
+/** What a Discover feed session reads (`discovery.createFeed`, and each session of `discovery.createProgressiveFeed`). */
+export interface DiscoveryFeedOptions extends DiscoveryFeedSessionOptions {
+    /** The app's network catalog (`protocols.publicNetworks()`): each network with `public_trends` is read. */
+    networks: SocialNetwork[];
+    /** A browse category id. */
+    category?: string;
+    /** 'all' (or none) for every network, 'minds', or one network's protocol. */
+    source?: string;
+    learning?: DiscoveryLearning;
+    recommend?: DiscoveryRecommendationSources;
+    /** A Politics choice, as `posts.list` takes it: it goes on every Minds read (and the top's read). */
+    compass?: string;
+}
 export type DiscoveryItem = DiscoveryPostItem | {
     key: string;
     kind: 'group';
@@ -398,6 +419,15 @@ export declare const isDiscoveryPost: (item: DiscoveryItem) => item is Discovery
 export declare const RECOMMENDATION_MAX_ITEMS = 6;
 /** Clusters read from the radar per session; the server never holds more. */
 export declare const RADAR_MAX_CLUSTERS = 40;
+/**
+ * In a category, a topics network's topic pages in a row that showed nothing new, after which its other topics are
+ * passed over without a call (its index stream is still read); and an index stream's pages in a row that showed nothing
+ * new, on the last of which the stream ends. Live on 2026-09-27 Bluesky's catalog was the same 25 topics in every
+ * category and off-topic pages carried a cursor: Food's feed made 42 trend-feed calls of 1-2 s in 24 bottom hits for
+ * nothing. The server ends a stream after three empty pages too, but it counts what it served, not what this session
+ * had not shown yet.
+ */
+export declare const DISCOVERY_EMPTY_TOPIC_PAGES = 3;
 /** How long one source's read may take before the page goes on without it (DiscoveryFeedSession). */
 export declare const DISCOVERY_SOURCE_TIMEOUT_MS = 15000;
 /**
@@ -535,13 +565,20 @@ export declare class DiscoveryFeedSession {
     retryFailed(): void;
     next(): Promise<DiscoveryFeedPage>;
     private read;
+    /** An open-network post in the member's seen set (options.seen: '<protocol>/<nativeId>', an ActivityPub id also without https://). */
+    private metNetworkPost;
     /**
      * One read of a topics network: the next topic page that carries posts. A topic the provider no
      * longer lists (Bluesky rotates its trends between the catalog read and the walk through it) is
-     * that topic's end, not the network's failure; a topic page with nothing in the category is
-     * walked past too, and its continuation kept, so the page reaches a topic that carries posts
-     * instead of spending a round on each empty one. Bounded by TOPIC_WALK reads and TOPIC_WALK_MS;
-     * a walk that stops short has moved the stream on, and the next read continues from there.
+     * that topic's end, not the network's failure; a topic page with nothing new is walked past too,
+     * so the page reaches a topic that carries posts instead of spending a round on each empty one.
+     * Bounded by TOPIC_WALK reads and TOPIC_WALK_MS; a walk that stops short has moved the stream on,
+     * and the next read continues from there.
+     *
+     * In a category (DISCOVERY_EMPTY_TOPIC_PAGES): a topic page that shows nothing new ends that topic
+     * (its provider cursor is dropped: more of an off-category topic is more of the same), after that
+     * many such pages in a row the network's other topics are passed over without a call (its index
+     * stream is still read), and an index stream ends on its that-many-th page in a row with nothing new.
      */
     private walkTopics;
     private readPage;
@@ -571,7 +608,8 @@ export declare class DiscoveryFeedSession {
      * 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.
+     * items follow the unseen ones. Each placed item says its place in the whole top (TopReady.positions), so the items
+     * the sessions of one progressive feed place never share a place.
      */
     private placeTop;
     /** The story's members as feed items, read once per story and bounded to three seconds; a failed read is simply none. */
@@ -587,6 +625,8 @@ export declare class DiscoveryResource {
     private curator?;
     private http?;
     private feeds?;
+    /** One share of top reads for this client's viewer: a progressive feed's sessions read the top once between them. */
+    private readonly topShare;
     constructor(posts: PostsResource, protocols: ProtocolsResource, curator?: Pick<CuratorResource, "forYou"> | undefined, http?: Pick<HttpClient, "get" | "post"> | undefined, feeds?: Pick<FeedsResource, "top"> | undefined);
     /**
      * Suggestions for the signed-in viewer from the app's one recommender: active or warm members, groups
@@ -652,12 +692,15 @@ export declare class DiscoveryResource {
      * 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: {
-        networks: SocialNetwork[];
-        category?: string;
-        source?: string;
-        learning?: DiscoveryLearning;
-        recommend?: DiscoveryRecommendationSources;
-        compass?: string;
-    } & DiscoveryFeedSessionOptions): DiscoveryFeedSession;
+    createFeed(options: DiscoveryFeedOptions): DiscoveryFeedSession;
+    /**
+     * Discover's feed, handed on as each network answers rather than as a page that waits for its slowest network: one
+     * `createFeed` session per source (Minds with the radar and suggestions, one per network with `public_trends`), each
+     * page a `DiscoveryPart` the moment it lands (createProgressiveFeed). The first load is held until Minds and one other
+     * network answered, or FIRST_SCREEN_MS after the first answer, and arrives as one composed first screen
+     * (composeFirstScreen). `top`, `seen`, `seenClusters` and `bucket` reach every session; the top is read once per
+     * open (one session token) and, for this client, not asked again for five minutes after it answers 404.
+     * `settings`: `perSource`, `firstScreen`, `firstScreenMs` (VISITOR_FIRST_SCREEN_MS for a visitor), `onLanded`.
+     */
+    createProgressiveFeed(options: DiscoveryFeedOptions, settings?: ProgressiveFeedSettings): ProgressiveDiscoveryFeed;
 }

package/dist/resources/discovery.js

@@ -1,3 +1,10 @@
+import { readFalloverSteps } from './discovery-fallover.js';
+import { createDiscoveryTopShare, createProgressiveFeed } from './discovery-progressive.js';
+export * from './discovery-fallover.js';
+export * from './discovery-first-screen.js';
+export * from './discovery-merge.js';
+export * from './discovery-progressive.js';
+export * from './discovery-safety.js';
 export const isDiscoveryPost = (item) => item.kind === 'minds' || item.kind === 'social';
 /** At most this many candidates per recommendation module. */
 export const RECOMMENDATION_MAX_ITEMS = 6;
@@ -32,6 +39,15 @@ const TOPIC_WALK_MS = 8000;
  * new counts as an empty topic.
  */
 const INDEX_CURSOR = 'idx:tf:';
+/**
+ * In a category, a topics network's topic pages in a row that showed nothing new, after which its other topics are
+ * passed over without a call (its index stream is still read); and an index stream's pages in a row that showed nothing
+ * new, on the last of which the stream ends. Live on 2026-09-27 Bluesky's catalog was the same 25 topics in every
+ * category and off-topic pages carried a cursor: Food's feed made 42 trend-feed calls of 1-2 s in 24 bottom hits for
+ * nothing. The server ends a stream after three empty pages too, but it counts what it served, not what this session
+ * had not shown yet.
+ */
+export const DISCOVERY_EMPTY_TOPIC_PAGES = 3;
 /** How long one source's read may take before the page goes on without it (DiscoveryFeedSession). */
 export const DISCOVERY_SOURCE_TIMEOUT_MS = 15_000;
 /**
@@ -124,6 +140,19 @@ const RADAR_SOCIAL_KINDS = new Set(['bluesky', 'activitypub', 'nostr']);
 const httpUrl = (value) => typeof value === 'string' && value.length <= 4096 && /^https?:\/\//i.test(value);
 const countOf = (value) => typeof value === 'number' && Number.isSafeInteger(value) && value >= 0 ? value : null;
 const dimension = (value) => typeof value === 'number' && Number.isSafeInteger(value) && value > 0 ? value : undefined;
+/** A story's outlets as the server counted them (StoryOutlets), or null when absent (an older server) or when its buckets do not sum to its total. */
+function storyOutletsOf(value) {
+    if (!value || typeof value !== 'object')
+        return null;
+    const o = value;
+    const total = countOf(o.total);
+    const mainstream = countOf(o.mainstream);
+    const independent = countOf(o.independent);
+    const other = countOf(o.other);
+    if (total === null || mainstream === null || independent === null || other === null || mainstream + independent + other !== total)
+        return null;
+    return { total, mainstream, independent, other };
+}
 /** Validate one radar cluster: bad or unexpected shapes are dropped, never rendered. Member keys are translated to this session's key format. */
 function radarCluster(value) {
     if (!value || typeof value !== 'object')
@@ -139,6 +168,8 @@ function radarCluster(value) {
     const independent = countOf(laneMix.independent);
     if (mainstream === null || independent === null)
         return null;
+    // The server's one count for the story (0.7.71), which its page, World Today and the News section name too.
+    const outlets = storyOutletsOf(c.outlets);
     const normalized = c.velocity?.normalized;
     const sources = {};
     if (c.sources && typeof c.sources === 'object')
@@ -185,7 +216,8 @@ function radarCluster(value) {
         ? { type: media.type, url: media.url, ...(httpUrl(media.poster) ? { poster: media.poster } : {}), ...(dimension(media.width) && dimension(media.height) ? { width: dimension(media.width), height: dimension(media.height) } : {}),
             memberKey: translated.get(media.memberKey) ?? media.memberKey } : undefined;
     const theme = typeof c.theme === 'string' && /^[a-z][a-z0-9-]{0,31}$/.test(c.theme) ? c.theme : undefined;
-    return { id: c.id, label: c.label.slice(0, 300), kind: c.kind, ...(theme ? { theme } : {}), outletCount: mainstream + independent, laneMix: { mainstream, independent }, sources,
+    return { id: c.id, label: c.label.slice(0, 300), kind: c.kind, ...(theme ? { theme } : {}), outletCount: outlets ? outlets.total : mainstream + independent,
+        laneMix: outlets ? { mainstream: outlets.mainstream, independent: outlets.independent } : { mainstream, independent }, sources,
         velocity: { normalized: typeof normalized === 'number' && Number.isFinite(normalized) && normalized >= 0 ? normalized : 0 }, newestAt, ...(lead ? { lead } : {}), links, memberKeys };
 }
 /**
@@ -209,12 +241,19 @@ function storyCluster(value) {
                 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: [] };
+    // `sources.outlet` counts articles: a server that sends the story's outlets (0.7.71) is read for the number instead.
+    const outlets = storyOutletsOf(s.outlets);
+    return { id: s.id, label: s.label.slice(0, 300), kind: s.kind, ...(theme ? { theme } : {}), outletCount: outlets ? outlets.total : sources.outlet ?? 0,
+        laneMix: outlets ? { mainstream: outlets.mainstream, independent: outlets.independent } : { mainstream: 0, independent: 0 }, sources, velocity: { normalized: 0 }, newestAt, links: [], memberKeys: [] };
+}
+/** A story whose lead the member had on screen RADAR_REST_AFTER times without an open: it rests. */
+function restedStory(id, seenClusters) {
+    const seen = seenClusters?.get(id);
+    return !!seen && !seen.clicked && seen.n >= RADAR_REST_AFTER;
 }
 /** 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 rested = (cluster) => restedStory(cluster.id, options.seenClusters);
     const unused = clusters.filter(candidate => !options.used?.has(candidate.id) && !rested(candidate));
     if (page !== 0)
         return unused.find(candidate => candidate.kind !== 'breaking');
@@ -285,31 +324,12 @@ function laneItem(value, protocol) {
         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;
-/**
- * The Minds read's `meta.fallover`, step by step. A step of a kind this SDK knows (`feed` included, 0.7.60) that carries
- * the fields its kind declares is kept as the server sent it; a step of a kind a later server added, or a malformed
- * one, is left out and never guessed at, so every step a page reports is a FalloverStep. Undefined when the page has
- * no list (a server before the contract, or a feed that is not a category's).
- */
-function readFallover(value) {
-    if (!Array.isArray(value))
-        return undefined;
-    return value.filter((raw) => {
-        if (!raw || typeof raw !== 'object')
-            return false;
-        const step = raw;
-        switch (step.kind) {
-            case 'category_older': return filled(step.category) && filled(step.cursor);
-            case 'category_network': return filled(step.category);
-            case 'category': return filled(step.category) && typeof step.via === 'string' && FALLOVER_VIA.has(step.via);
-            case 'for_you':
-            case 'all': return true;
-            case 'feed': return filled(step.ref);
-            default: return false;
-        }
-    });
+/** The refs a member's seen set may hold for a top item, as the app records visible views. */
+function topItemSeenRefs(value) {
+    const target = (value?.target ?? {});
+    if (target.kind === 'post' && idString(target.id))
+        return seenRefsOf('minds', target.id);
+    return target.kind === 'network_post' && typeof target.protocol === 'string' && idString(target.nativeId) ? seenRefsOf(target.protocol, target.nativeId) : [];
 }
 const ordinary = { version: 'discovery-layout-v1', presentation: 'posts', source: 'fallback' };
 const key = (protocol, id) => JSON.stringify([protocol, id]);
@@ -429,7 +449,7 @@ export class DiscoveryFeedSession {
                     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);
+                const fallover = readFalloverSteps(response.meta.fallover);
                 if (fallover)
                     stream.fallover = fallover;
                 const items = response.data.map(post => ({ key: key('minds', post.id), kind: 'minds', post }));
@@ -470,7 +490,9 @@ export class DiscoveryFeedSession {
             // Outside a category the catalog's previews are this page. In a category a preview is not
             // judged to be in it, so the catalog carries no card: the read walks into its topics now,
             // 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 }] : []);
+            // A preview the member already saw is left out; its topic stays.
+            const previews = data.items.flatMap(topic => !this.category && topic.preview && !this.metNetworkPost(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, ...(previews.length ? { previews: true } : {}) };
             return this.walkTopics(stream, params, validatePosts, partial, started);
@@ -481,19 +503,43 @@ export class DiscoveryFeedSession {
         if (stream.cursor)
             stream.used = [...stream.used, stream.cursor].slice(-32);
         stream.cursor = next;
-        return { items: data.items.map(post => ({ key: key(post.protocol, post.nativeId), kind: 'social', post })), layout: data.discovery ?? ordinary, partial: data.categoryFilter?.status === 'partial' };
+        // A post the member already saw is left out (the top's lanes are the top's own, ranked by impressions). Each kept
+        // post keeps its own window's layout.
+        const kept = data.items.flatMap((post, index) => this.metNetworkPost(post) ? [] : [{ post, index }]);
+        const layout = data.discovery ?? ordinary;
+        return { items: kept.map(({ post }) => ({ key: key(post.protocol, post.nativeId), kind: 'social', post })), layout, partial: data.categoryFilter?.status === 'partial',
+            ...(kept.length !== data.items.length ? { layouts: kept.map(({ index }) => windowLayout(layout, index)) } : {}) };
+    }
+    /** An open-network post in the member's seen set (options.seen: '<protocol>/<nativeId>', an ActivityPub id also without https://). */
+    metNetworkPost(post) {
+        if (!this.appSeen || typeof post.protocol !== 'string' || typeof post.nativeId !== 'string' || !post.protocol || !post.nativeId)
+            return false;
+        return seenRefsOf(post.protocol, post.nativeId).some(ref => this.appSeen.has(ref));
     }
     /**
      * One read of a topics network: the next topic page that carries posts. A topic the provider no
      * longer lists (Bluesky rotates its trends between the catalog read and the walk through it) is
-     * that topic's end, not the network's failure; a topic page with nothing in the category is
-     * walked past too, and its continuation kept, so the page reaches a topic that carries posts
-     * instead of spending a round on each empty one. Bounded by TOPIC_WALK reads and TOPIC_WALK_MS;
-     * a walk that stops short has moved the stream on, and the next read continues from there.
+     * that topic's end, not the network's failure; a topic page with nothing new is walked past too,
+     * so the page reaches a topic that carries posts instead of spending a round on each empty one.
+     * Bounded by TOPIC_WALK reads and TOPIC_WALK_MS; a walk that stops short has moved the stream on,
+     * and the next read continues from there.
+     *
+     * In a category (DISCOVERY_EMPTY_TOPIC_PAGES): a topic page that shows nothing new ends that topic
+     * (its provider cursor is dropped: more of an off-category topic is more of the same), after that
+     * many such pages in a row the network's other topics are passed over without a call (its index
+     * stream is still read), and an index stream ends on its that-many-th page in a row with nothing new.
      */
     async walkTopics(stream, params, validatePosts, partial, started) {
         const topics = stream.topics;
+        const inCategory = !!this.category;
+        /** A category page's outcome for the network's run of pages that showed nothing new. */
+        const count = (showsSomething) => { if (inCategory)
+            stream.emptyTopics = showsSomething ? 0 : (stream.emptyTopics ?? 0) + 1; };
+        const passedOver = () => inCategory && (stream.emptyTopics ?? 0) >= DISCOVERY_EMPTY_TOPIC_PAGES;
         for (let reads = 0; reads < TOPIC_WALK && Date.now() - started < TOPIC_WALK_MS; reads++) {
+            // Past the run, the network's provider topics are passed over without a call; its index stream is still read.
+            while (topics[0] && passedOver() && !topics[0].cursor?.startsWith(INDEX_CURSOR))
+                topics.shift();
             const topic = topics[0];
             if (!topic)
                 break;
@@ -503,8 +549,10 @@ export class DiscoveryFeedSession {
             const indexContinuation = !!topic.cursor?.startsWith(INDEX_CURSOR);
             const response = await reach(this.protocols.getPublicTrendFeed({ ...params, protocol: stream.protocol, topic: topic.topic, cursor: topic.cursor }, NO_RETRY))
                 .catch((error) => {
-                if (isGone(error))
+                if (isGone(error)) {
+                    count(false);
                     return null;
+                }
                 if (indexContinuation) {
                     stream.indexStarted = false;
                     return null;
@@ -518,23 +566,42 @@ export class DiscoveryFeedSession {
             validatePosts(data);
             if (data.trend.protocol !== stream.protocol || data.trend.nativeId !== topic.topic)
                 throw new Error('Invalid discovery topic');
-            const next = data.cursor;
-            // A provider cursor is always kept. An index cursor from a provider page starts the network's one index
-            // stream: queued the first time only, since every later start would re-read the same stream from its top.
+            // What this page shows that no page of the session showed: the index serves the same posts to every gone or
+            // empty topic, so an index page's posts already shown are left out, and a page with nothing new is an empty topic.
+            const showsSomething = data.items.some(post => !this.seen.has(key(post.protocol, post.nativeId)));
+            count(showsSomething);
+            let next = data.cursor ?? null;
+            // In a category, a provider page with nothing new ends its topic.
+            if (inCategory && !showsSomething && next && !next.startsWith(INDEX_CURSOR))
+                next = null;
+            // An index stream (a page that starts or continues it) ends on its DISCOVERY_EMPTY_TOPIC_PAGES-th page in a row
+            // with nothing new; the run travels with the cursor, so a page read again counts once.
+            let indexRun;
+            if (next?.startsWith(INDEX_CURSOR)) {
+                indexRun = showsSomething ? 0 : (indexContinuation ? topic.indexRun ?? 0 : 0) + 1;
+                if (indexRun >= DISCOVERY_EMPTY_TOPIC_PAGES)
+                    next = null;
+            }
+            // A provider cursor is kept. An index cursor from a provider page starts the network's one index stream: queued
+            // the first time only, since every later start would re-read the same stream from its top.
             const indexed = !!data.sourceIndex;
-            const startsIndex = !!next?.startsWith(INDEX_CURSOR) && !topic.cursor?.startsWith(INDEX_CURSOR);
+            const startsIndex = !!next?.startsWith(INDEX_CURSOR) && !indexContinuation;
             if (next && next !== topic.cursor && !topic.used.includes(next) && !(startsIndex && stream.indexStarted)) {
-                topics.push({ topic: topic.topic, cursor: next, used: [...topic.used, ...(topic.cursor ? [topic.cursor] : [])].slice(-32) });
+                topics.push({ topic: topic.topic, cursor: next, used: [...topic.used, ...(topic.cursor ? [topic.cursor] : [])].slice(-32),
+                    ...(indexRun !== undefined ? { indexRun } : {}) });
                 if (startsIndex)
                     stream.indexStarted = true;
             }
             partial ||= data.categoryFilter?.status === 'partial';
-            const items = indexed ? data.items.filter(post => !this.seen.has(key(post.protocol, post.nativeId))) : data.items;
+            // A post the member already saw is left out too (options.seen).
+            const items = (indexed ? data.items.filter(post => !this.seen.has(key(post.protocol, post.nativeId))) : data.items).filter(post => !this.metNetworkPost(post));
             if (items.length) {
                 stream.done = !topics.length;
                 return { items: items.map(post => ({ key: key(post.protocol, post.nativeId), kind: 'social', post })), layout: data.discovery ?? ordinary, partial };
             }
         }
+        while (topics[0] && passedOver() && !topics[0].cursor?.startsWith(INDEX_CURSOR))
+            topics.shift();
         stream.done = !topics.length;
         return { items: [], layout: ordinary, partial };
     }
@@ -784,8 +851,21 @@ export class DiscoveryFeedSession {
             if (lane.length)
                 lanes.set(protocol, lane);
         }
-        const lead = this.radar ? storyCluster(value.lead) : null;
+        // A lead story the member passed over RADAR_REST_AFTER times without an open is left to the session's own pick,
+        // which rests it: with the top on, the same story led every visit.
+        const named = this.radar ? storyCluster(value.lead) : null;
+        const lead = named && !restedStory(named.id, this.seenClusters) ? named : null;
         const impressions = (value.meta?.flag?.impressions) === 'on';
+        // Each item's place in the whole top: the server's order, with the member's seen items after the unseen ones when
+        // that order did not use impressions. A session places only its own network's items, so it never counts from 0.
+        const ordered = value.items.filter(item => !!item && typeof item === 'object' && idString(item.ref));
+        const met = (item) => !!this.appSeen && topItemSeenRefs(item).some(ref => this.appSeen.has(ref));
+        const positions = new Map();
+        for (const item of impressions || !this.appSeen ? ordered : [...ordered.filter(item => !met(item)), ...ordered.filter(met)]) {
+            const ref = item.ref;
+            if (!positions.has(ref))
+                positions.set(ref, positions.size);
+        }
         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.
@@ -812,13 +892,14 @@ export class DiscoveryFeedSession {
         for (const item of [...minds, ...network.flat()])
             if (item && !posts.has(item.key))
                 posts.set(item.key, item);
-        return { rows, posts, lanes, lead, impressions };
+        return { rows, posts, lanes, lead, impressions, positions };
     }
     /**
      * 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.
+     * items follow the unseen ones. Each placed item says its place in the whole top (TopReady.positions), so the items
+     * the sessions of one progressive feed place never share a place.
      */
     placeTop(top, selected, reads) {
         for (const [protocol, lane] of top.lanes) {
@@ -839,7 +920,7 @@ export class DiscoveryFeedSession {
             const found = top.posts.get(row.key) ?? carried.get(row.key);
             if (!found || this.seen.has(row.key))
                 continue;
-            const position = placed.length;
+            const position = top.positions.get(row.ref) ?? 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);
@@ -963,6 +1044,8 @@ export class DiscoveryResource {
     curator;
     http;
     feeds;
+    /** One share of top reads for this client's viewer: a progressive feed's sessions read the top once between them. */
+    topShare = createDiscoveryTopShare();
     constructor(posts, protocols, curator, http, feeds) {
         this.posts = posts;
         this.protocols = protocols;
@@ -1063,6 +1146,23 @@ export class DiscoveryResource {
         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 } : {}) });
     }
+    /**
+     * Discover's feed, handed on as each network answers rather than as a page that waits for its slowest network: one
+     * `createFeed` session per source (Minds with the radar and suggestions, one per network with `public_trends`), each
+     * page a `DiscoveryPart` the moment it lands (createProgressiveFeed). The first load is held until Minds and one other
+     * network answered, or FIRST_SCREEN_MS after the first answer, and arrives as one composed first screen
+     * (composeFirstScreen). `top`, `seen`, `seenClusters` and `bucket` reach every session; the top is read once per
+     * open (one session token) and, for this client, not asked again for five minutes after it answers 404.
+     * `settings`: `perSource`, `firstScreen`, `firstScreenMs` (VISITOR_FIRST_SCREEN_MS for a visitor), `onLanded`.
+     */
+    createProgressiveFeed(options, settings = {}) {
+        const feeds = this.feeds;
+        const compass = options.compass;
+        const top = options.top && !options.top.read && feeds
+            ? { ...options.top, read: this.topShare(params => feeds.top({ ...params, ...(compass ? { compass } : {}) }, NO_RETRY), compass ?? '') }
+            : options.top;
+        return createProgressiveFeed(this, { ...options, ...(top ? { top } : {}) }, settings);
+    }
 }
 /** A read bounded to three seconds; a late or failed one resolves to `fallback`, never an error. */
 function withDeadline(read, fallback, ms = 3000) {

package/dist/resources/feeds.d.ts

@@ -1,5 +1,5 @@
 import type { HttpClient } from '../client.js';
-import type { CompassFilterMeta } from '../types.js';
+import type { CompassFilterMeta, StoryOutlets } from '../types.js';
 /**
  * The top of a feed: what the member (or a visitor) is most likely to engage with, rotated by what they have seen.
  * `feeds.top` and `feeds.stories` read it for a member with their own key of the app; `feeds.publicTop` reads a
@@ -104,6 +104,8 @@ export interface FeedStory {
      */
     political?: boolean;
     sources: Partial<Record<'outlet' | 'hackernews' | 'bluesky' | 'activitypub' | 'nostr' | 'minds', number>>;
+    /** How many outlets reported it (StoryOutlets): the number every surface names for the story. Absent from a server older than 0.7.71. */
+    outlets?: StoryOutlets;
     media: {
         images: number;
         videos: number;