@recursiv/sdk 0.7.63 → 0.7.65

package/README.md

@@ -95,6 +95,7 @@ for await (const chunk of r.agents.chatStream(agent.id, { message: 'Hello!' }))
 |----------|------------|
 | `r.posts` | `create`, `update`, `list`, `liked`, `bookmarked`, `bookmark`, `unbookmark`, `search`, `replies`, `react` |
 | `r.bookmarks` | `save`, `unsave`, `posts`, `list`, `keys`, `merge` — the member's saved posts, open-network posts and articles, synced across devices |
+| `r.feeds` | `top` (what the member is most likely to engage with, rotated by what they saw, with open-network lanes and the lead story), `stories` (the story tail), `publicTop` (a visitor's top, keyless and edge-cacheable) |
 | `r.communities` | `create`, `join`, `search`, `members` |
 | `r.chat` | `send`, `dm`, `createGroup` (`encrypted: true` for an end-to-end encrypted group, 0.7.59), `messages` (cursor paging), `acceptRequest`, `declineRequest`, `leave`, `deleteConversation`; a private group's admin: `addMembers`, `removeMember`, `updateGroup` (0.7.59) |
 | `r.tags` | `create`, `list` |
@@ -669,6 +670,39 @@ and says whether the member is personalized yet (`meta.personalized`). With a
 `category` (the member's first), the session also reads open-network posts from it;
 without, it is Minds only. It never carries the radar.
 
+### The top of a feed
+
+`sdk.feeds.top({ ref, limit?, session?, compass? })` answers the top of a feed for the
+signed-in member, read with their own key of the app (`ref`: `builtin:all`,
+`category:<id>`, `following`, `watch` or `story:<cluster id>`): `items` (the posts most
+likely to be engaged with, often video, rotated by what the member has seen), `networks`
+(Bluesky, Fediverse and Nostr lanes of up to six posts, each with a `card` to draw and no
+URL on its network), `lead` (the story the feed should open with) and `meta` (`short`,
+`safety`, whether the order used impressions). Every item's `target` is in the app: a
+post id, `/social/post/<protocol>/<id>`, or a story id. `sdk.feeds.stories({ after?, limit? })`
+is the story tail from the same ranker. `sdk.feeds.publicTop({ projectId, ref?, limit?, compass? })`
+is a visitor's top (safe items only, the same for every visitor in one 15-minute bucket),
+read with no credential so the edge can hold it. Each answers 404 while the app's operator
+has it off. Send `block: 'top'` and the item's position with a visible view of a top item.
+
+A feed session opens with it when asked: `createFeed({ networks, top: { ref, session? }, seen,
+seenClusters?, bucket? })` (or `new DiscoveryFeedSession(..., { top: { ref, read, post? }, seen })`
+with your own readers). The top's read starts with the first page's reads, and the top holds
+the page at most 1.5 s from its start, the reads of its items' posts included; a top that is
+off, fails or is late leaves the session exactly as it is without one. The radar's story reads
+its posts as soon as the radar answers, whatever the top does. When it answers, page 0 opens with the story it leads with, then its items (each item
+carries `top: { ref, position, block }`, a lane entry also `lane`), and its lanes stand in
+for the networks' first reads. Minds items the first hot page does not carry are read by id
+once, within the same 1.5 s (`top.post`, or `GET /posts/:id` without retries). `seen` (Minds post ids and
+`<protocol>/<nativeId>` refs the member already saw) leaves those posts out of the hot pages,
+and no hot page repeats a top item; a hot page left under five posts walks on, up to three
+more pages, and the feed's `fallover` still reports when the ranking ends. Without impressions
+in the top's order, the member's seen top items follow the unseen ones. With no server lead,
+`seenClusters` (`Map<id, { n, clicked }>`) skips a story shown three times without an open,
+and a visitor's `bucket` rotates page 0's story among the breaking ones
+(`pickRadarCluster` is the same rule on its own). With none of these options a session is
+unchanged.
+
 Both take a Politics choice, `compass` (`all`, `mix`, `hide`, or cells in the order
 `lo,co,ro,lm,cm,rm,ll,cl,rl`, optionally `np`), and send it with every Minds read
 (`posts.list` and `curator.forYou` take it too). Each such page says what it did in

package/dist/feed-definition.d.ts

@@ -17,7 +17,11 @@ export declare const FEED_SOURCES_MAX = 50;
 export declare const FEED_DEFINITION_MAX_BYTES: number;
 export declare const FEED_SOURCE_KINDS: readonly ["category", "tag", "account", "community", "collection", "list", "story", "bsky_feed", "bsky_list", "bsky_starterpack", "nostr_set"];
 export type FeedSourceKind = typeof FEED_SOURCE_KINDS[number];
-export declare const FEED_RANKING_MODES: readonly ["hot", "new", "top", "for_you", "viral"];
+/**
+ * 'engagement' ranks by predicted engagement for the reader: the top of a feed (`feeds.top`). Like For you
+ * and viral it reaches past the sources on the reader's behalf.
+ */
+export declare const FEED_RANKING_MODES: readonly ["hot", "new", "top", "for_you", "viral", "engagement"];
 export type FeedRankingMode = typeof FEED_RANKING_MODES[number];
 export declare const FEED_RANKING_RANGES: readonly ["24h", "7d", "30d", "1y"];
 export type FeedRankingRange = typeof FEED_RANKING_RANGES[number];

package/dist/feed-definition.js

@@ -19,7 +19,11 @@ export const FEED_SOURCE_KINDS = [
     'category', 'tag', 'account', 'community', 'collection', 'list', 'story',
     'bsky_feed', 'bsky_list', 'bsky_starterpack', 'nostr_set',
 ];
-export const FEED_RANKING_MODES = ['hot', 'new', 'top', 'for_you', 'viral'];
+/**
+ * 'engagement' ranks by predicted engagement for the reader: the top of a feed (`feeds.top`). Like For you
+ * and viral it reaches past the sources on the reader's behalf.
+ */
+export const FEED_RANKING_MODES = ['hot', 'new', 'top', 'for_you', 'viral', 'engagement'];
 export const FEED_RANKING_RANGES = ['24h', '7d', '30d', '1y'];
 export const FEED_MEDIA = ['any', 'images', 'video', 'longread'];
 export const FEED_NETWORKS = ['minds', 'bluesky', 'activitypub', 'nostr'];

package/dist/index.d.ts

@@ -62,6 +62,7 @@ import { ModerationResource } from './resources/moderation.js';
 import { LinkPreviewResource } from './resources/link-preview.js';
 import { SearchResource } from './resources/search.js';
 import { BookmarksResource } from './resources/bookmarks.js';
+import { FeedsResource } from './resources/feeds.js';
 import { AccountsResource } from './resources/accounts.js';
 import { RealtimeClient } from './realtime.js';
 import type { RecursivConfig } from './types.js';
@@ -121,6 +122,8 @@ export declare class Recursiv {
     readonly jobs: JobsResource;
     readonly curator: CuratorResource;
     readonly discovery: DiscoveryResource;
+    /** The top of a feed: what the member (or a visitor) is most likely to engage with, rotated by what they have seen. */
+    readonly feeds: FeedsResource;
     readonly video: VideoResource;
     readonly appSubscriptions: AppSubscriptionsResource;
     readonly boosts: BoostsResource;
@@ -201,6 +204,8 @@ export { LinkPreviewResource } from './resources/link-preview.js';
 export { SEARCH_SECTIONS, SearchResource } from './resources/search.js';
 export type { SearchAnswer, SearchGroup, SearchOmitReason, SearchParams, SearchPerson, SearchRelated, SearchResponse, SearchSection, SearchStory, SearchTopic } from './resources/search.js';
 export { BOOKMARK_MERGE_MAX_ITEMS, BookmarksResource } from './resources/bookmarks.js';
+export { FEED_TOP_NETWORKS, FeedsResource } from './resources/feeds.js';
+export type { FeedStoriesParams, FeedStoriesResponse, FeedStory, FeedTopExplain, FeedTopItem, FeedTopMeta, FeedTopNetwork, FeedTopNetworkCard, FeedTopNetworkEntry, FeedTopParams, FeedTopResponse, FeedTopTarget, PublicFeedTopMeta, PublicFeedTopParams, PublicFeedTopResponse, } from './resources/feeds.js';
 export type { BookmarkedPost, BookmarkInput, BookmarkItem, BookmarkKey, BookmarkKeyRow, BookmarkKind, BookmarkMergeItem, BookmarkMergeResult, BookmarkProtocol, BookmarkRequestOptions, BookmarksPage, SavedBookmark, UnsavedBookmark, } from './resources/bookmarks.js';
 export { AccountsResource } from './resources/accounts.js';
 export type { SiblingAccount, SiblingAccountsResponse, SwitchAccountResult, } from './resources/accounts.js';

package/dist/index.js

@@ -63,6 +63,7 @@ import { ModerationResource } from './resources/moderation.js';
 import { LinkPreviewResource } from './resources/link-preview.js';
 import { SearchResource } from './resources/search.js';
 import { BookmarksResource } from './resources/bookmarks.js';
+import { FeedsResource } from './resources/feeds.js';
 import { AccountsResource } from './resources/accounts.js';
 import { RealtimeClient } from './realtime.js';
 export class Recursiv {
@@ -122,6 +123,8 @@ export class Recursiv {
     jobs;
     curator;
     discovery;
+    /** The top of a feed: what the member (or a visitor) is most likely to engage with, rotated by what they have seen. */
+    feeds;
     video;
     appSubscriptions;
     boosts;
@@ -188,7 +191,8 @@ export class Recursiv {
         this.webhooks = new WebhooksResource(client);
         this.jobs = new JobsResource(client);
         this.curator = new CuratorResource(client);
-        this.discovery = new DiscoveryResource(this.posts, this.protocols, this.curator, client);
+        this.feeds = new FeedsResource(client);
+        this.discovery = new DiscoveryResource(this.posts, this.protocols, this.curator, client, this.feeds);
         this.video = new VideoResource(client);
         this.appSubscriptions = new AppSubscriptionsResource(client);
         this.boosts = new BoostsResource(client);
@@ -254,6 +258,7 @@ export { ModerationResource } from './resources/moderation.js';
 export { LinkPreviewResource } from './resources/link-preview.js';
 export { SEARCH_SECTIONS, SearchResource } from './resources/search.js';
 export { BOOKMARK_MERGE_MAX_ITEMS, BookmarksResource } from './resources/bookmarks.js';
+export { FEED_TOP_NETWORKS, FeedsResource } from './resources/feeds.js';
 export { AccountsResource } from './resources/accounts.js';
 export { OrganizationSettingsResource } from './resources/organization-settings.js';
 export { ProjectSettingsResource } from './resources/project-settings.js';

package/dist/resources/discovery.d.ts

@@ -2,6 +2,7 @@ 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 { 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 type DiscoveryRecommendationKind = 'groups' | 'people' | 'tags';
@@ -284,15 +285,97 @@ export interface DiscoveryRadarMemberSources {
     }>;
 }
 export type DiscoveryRadarPresentation = 'breaking' | 'story';
+/** Where an item sits in the top of the feed: set only on the items a session's top placed on its first page. */
+export interface DiscoveryTopPlacement {
+    /** The item's ref in the top (a Minds post id, or '<protocol>/<nativeId>'): what a visible view of it names. */
+    ref: string;
+    /** Its position in the top, or in its network's lane. */
+    position: number;
+    /** 'top' for the first 10: send `block: 'top'` and the position with a visible view of one (an impression). */
+    block: 'top' | 'below';
+    /** Set on an open-network lane's entry: its network. */
+    lane?: FeedTopNetwork;
+}
 export type DiscoveryPostItem = {
     key: string;
     kind: 'minds';
     post: Post;
+    top?: DiscoveryTopPlacement;
 } | {
     key: string;
     kind: 'social';
     post: SocialPost;
+    top?: DiscoveryTopPlacement;
 };
+/** What a session reads of a top answer: the member route's (`feeds.top`) and the visitor read's (`feeds.publicTop`) common shape. */
+export interface DiscoveryTopAnswer {
+    items: FeedTopItem[];
+    networks: Partial<Record<FeedTopNetwork, FeedTopNetworkEntry[]>> | null;
+    lead: FeedStory | null;
+    meta?: {
+        flag?: {
+            impressions?: string;
+        };
+    };
+}
+/** Reads the top of the session's feed. */
+export type DiscoveryTopSource = (params: {
+    ref: string;
+    limit: number;
+    session?: string;
+}) => Promise<DiscoveryTopAnswer>;
+/** The top of the feed a session opens with (`discovery.createFeed({ top })`, or DiscoveryFeedSession's options). */
+export interface DiscoveryTopOptions {
+    /**
+     * The feed's ref as the reader takes it: `builtin:all`, `category:<id>`, `following`, `watch` or `story:<id>` for
+     * `feeds.top`; `all`, `watch` or `category:<id>` for `feeds.publicTop`.
+     */
+    ref: string;
+    /** Items asked for, 1..25 (default DISCOVERY_TOP_LIMIT). */
+    limit?: number;
+    /** The app's session token (`feeds.top` keeps one session's order stable with it). */
+    session?: string;
+    /** The reader. createFeed reads `feeds.top` (with its `compass`); a session built directly has no top without one. */
+    read?: DiscoveryTopSource;
+    /**
+     * Reads one Minds post by id, for a top item the first hot page does not carry, within the top's one deadline
+     * (DISCOVERY_TOP_TIMEOUT_MS from the page's start). Defaults to the session's radar Minds reader; createFeed passes
+     * `GET /posts/:id` without retries. Without either, a Minds top item shows only when the first hot page carries it.
+     */
+    post?: (id: string) => Promise<{
+        data: Post;
+    }>;
+}
+/** What a member saw of a radar story: how often its lead was on screen, and whether they ever opened it. */
+export interface DiscoverySeenCluster {
+    n: number;
+    clicked: boolean;
+}
+/** The options a session takes besides its readers. With none set, a session answers exactly what 0.7.63's did. */
+export interface DiscoveryFeedSessionOptions {
+    /**
+     * The top of the feed. Its read starts with the first page's reads, and it holds the page at most
+     * DISCOVERY_TOP_TIMEOUT_MS from the page's start, the reads of its items' posts included: a top that fails (404 while
+     * it is off, a network error, a timeout) leaves the session exactly as it is without one. The radar's own story reads
+     * its member posts as soon as the radar answers, whatever the top does; a different story the top leads with reads its
+     * own from the moment the top answers.
+     * When it answers, the first page opens with its items (each carrying `top`), its open-network lanes stand in for the
+     * networks' first reads (a topics network's previews), its lead is the page's story, and no later hot page repeats an
+     * item it placed.
+     */
+    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
+     * 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. */
+    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;
+}
 export type DiscoveryItem = DiscoveryPostItem | {
     key: string;
     kind: 'group';
@@ -325,6 +408,22 @@ export declare const DISCOVERY_SOURCE_TIMEOUT_MS = 15000;
  * "Minds posts didn't load" with Try again and which its Politics fallback (minds#1212) waits for.
  */
 export declare 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 declare const DISCOVERY_TOP_TIMEOUT_MS = 1500;
+/** Top items a session asks for unless its options say otherwise: the top block. */
+export declare const DISCOVERY_TOP_LIMIT = 10;
+/** A hot page the seen set (or the top) leaves under this many posts walks on to the next hot page... */
+export declare 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 declare const DISCOVERY_SEEN_WALK = 3;
+/** A story whose lead was on screen this many times with no open is skipped (DiscoveryFeedSessionOptions.seenClusters). */
+export declare 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 declare const RADAR_BUCKET_ROTATION = 5;
 /**
  * Whether a source's read failed for a reason that passes: it ran past its deadline, its call never got an answer (a
  * failed connection or an abort, as the session's read reports it), or the server answered 408, 425, 429 or 5xx (or no
@@ -332,6 +431,17 @@ export declare const DISCOVERY_SOURCE_RETRIES = 2;
  * checking it) and any other 4xx are the source's own failure and are not asked again.
  */
 export declare function transientSourceFailure(error: unknown): boolean;
+/** Page 0's story, else a later page's: the client's own pick, for a session with no lead from the top of the feed. */
+export interface RadarPickOptions {
+    /** Stories this session already showed. */
+    used?: ReadonlySet<string>;
+    /** What the member saw of each story: one shown RADAR_REST_AFTER times with no open is skipped. */
+    seenClusters?: ReadonlyMap<string, DiscoverySeenCluster>;
+    /** A visitor's bucket: page 0's story rotates by it among the RADAR_BUCKET_ROTATION best breaking stories (best stories when none is breaking). */
+    bucket?: number;
+}
+/** Page 0: the top breaking story, else the top story. Later pages: the next unused story that is not breaking. */
+export declare function pickRadarCluster(clusters: readonly DiscoveryCluster[], page: number, options?: RadarPickOptions): DiscoveryCluster | undefined;
 /** json-render Spec: values are references to authenticated SDK results, never
  * arbitrary executable components, links, generated text or provider markup. */
 export interface DiscoveryModule {
@@ -407,7 +517,21 @@ export declare class DiscoveryFeedSession {
     private radarLoading;
     /** Member reads per story, started as soon as the story is known and shared by whichever page shows it. */
     private memberReads;
-    constructor(posts: Pick<PostsResource, 'list'>, protocols: Pick<ProtocolsResource, 'getPublicTrends' | 'getPublicTrendFeed'>, networks: SocialNetwork[], category?: string | undefined, source?: string, learning?: DiscoveryLearning | undefined, recommend?: DiscoveryRecommendationSources | undefined, radar?: DiscoveryRadarSource, members?: DiscoveryRadarMemberSources | undefined);
+    /** The top of the feed (options.top with a reader), its read started with page 0's reads, and the keys it placed. */
+    private top?;
+    private topLoading;
+    /** The story the top leads with, once its answer is in (null: it names none); undefined until then. */
+    private topLead;
+    private topKeys;
+    /** What the member already saw (options.seen): left out of the Minds hot pages. */
+    private appSeen;
+    private seenClusters?;
+    private bucket?;
+    constructor(posts: Pick<PostsResource, 'list'>, protocols: Pick<ProtocolsResource, 'getPublicTrends' | 'getPublicTrendFeed'>, networks: SocialNetwork[], category?: string | undefined, source?: string, learning?: DiscoveryLearning | undefined, recommend?: DiscoveryRecommendationSources | undefined, radar?: DiscoveryRadarSource, members?: DiscoveryRadarMemberSources | undefined, options?: DiscoveryFeedSessionOptions);
+    /** The Minds hot pages leave out what the member saw or the top placed, and walk on past a page that leaves too little. */
+    private get filtering();
+    /** A Minds hot item the page leaves out: shown on an earlier page, placed by the top, or in the member's seen set. */
+    private hiddenFromHot;
     retryFailed(): void;
     next(): Promise<DiscoveryFeedPage>;
     private read;
@@ -421,10 +545,35 @@ export declare class DiscoveryFeedSession {
      */
     private walkTopics;
     private readPage;
-    /** Page 0: the top breaking cluster, else the top cluster. Every second later page: the next unused story or viral cluster. */
+    /**
+     * 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.
+     */
     private radarCluster;
-    /** 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). */
     private pickCluster;
+    /** 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. */
+    private leadOf;
+    /** 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). */
+    private topModule;
+    /**
+     * 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.
+     */
+    private loadTop;
+    /**
+     * 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.
+     */
+    private readyTop;
+    /**
+     * 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.
+     */
+    private placeTop;
     /** The story's members as feed items, read once per story and bounded to three seconds; a failed read is simply none. */
     private memberPosts;
     private readMembers;
@@ -437,7 +586,8 @@ export declare class DiscoveryResource {
     private protocols;
     private curator?;
     private http?;
-    constructor(posts: PostsResource, protocols: ProtocolsResource, curator?: Pick<CuratorResource, "forYou"> | undefined, http?: Pick<HttpClient, "get" | "post"> | undefined);
+    private feeds?;
+    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
      * with several posters, tags used by several people, open-network accounts or stories, overall or in one
@@ -497,6 +647,10 @@ export declare 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: {
         networks: SocialNetwork[];
@@ -505,5 +659,5 @@ export declare class DiscoveryResource {
         learning?: DiscoveryLearning;
         recommend?: DiscoveryRecommendationSources;
         compass?: string;
-    }): DiscoveryFeedSession;
+    } & DiscoveryFeedSessionOptions): DiscoveryFeedSession;
 }

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. */

package/dist/resources/feeds.d.ts

@@ -0,0 +1,228 @@
+import type { HttpClient } from '../client.js';
+import type { CompassFilterMeta } 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
+ * visitor's top keylessly. A feed session (`discovery.createFeed({ top })`) opens its first page with it.
+ *
+ * Every tap target is in the app: a Minds post by id, an open-network post by `/social/post/<protocol>/<id>`, a story
+ * by id. Nothing here is a URL on another network.
+ */
+/** The open networks whose lanes a top carries. */
+export type FeedTopNetwork = 'bluesky' | 'activitypub' | 'nostr';
+export declare const FEED_TOP_NETWORKS: readonly FeedTopNetwork[];
+/** Where a tap on an item goes, always in the app. `path` is the app's own page of a network post, never its URL there. */
+export type FeedTopTarget = {
+    kind: 'post';
+    id: string;
+} | {
+    kind: 'network_post';
+    protocol: string;
+    nativeId: string;
+    path: string;
+    readRef?: string;
+};
+/** Why an item is where it is. */
+export interface FeedTopExplain {
+    score: number;
+    engagement: {
+        source: string;
+        rate: number;
+    };
+    media: string;
+    origin: string;
+    /** Where the item came from: the Minds ranking, Watch's list, a radar story, the member's follows, or a network's trends. */
+    source: 'minds' | 'watch' | 'radar' | 'following' | 'trends';
+    /** 'safe' for everyone; 'open' only for a member who turned safe defaults off. */
+    label: 'safe' | 'open';
+    cluster: string | null;
+    topic: string | null;
+    /** 'demoted': the member viewed it in the last 6 hours (it sits below rank 20). A visitor's items are all 'fresh'. */
+    impression: 'fresh' | 'demoted';
+}
+/** One item of the top: a Minds post (`ref` is its id) or an open-network post (`ref` is '<protocol>/<nativeId>'). */
+export interface FeedTopItem {
+    ref: string;
+    kind: 'post' | 'network_post';
+    authorId: string;
+    target: FeedTopTarget;
+    position: number;
+    /** 'top' for the first 10: send `block: 'top'` and the position with a visible view of one (an impression). */
+    block: 'top' | 'below';
+    explain: FeedTopExplain;
+}
+/** What an app draws for an open-network lane entry. No URL on the post's network: the app opens it by `target.path`. */
+export interface FeedTopNetworkCard {
+    text: string;
+    createdAt: string;
+    author: {
+        nativeId: string;
+        handle: string;
+        displayName: string;
+        avatarUrl: string | null;
+    };
+    media: Array<{
+        type: 'image' | 'video';
+        url: string;
+        alt: string;
+        poster?: string;
+        width?: number;
+        height?: number;
+    }>;
+    counts: {
+        likes: number | null;
+        replies: number | null;
+        reposts: number | null;
+    };
+    sensitive: boolean;
+    /** The post quotes another; read the quote when the post is opened. */
+    hasQuote: boolean;
+}
+/** One entry of an open-network lane: up to six per network, ranked by engagement and rotated by impressions. */
+export interface FeedTopNetworkEntry extends FeedTopItem {
+    kind: 'network_post';
+    protocol: FeedTopNetwork;
+    card: FeedTopNetworkCard;
+}
+/** A story as the top names it: its id and in-app target, never an outlet's or a network's URL. */
+export interface FeedStory {
+    id: string;
+    /** 'cluster:<id>': what an impression of the story names. */
+    ref: string;
+    target: {
+        kind: 'story';
+        id: string;
+    };
+    label: string;
+    kind: 'breaking' | 'viral' | 'story';
+    breaking: boolean;
+    theme: string | null;
+    sources: Partial<Record<'outlet' | 'hackernews' | 'bluesky' | 'activitypub' | 'nostr' | 'minds', number>>;
+    media: {
+        images: number;
+        videos: number;
+    };
+    freshness: {
+        newestAt: string;
+        oldestAt: string;
+    };
+    explain: {
+        score: number;
+        parts: {
+            ageHours: number;
+            engagement: number;
+            media: number;
+            kind: number;
+            freshness: number;
+        };
+        impression: 'fresh' | 'demoted';
+    };
+}
+export interface FeedTopMeta {
+    ref: string;
+    poolBuiltAt: string;
+    poolSize: number;
+    /** Fewer items than asked for (a thin pool, the caps, or only items the member saw recently). */
+    short: boolean;
+    /** `impressions`: 'on' when the order uses what the member saw; otherwise the order is the pool's, jittered per session. */
+    flag: {
+        top: 'on';
+        impressions: 'on' | 'off' | 'unavailable';
+    };
+    stoppedBy: 'pool' | 'caps' | 'seen' | null;
+    /** 'safe' for a member on safe defaults, 'open' for one who turned them off. */
+    safety: 'safe' | 'open';
+    mindsSource: 'member' | 'anonymous' | 'none' | 'following';
+    networks: Record<FeedTopNetwork, 'ok' | 'unavailable'> | null;
+    compass_filter?: CompassFilterMeta;
+}
+/** GET /feeds/top. `networks` is null on a feed with no lanes (Following, a story); `lead` is null when the feed has no story. */
+export interface FeedTopResponse {
+    items: FeedTopItem[];
+    networks: Record<FeedTopNetwork, FeedTopNetworkEntry[]> | null;
+    lead: FeedStory | null;
+    meta: FeedTopMeta;
+}
+export interface FeedStoriesResponse {
+    data: FeedStory[];
+    meta: {
+        after: string | null;
+        limit: number;
+        short: boolean;
+        flag: {
+            top: 'on';
+            impressions: 'on' | 'off' | 'unavailable';
+        };
+        compass_filter?: CompassFilterMeta;
+    };
+}
+export interface PublicFeedTopMeta {
+    ref: string;
+    /** The 15-minute bucket the page was drawn for: the same for every visitor in it. */
+    bucket: number;
+    poolBuiltAt: string | null;
+    poolSize: number;
+    short: boolean;
+    flag: {
+        top: 'on';
+    };
+    compass_filter?: CompassFilterMeta;
+}
+/** A visitor's top (`feeds.publicTop`): safe items only, the same for every visitor in one 15-minute bucket. */
+export interface PublicFeedTopResponse {
+    items: FeedTopItem[];
+    networks: Record<FeedTopNetwork, FeedTopNetworkEntry[]> | null;
+    lead: FeedStory | null;
+    meta: PublicFeedTopMeta;
+}
+export interface FeedTopParams {
+    /** `builtin:all`, `category:<a browse category id>`, `following`, `watch` or `story:<a 64-character cluster id>`. */
+    ref: string;
+    /** 1..25, default 25. */
+    limit?: number;
+    /** Opaque per app session ([A-Za-z0-9_-], up to 64): the same token keeps one session's order stable across reads. */
+    session?: string;
+    /** A Politics choice, as `posts.list` takes it (refused on `following`). */
+    compass?: string;
+}
+export interface FeedStoriesParams {
+    /** The story the member is on (a 64-character cluster id): left out of the next ones. */
+    after?: string;
+    /** 1..10, default 10. */
+    limit?: number;
+    compass?: string;
+}
+export interface PublicFeedTopParams {
+    /** The app's project id. */
+    projectId: string;
+    /** `all` (default), `watch` or `category:<a browse category id>`. */
+    ref?: string;
+    /** 1..25 (the server's default is 25). */
+    limit?: number;
+    /** `all` or `hide`: a visitor's Politics choice. */
+    compass?: string;
+}
+export declare class FeedsResource {
+    private readonly http;
+    constructor(http: HttpClient);
+    /**
+     * The top of a feed for the signed-in member, with their own key of the app: the items they are most likely to engage
+     * with, rotated by what they have seen, the open-network lanes and the lead story. Off (404) until the app's operator
+     * turns it on; a 503 `feed_top_unavailable` carries Retry-After. Always private: never cached for anyone else.
+     */
+    top(params: FeedTopParams, options?: {
+        retry?: boolean;
+    }): Promise<FeedTopResponse>;
+    /** The stories the member should meet next (the story tail), by the same ranker as the top's lead. */
+    stories(params?: FeedStoriesParams, options?: {
+        retry?: boolean;
+    }): Promise<FeedStoriesResponse>;
+    /**
+     * A visitor's top of All, a category or Watch (tRPC `publicDiscovery.feedTop`): safe items only, the same for every
+     * visitor in one 15-minute bucket. Read with no credential at all (no key, no cookie: `credentials: 'omit'`), so the
+     * edge can hold it; a credentialed read would be private and uncached. Off (404) until the app's operator turns it on.
+     */
+    publicTop(params: PublicFeedTopParams, options?: {
+        timeoutMs?: number;
+    }): Promise<PublicFeedTopResponse>;
+}

package/dist/resources/feeds.js

@@ -0,0 +1,61 @@
+import { NotFoundError, RecursivError } from '../errors.js';
+export const FEED_TOP_NETWORKS = ['bluesky', 'activitypub', 'nostr'];
+export class FeedsResource {
+    http;
+    constructor(http) {
+        this.http = http;
+    }
+    /**
+     * The top of a feed for the signed-in member, with their own key of the app: the items they are most likely to engage
+     * with, rotated by what they have seen, the open-network lanes and the lead story. Off (404) until the app's operator
+     * turns it on; a 503 `feed_top_unavailable` carries Retry-After. Always private: never cached for anyone else.
+     */
+    top(params, options) {
+        return this.http.get('/feeds/top', { ref: params.ref, limit: params.limit, session: params.session, compass: params.compass }, options);
+    }
+    /** The stories the member should meet next (the story tail), by the same ranker as the top's lead. */
+    stories(params = {}, options) {
+        return this.http.get('/feeds/stories', { after: params.after, limit: params.limit, compass: params.compass }, options);
+    }
+    /**
+     * A visitor's top of All, a category or Watch (tRPC `publicDiscovery.feedTop`): safe items only, the same for every
+     * visitor in one 15-minute bucket. Read with no credential at all (no key, no cookie: `credentials: 'omit'`), so the
+     * edge can hold it; a credentialed read would be private and uncached. Off (404) until the app's operator turns it on.
+     */
+    async publicTop(params, options) {
+        // One fixed key order, so equal reads are one edge-cached URL.
+        const input = { projectId: params.projectId, ref: params.ref ?? 'all', ...(params.limit !== undefined ? { limit: params.limit } : {}),
+            ...(params.compass ? { compass: params.compass } : {}) };
+        const url = `${this.http.baseOrigin}/api/trpc/publicDiscovery.feedTop?input=${encodeURIComponent(JSON.stringify(input))}`;
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), options?.timeoutMs ?? this.http.requestTimeoutMs);
+        try {
+            let response;
+            try {
+                response = await fetch(url, { method: 'GET', headers: { Accept: 'application/json' }, credentials: 'omit', signal: controller.signal });
+            }
+            catch (error) {
+                throw new RecursivError(0, { type: 'api_error', code: controller.signal.aborted ? 'timeout' : 'network_error',
+                    message: controller.signal.aborted ? 'The visitor top did not answer in time.' : `The visitor top could not be reached (${error instanceof Error ? error.message : String(error)}).` });
+            }
+            let body = null;
+            try {
+                body = await response.json();
+            }
+            catch {
+                body = null;
+            }
+            const data = body?.result?.data;
+            if (response.ok && data && typeof data === 'object')
+                return data;
+            const error = body?.error && typeof body.error === 'object' ? body.error : undefined;
+            const said = [error?.json?.message, error?.message].find((value) => typeof value === 'string' && value.length > 0);
+            const code = typeof error?.data?.code === 'string' ? error.data.code.toLowerCase() : 'unknown_error';
+            const failure = { type: response.status === 404 ? 'not_found_error' : 'api_error', code, message: said ?? `HTTP ${response.status}` };
+            throw response.status === 404 ? new NotFoundError(failure) : new RecursivError(response.ok ? 502 : response.status, failure);
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+}

package/dist/resources/search.d.ts

@@ -35,8 +35,9 @@ export interface SearchPerson {
     pro: boolean;
     founder: boolean;
     /**
-     * The account wears the display name of a verified or founder account it is not: it is listed after every account
-     * that is not such a copy. Label it as not the account at `name_matches_verified_handle`. Absent from an older API.
+     * The account wears the display name of a verified or founder account it is not. Such an account is listed only when
+     * the query asks for its handle ("@handle"), after every account that is not such a copy (an older API listed it
+     * last for any query). Label it as not the account at `name_matches_verified_handle`. Absent from an older API.
      */
     name_matches_verified?: boolean;
     name_matches_verified_handle?: string | null;

package/dist/types.d.ts

@@ -1261,8 +1261,9 @@ export interface ProfileSearchResult extends Profile {
     pro: boolean;
     founder: boolean;
     /**
-     * The account wears the display name of a verified or founder account it is not: it is listed after every account
-     * that is not such a copy. Label it as not the account at `name_matches_verified_handle`. Absent from an older API.
+     * The account wears the display name of a verified or founder account it is not. Such an account is listed only when
+     * the query asks for its handle ("@handle"), after every account that is not such a copy (an older API listed it
+     * last for any query). Label it as not the account at `name_matches_verified_handle`. Absent from an older API.
      */
     name_matches_verified?: boolean;
     name_matches_verified_handle?: string | null;

package/llm.md

@@ -639,6 +639,19 @@ await r.bookmarks.unsave(key)                                          // or uns
 
 Newest saved first. Pages can be short while they skip posts the member can no longer read: page on `meta.next_cursor`, not length. Needs the member's own app key (else 403 `project_binding_required`). 503 `bookmarks_unavailable` means the server has no synced bookmarks yet: keep saves on the device (pass `{ retry: false }` to the probe so the 503 is not retried).
 
+### r.feeds — The top of a feed (member and visitor)
+
+```typescript
+const top = await r.feeds.top({ ref: 'builtin:all', limit: 10, session })   // member's own app key; category:<id>, following, watch, story:<id>
+// top.items: { ref, kind, target, position, block: 'top' | 'below', explain }; top.networks: { bluesky, activitypub, nostr } lanes with a card each
+// top.lead: the story to open with; every target is in the app (post id, /social/post/<protocol>/<id>, story id), never a URL out
+const { data: next } = await r.feeds.stories({ after: storyId })             // the story tail, same ranker as the lead
+const page = await r.feeds.publicTop({ projectId, ref: 'all' })              // a visitor's top: safe items only, keyless, edge-cacheable
+const feed = r.discovery.createFeed({ networks, top: { ref: 'builtin:all', session }, seen: seenRefs })
+```
+
+Each answers 404 while the app's operator has it off; `feeds.top` is private to the member and 503 `feed_top_unavailable` carries Retry-After. With a visible view of a top item, send `block: 'top'` and its position. In a feed session the top's read starts with page 0's reads and the top holds the page at most 1.5 s from its start, the by-id reads of its posts included; off, failed or late, the session is unchanged, and the radar's story reads its posts as soon as the radar answers either way. Page 0 then opens with the top's lead story and items (each item carries `top: { ref, position, block }`), its lanes replace the networks' first reads, and no hot page repeats a top item. `seen` (Minds ids and `<protocol>/<nativeId>` refs) leaves seen posts out of the hot pages, walking on past a page left under five posts (up to three more). `seenClusters` (`Map<id, { n, clicked }>`) and a visitor's `bucket` rotate the story when the top names none (`pickRadarCluster`).
+
 ### r.search
 
 ```typescript

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@recursiv/sdk",
-  "version": "0.7.63",
+  "version": "0.7.65",
   "description": "TypeScript SDK for the Recursiv API",
   "license": "FSL-1.1-ALv2",
   "type": "module",