@recursiv/sdk 0.7.70 → 0.7.71

package/dist/resources/discovery-merge.js

@@ -0,0 +1,479 @@
+import { isSensitivePost, linksAdultSite } from './discovery-safety.js';
+// ──────────────────────────────────────────────────────────────────────────
+// How a Discover client merges its sources' posts: by engagement, with the
+// network mix as a soft constraint, never by taking turns. Ported from the
+// Minds app (lib/feedMerge, 2026-10-04).
+//
+// A progressive feed reads Minds and each open network as its own session
+// (createProgressiveFeed), so something has to put their pages together.
+// Until 2026-10-04 the Minds app took turns, one row per network: live,
+// Politics' rows 3-21 cycled Minds, Bluesky, Nostr and ActivityPub, the Nostr
+// turns holding posts with no engagement beside 150-like posts.
+//
+// Each post module gets a score, and rows are filled best first:
+//
+//  - engagement: likes, reposts (x2), replies (x3), quotes and zappers (x2).
+//    Networks count on different scales, so the points are normalised twice
+//    and the two halves added: against the median of the post's own network
+//    in the batch, and against the median of the whole batch, both on a log
+//    scale with the medians held to at least DISCOVERY_REFERENCE_FLOOR;
+//  - recency: the score halves every DISCOVERY_HALF_LIFE_HOURS of age;
+//  - format: a video that can play scores DISCOVERY_VIDEO_BOOST times, a
+//    picture DISCOVERY_PICTURE_BOOST times (neither when it would be masked);
+//  - a post nobody engaged with (counts known, all zero) goes below every post
+//    with engagement unless it is fresh (under DISCOVERY_FRESH_MS): then it
+//    scores DISCOVERY_FRESH_NORM. A post whose network reports no counts is
+//    unknown, not zero: it scores DISCOVERY_UNKNOWN_NORM.
+//
+// The network mix is a soft constraint: no network takes more than
+// DISCOVERY_NETWORK_ROWS_MAX of any DISCOVERY_NETWORK_WINDOW rows, nor more
+// than DISCOVERY_NETWORK_RUN_MAX in a row, and a titled module waits until
+// DISCOVERY_TITLE_SCREEN_ROWS rows separate it from the last one titled the
+// same. When nothing left fits, the run gives way first, then the title, then
+// the share: nothing is dropped. Minds members have a floor: no more than
+// DISCOVERY_MINDS_GAP_MAX rows in a row without one of their posts while they
+// have one of the same standing left.
+//
+// The galleries a batch holds are pooled into one, its cards best first, at
+// most DISCOVERY_GALLERY_NETWORK_MAX from one network; the cards that do not
+// fit go in as posts of their own.
+// ──────────────────────────────────────────────────────────────────────────
+/** A radar story's lane (discoveryModuleLane). */
+export const DISCOVERY_STORY_LANE = 'story';
+/** A suggestion rail's lane (groups, people, tags). */
+export const DISCOVERY_RAIL_LANE = 'rail';
+/** Rows the network share is counted over... */
+export const DISCOVERY_NETWORK_WINDOW = 20;
+/** ...and the most of them one network may take (40%). */
+export const DISCOVERY_NETWORK_ROWS_MAX = 8;
+/** The most rows in a row one network may take. */
+export const DISCOVERY_NETWORK_RUN_MAX = 3;
+/** The home network's floor: after this many rows in a row with no Minds member's post, the next row is Minds' best of the tier. */
+export const DISCOVERY_MINDS_GAP_MAX = 5;
+/** Rows that separate two modules with the same title: more than a screen. */
+export const DISCOVERY_TITLE_SCREEN_ROWS = 6;
+/** A post younger than this with no engagement yet is fresh: it scores DISCOVERY_FRESH_NORM, not zero. */
+export const DISCOVERY_FRESH_MS = 2 * 60 * 60_000;
+/** The score halves with every this many hours of a post's age. */
+export const DISCOVERY_HALF_LIFE_HOURS = 24;
+/** A video that can play, and a picture, against a text post with the same engagement. */
+export const DISCOVERY_VIDEO_BOOST = 1.5;
+export const DISCOVERY_PICTURE_BOOST = 1.15;
+/** The least a network's (or the batch's) typical engagement is taken to be, in points. */
+export const DISCOVERY_REFERENCE_FLOOR = 5;
+/** A fresh post with no engagement yet, and a post whose network reports no counts: against a typical post's 1. */
+export const DISCOVERY_FRESH_NORM = 0.5;
+export const DISCOVERY_UNKNOWN_NORM = 0.5;
+/** A pooled gallery's cards, and the most of them from one network. */
+export const DISCOVERY_POOLED_GALLERY_MAX = 12;
+export const DISCOVERY_GALLERY_NETWORK_MAX = 5;
+const POINTS = { likes: 1, reposts: 2, replies: 3, quotes: 2, zappers: 2 };
+const TITLED = new Set(['visual', 'video', 'conversation', 'thread', 'longread']);
+const RAILS = new Set(['groups', 'people', 'tags']);
+const isPostItem = (item) => item.kind === 'minds' || item.kind === 'social';
+/**
+ * The network a post in Minds' own lane comes from. Minds' feeds carry
+ * accounts that fediverse servers federated into legacy minds.com, stored as
+ * ordinary accounts with a `name@host` handle; a post by one is ActivityPub's.
+ * The server's `isFederatedHandle` rule: a Minds username never carries an @.
+ */
+export function mindsPostNetwork(post) {
+    const username = post?.author?.username?.trim().replace(/^@/, '');
+    return username?.includes('@') ? 'activitypub' : 'minds';
+}
+/** The network a post item comes from: 'minds' only for a Minds member's own post. */
+export function discoveryPostNetwork(item) {
+    return item.kind === 'minds' ? mindsPostNetwork(item.post) : item.post.protocol;
+}
+/** Whose row a module is: the network of the post it leads with ('minds' for a Minds member), the story lane or the rail lane. */
+export function discoveryModuleLane(module) {
+    const lead = module.items[0];
+    if (!lead)
+        return DISCOVERY_RAIL_LANE;
+    if (lead.kind === 'cluster')
+        return DISCOVERY_STORY_LANE;
+    if (!isPostItem(lead))
+        return DISCOVERY_RAIL_LANE;
+    return discoveryPostNetwork(lead);
+}
+const isModule = (row) => !!row && typeof row === 'object' && 'presentation' in row && 'items' in row && 'spec' in row;
+/** A module of posts (a post, a gallery, a conversation, a strip of clips): what the merge orders. */
+export function isDiscoveryPostModule(row) {
+    if (!isModule(row))
+        return false;
+    const lane = discoveryModuleLane(row);
+    return lane !== DISCOVERY_STORY_LANE && lane !== DISCOVERY_RAIL_LANE;
+}
+/** What a row is titled, as a key: a featured module's kind and theme, a rail's kind. Null for a row with no title of its own. */
+export function discoveryRowTitle(row) {
+    if (!isModule(row))
+        return null;
+    const presentation = row.presentation;
+    if (RAILS.has(presentation))
+        return presentation;
+    if (!TITLED.has(presentation))
+        return null;
+    const theme = row.theme;
+    return `${presentation}|${typeof theme === 'string' ? theme : ''}`;
+}
+const hasMedia = (media) => Array.isArray(media)
+    && media.some(entry => !!entry && typeof entry === 'object' && (entry.type === 'image' || entry.type === 'video')
+        && entry.unplayable !== true);
+/**
+ * A post the reader may be shown first: a Minds post nobody masks (isSensitivePost), and an open-network post that
+ * links no porn site (their cards carry no NSFW flag).
+ */
+export function discoveryLeadable(item) {
+    return item.kind === 'minds' ? !isSensitivePost(item.post) : !linksAdultSite(item.post.text);
+}
+/** A post with a picture or a video of its own that the reader sees unblurred. */
+export function discoveryShowsMedia(item) {
+    return discoveryLeadable(item) && hasMedia(item.post.media);
+}
+// ── Videos that can play ────────────────────────────────────────────────
+/** Video files (or playlists) a player found will not play this session: never promoted again. */
+const UNAVAILABLE_VIDEOS = new Set();
+const UNAVAILABLE_VIDEOS_KEPT = 512;
+/** A player found this video file (or HLS playlist) will not play: no Discover module promotes it, and it gets no video boost. */
+export function reportDiscoveryVideoUnavailable(url) {
+    if (!url)
+        return;
+    UNAVAILABLE_VIDEOS.add(url);
+    while (UNAVAILABLE_VIDEOS.size > UNAVAILABLE_VIDEOS_KEPT)
+        UNAVAILABLE_VIDEOS.delete(UNAVAILABLE_VIDEOS.values().next().value);
+}
+/** Forget every report (a test seam, or a new viewer). */
+export function resetDiscoveryVideoReports() { UNAVAILABLE_VIDEOS.clear(); }
+const VIDEO_EXTENSIONS = ['.mp4', '.webm', '.mov', '.m4v', '.avi', '.m3u8'];
+const isVideoUrl = (url) => VIDEO_EXTENSIONS.some(ext => url.toLowerCase().includes(ext)) || url.includes('cloudflarestream') || url.includes('/video/');
+/** A URL that is a picture, whatever the row says: the legacy thumbnail route, or an image extension. */
+const POSTER_URL = /\/fs\/v1\/thumbnail\/|\.(png|jpe?g|gif|webp|avif)(\?|$)/i;
+/**
+ * A media entry a module may feature as a video: a video (by its type, or by its address when it has none) with a file
+ * to play, not a poster row (a row typed video whose file is a picture), not still encoding or failed by its own
+ * `status`, and not reported unavailable (reportDiscoveryVideoUnavailable).
+ */
+export function promotableDiscoveryVideo(entry) {
+    const media = (typeof entry === 'string' ? { url: entry } : entry);
+    if (!media || typeof media !== 'object' || typeof media.url !== 'string' || !media.url)
+        return false;
+    const type = typeof media.type === 'string' && media.type ? media.type : isVideoUrl(media.url) ? 'video' : 'image';
+    if (type !== 'video' || media.unplayable === true || POSTER_URL.test(media.url))
+        return false;
+    if (media.status === 'processing' || media.status === 'failed')
+        return false;
+    if (UNAVAILABLE_VIDEOS.has(media.url))
+        return false;
+    const hls = typeof media.hlsUrl === 'string' ? media.hlsUrl : typeof media.hls_url === 'string' ? media.hls_url : '';
+    return !(hls && UNAVAILABLE_VIDEOS.has(hls));
+}
+/** A module's items whose post has a video that can play (promotableDiscoveryVideo). */
+export function promotedDiscoveryVideoItems(items) {
+    return items.filter(item => 'post' in item && (() => {
+        const media = item.post.media;
+        return Array.isArray(media) ? media.some(promotableDiscoveryVideo) : promotableDiscoveryVideo(media);
+    })());
+}
+// ── Engagement ──────────────────────────────────────────────────────────
+/** The first of the values that is a count (a finite number, 0 or more); null when none is. */
+function firstCount(...values) {
+    for (const value of values) {
+        const count = typeof value === 'number' ? value : typeof value === 'string' && value.trim() ? Number(value) : Number.NaN;
+        if (Number.isFinite(count) && count >= 0)
+            return count;
+    }
+    return null;
+}
+function mindsPoints(post) {
+    if (!post)
+        return null;
+    const likes = firstCount(post.reactions_count, post.reactionsCount, post.likeCount, post.upvote_count, post.score);
+    const replies = firstCount(post.reply_count, post.repliesCount, post.replies_count);
+    const external = firstCount(post.reply_count_external, post.replyCountExternal);
+    const reposts = firstCount(post.reposts_count, post.repostsCount, post.repostCount);
+    if (likes === null && replies === null && external === null && reposts === null)
+        return null;
+    return POINTS.likes * (likes ?? 0) + POINTS.replies * ((replies ?? 0) + (external ?? 0)) + POINTS.reposts * (reposts ?? 0);
+}
+/**
+ * A post's engagement points: likes, reposts, replies, quotes and zappers. Null when its network reports no counts
+ * (unknown, not zero). A Minds repost counts its original's too, when that is more: the card shows the original.
+ */
+export function discoveryEngagementPoints(item) {
+    if (item.kind === 'minds') {
+        const post = item.post;
+        const own = mindsPoints(post);
+        const original = mindsPoints((post.reposted_from ?? post.repostedFrom));
+        return own === null ? original : original === null ? own : Math.max(own, original);
+    }
+    const post = item.post;
+    const likes = firstCount(post.likeCount);
+    const reposts = firstCount(post.repostCount);
+    const replies = firstCount(post.replyCount);
+    const quotes = firstCount(post.quoteCount);
+    const zappers = firstCount(post.distinctZappers);
+    if (likes === null && reposts === null && replies === null && quotes === null && zappers === null)
+        return null;
+    return POINTS.likes * (likes ?? 0) + POINTS.reposts * (reposts ?? 0) + POINTS.replies * (replies ?? 0)
+        + POINTS.quotes * (quotes ?? 0) + POINTS.zappers * (zappers ?? 0);
+}
+function writtenAt(item) {
+    const post = item.post;
+    const value = item.kind === 'minds' ? post.created_at ?? post.createdAt ?? post.publishedAt : post.createdAt;
+    const at = typeof value === 'string' || typeof value === 'number' ? new Date(value).getTime() : Number.NaN;
+    return Number.isFinite(at) ? at : null;
+}
+/** Whose counts a post's points are: Minds' own for any post in Minds' lane, else its network's. */
+const countedBy = (item) => (item.kind === 'minds' ? 'minds' : item.post.protocol);
+function median(values) {
+    if (!values.length)
+        return 0;
+    const sorted = [...values].sort((a, b) => a - b);
+    const middle = Math.floor(sorted.length / 2);
+    return sorted.length % 2 ? sorted[middle] : (sorted[middle - 1] + sorted[middle]) / 2;
+}
+/** The typical engagement of a batch of posts: the median of the posts with any, held to at least DISCOVERY_REFERENCE_FLOOR. */
+export function discoveryEngagementReference(items) {
+    const byNetwork = new Map();
+    const all = [];
+    for (const item of items) {
+        const points = discoveryEngagementPoints(item);
+        if (points === null || points <= 0)
+            continue;
+        all.push(points);
+        const network = countedBy(item);
+        const list = byNetwork.get(network);
+        if (list)
+            list.push(points);
+        else
+            byNetwork.set(network, [points]);
+    }
+    const networks = new Map();
+    for (const [network, list] of byNetwork)
+        networks.set(network, Math.max(DISCOVERY_REFERENCE_FLOOR, median(list)));
+    return { networks, batch: Math.max(DISCOVERY_REFERENCE_FLOOR, median(all)) };
+}
+/** A post's tier and score in a batch. `now`: the time the scores are for. */
+export function rankDiscoveryItem(item, reference, now) {
+    const points = discoveryEngagementPoints(item);
+    const at = writtenAt(item);
+    const age = at === null ? null : Math.max(0, now - at);
+    // A post that does not say when it was written is taken to be a day old: neither fresh nor buried.
+    const decay = 0.5 ** ((age ?? DISCOVERY_HALF_LIFE_HOURS * 3_600_000) / (DISCOVERY_HALF_LIFE_HOURS * 3_600_000));
+    const boost = promotedDiscoveryVideoItems([item]).length && discoveryLeadable(item) ? DISCOVERY_VIDEO_BOOST : discoveryShowsMedia(item) ? DISCOVERY_PICTURE_BOOST : 1;
+    if (points === null)
+        return { tier: 0, score: DISCOVERY_UNKNOWN_NORM * decay * boost };
+    if (points > 0) {
+        const own = Math.log1p(points) / Math.log1p(reference.networks.get(countedBy(item)) ?? DISCOVERY_REFERENCE_FLOOR);
+        const batch = Math.log1p(points) / Math.log1p(reference.batch);
+        return { tier: 0, score: ((own + batch) / 2) * decay * boost };
+    }
+    if (age !== null && age < DISCOVERY_FRESH_MS)
+        return { tier: 0, score: DISCOVERY_FRESH_NORM * decay * boost };
+    return { tier: 1, score: decay * boost };
+}
+/** A module's best post: the lowest tier, then the highest score. Null for a module with no posts. */
+export function rankDiscoveryModule(module, reference, now) {
+    let best = null;
+    for (const item of module.items) {
+        if (!isPostItem(item))
+            continue;
+        const rank = rankDiscoveryItem(item, reference, now);
+        if (!best || rank.tier < best.tier || (rank.tier === best.tier && rank.score > best.score))
+            best = rank;
+    }
+    return best;
+}
+/** Where a module's post stands in the top of the feed: its place in the top's block, or null (not a top post, or a network lane's entry). */
+export function discoveryTopPlace(module) {
+    const first = module.items[0];
+    const top = first && isPostItem(first) ? first.top : undefined;
+    return top && !top.lane && top.block === 'top' && typeof top.position === 'number' ? top.position : null;
+}
+const postsOf = (modules) => modules.flatMap(module => module.items.filter(isPostItem));
+/** Several posts of one network one under another (a conversation, a thread of more than two): a screenful of one source. */
+export function isColumnModule(module) {
+    const presentation = module.presentation;
+    return (presentation === 'conversation' || presentation === 'thread') && module.items.filter(isPostItem).length > 2;
+}
+const isGallery = (module) => module.presentation === 'visual' && module.items.length > 0 && module.items.every(isPostItem);
+const withItems = (module, items) => {
+    const element = module.spec.elements.module;
+    return { ...module, items, spec: { ...module.spec, elements: { ...module.spec.elements, module: { ...element, props: { ...element.props, itemKeys: items.map(item => item.key) } } } } };
+};
+/** One card of a gallery as a post of its own (the ordinary presentation, so its spec still validates). */
+function asPost(gallery, item) {
+    const element = gallery.spec.elements.module;
+    return { id: `${gallery.id}~${item.key}`, presentation: 'posts', source: 'fallback', items: [item],
+        spec: { root: 'module', elements: { module: { ...element, type: 'DiscoveryPosts', props: { itemKeys: [item.key] }, children: [] } } } };
+}
+/**
+ * The batch with its galleries pooled into one (one per title): the cards best first, at most
+ * DISCOVERY_GALLERY_NETWORK_MAX from one network and DISCOVERY_POOLED_GALLERY_MAX in all; every card that does not fit
+ * goes in as a post of its own. The gallery keeps the place and id of the batch's first gallery; one gallery that fits
+ * as it is stays as it is. `keep`: a module never pooled (a screen's lead).
+ */
+export function poolDiscoveryGalleries(modules, now, keep) {
+    const themes = new Map();
+    for (const module of modules) {
+        if (module === keep || !isGallery(module))
+            continue;
+        const title = discoveryRowTitle(module) ?? '';
+        const group = themes.get(title);
+        if (group)
+            group.push(module);
+        else
+            themes.set(title, [module]);
+    }
+    if (!themes.size)
+        return [...modules];
+    const reference = discoveryEngagementReference(postsOf(modules));
+    const replaced = new Map();
+    for (const galleries of themes.values()) {
+        const seen = new Set();
+        const cards = galleries.flatMap((gallery, from) => gallery.items.filter(isPostItem).flatMap((item, index) => {
+            if (seen.has(item.key))
+                return [];
+            seen.add(item.key);
+            return [{ item, gallery, network: discoveryPostNetwork(item), rank: rankDiscoveryItem(item, reference, now), order: index * galleries.length + from }];
+        })).sort((a, b) => a.rank.tier - b.rank.tier || b.rank.score - a.rank.score || a.order - b.order);
+        const counts = new Map();
+        const kept = [];
+        const spilled = [];
+        for (const card of cards) {
+            const count = counts.get(card.network) ?? 0;
+            if (kept.length < DISCOVERY_POOLED_GALLERY_MAX && count < DISCOVERY_GALLERY_NETWORK_MAX) {
+                kept.push(card);
+                counts.set(card.network, count + 1);
+            }
+            else
+                spilled.push(card);
+        }
+        if (galleries.length === 1 && !spilled.length)
+            continue;
+        const [first, ...rest] = galleries;
+        replaced.set(first, [withItems(first, kept.map(card => card.item)), ...spilled.map(card => asPost(card.gallery, card.item))]);
+        for (const gallery of rest)
+            replaced.set(gallery, []);
+    }
+    return replaced.size ? modules.flatMap(module => replaced.get(module) ?? [module]) : [...modules];
+}
+const laneOfRow = (row) => (isDiscoveryPostModule(row) ? discoveryModuleLane(row) : null);
+/**
+ * A batch of post modules, taken best first under the network mix's soft constraints (the rules above). Each `take`
+ * reads the rows above the place it fills, so it fits the rows a feed already shows.
+ *
+ * The top of the feed's posts (discoveryTopPlace) are taken first, in the top's order: the engagement lanes own that
+ * order. `order` breaks equal scores: the caller's order of the modules (lower first), by default their order in `modules`.
+ */
+export class DiscoveryEngagementMerge {
+    left;
+    constructor(modules, { now = Date.now(), order } = {}) {
+        const reference = discoveryEngagementReference(postsOf(modules));
+        this.left = modules.map((module, index) => {
+            const rank = rankDiscoveryModule(module, reference, now) ?? { tier: 1, score: 0 };
+            return { module, lane: discoveryModuleLane(module), title: discoveryRowTitle(module), column: isColumnModule(module), top: discoveryTopPlace(module),
+                tier: rank.tier, score: rank.score, order: order ? order(module, index) : index };
+        }).sort((a, b) => (a.top ?? Number.POSITIVE_INFINITY) - (b.top ?? Number.POSITIVE_INFINITY) || a.tier - b.tier || b.score - a.score || a.order - b.order);
+    }
+    get size() { return this.left.length; }
+    /** The modules not taken yet, best first. */
+    rest() { return this.left.map(candidate => candidate.module); }
+    /** Whether a module is still to be taken. */
+    has(module) { return this.left.some(candidate => candidate.module === module); }
+    /** Takes this module out of the batch (a screen's lead). */
+    remove(module) { this.left = this.left.filter(candidate => candidate.module !== module); }
+    /**
+     * The module for the row under `above`, or undefined when none is left. `singles`: a column (a conversation, a
+     * thread) only when no single post of the same tier is left. `newNetwork`: a post from a network none of the rows
+     * above come from, while one of the same tier is left (a first screen's second row).
+     */
+    take(above, { singles = false, newNetwork = false } = {}) {
+        if (!this.left.length)
+            return undefined;
+        const pick = (candidate) => { this.left.splice(this.left.indexOf(candidate), 1); return candidate.module; };
+        const topped = this.left.find(candidate => candidate.top !== null);
+        if (topped)
+            return pick(topped);
+        const tier = Math.min(...this.left.map(candidate => candidate.tier));
+        let pool = this.left.filter(candidate => candidate.tier === tier);
+        if (singles && pool.some(candidate => !candidate.column))
+            pool = pool.filter(candidate => !candidate.column);
+        if (newNetwork) {
+            const shown = new Set(above.map(laneOfRow));
+            if (pool.some(candidate => !shown.has(candidate.lane)))
+                pool = pool.filter(candidate => !shown.has(candidate.lane));
+        }
+        let since = 0;
+        while (since < above.length && laneOfRow(above[above.length - 1 - since]) !== 'minds')
+            since += 1;
+        const home = since >= DISCOVERY_MINDS_GAP_MAX ? pool.find(candidate => candidate.lane === 'minds') : undefined;
+        if (home)
+            return pick(home);
+        const window = above.slice(-(DISCOVERY_NETWORK_WINDOW - 1)).map(laneOfRow);
+        const run = above.slice(-DISCOVERY_NETWORK_RUN_MAX).map(laneOfRow);
+        const titles = new Set(above.slice(-(DISCOVERY_TITLE_SCREEN_ROWS - 1)).map(discoveryRowTitle).filter((title) => !!title));
+        const share = (candidate) => window.filter(lane => lane === candidate.lane).length < DISCOVERY_NETWORK_ROWS_MAX;
+        const unbroken = (candidate) => run.length < DISCOVERY_NETWORK_RUN_MAX || run.some(lane => lane !== candidate.lane);
+        const untitled = (candidate) => !candidate.title || !titles.has(candidate.title);
+        const chosen = pool.find(candidate => share(candidate) && unbroken(candidate) && untitled(candidate))
+            ?? pool.find(candidate => share(candidate) && untitled(candidate))
+            ?? pool.find(candidate => share(candidate) && unbroken(candidate))
+            ?? pool.find(share)
+            ?? pool[0];
+        return pick(chosen);
+    }
+}
+function weave(first, second) {
+    const out = [];
+    for (let index = 0; index < Math.max(first.length, second.length); index++) {
+        if (index < first.length)
+            out.push(first[index]);
+        if (index < second.length)
+            out.push(second[index]);
+    }
+    return out;
+}
+/** The place below which rows that arrive go: after the last row seen and one more, never above `floor`; the end when nothing was seen. */
+function arrivalPlace(rows, reached, floor) {
+    let last = -1;
+    rows.forEach((row, index) => { if (reached.has(row.id))
+        last = index; });
+    return Math.max(Math.min(floor, rows.length), last < 0 ? rows.length : Math.min(rows.length, last + 2));
+}
+/** Rows that arrive woven in one by one with the rows not seen yet, below the place a reader has reached: for a feed of one source. */
+export function weaveDiscoveryArrival(rows, arriving, reached, floor = 0) {
+    const at = arrivalPlace(rows, reached, floor);
+    return at >= rows.length ? [...rows, ...arriving] : [...rows.slice(0, at), ...weave(arriving, rows.slice(at))];
+}
+/**
+ * Where rows that arrive after others go (a progressive feed's `mixed` part). Nothing the viewer has had on screen
+ * moves: they go after the last row seen (`reached`, by id, and one more for a row only peeking in), never above `floor`;
+ * with nothing seen yet, at the end. Below that place the arriving rows and the rows not seen yet are merged: the rows
+ * that are not posts (a story, a rail, a row of the client's own) take the places they would have had woven in one by
+ * one, and the posts fill the other places by engagement under the network mix (DiscoveryEngagementMerge).
+ */
+export function mergeDiscoveryArrival(rows, arriving, reached, floor = 0, now = Date.now()) {
+    const at = arrivalPlace(rows, reached, floor);
+    const head = rows.slice(0, at);
+    const below = at >= rows.length ? [...arriving] : weave(arriving, rows.slice(at));
+    const posts = below.filter(isDiscoveryPostModule);
+    if (!posts.length)
+        return [...head, ...below];
+    const pooled = poolDiscoveryGalleries(posts, now);
+    const place = new Map(posts.map((module, index) => [module, index]));
+    const merge = new DiscoveryEngagementMerge(pooled, { now, order: (module, index) => place.get(module) ?? posts.length + index });
+    const out = [...head];
+    for (const row of below) {
+        if (!isDiscoveryPostModule(row)) {
+            out.push(row);
+            continue;
+        }
+        const next = merge.take(out);
+        if (next)
+            out.push(next);
+    }
+    for (let next = merge.take(out); next; next = merge.take(out))
+        out.push(next);
+    return out;
+}

package/dist/resources/discovery-progressive.d.ts

@@ -0,0 +1,117 @@
+import type { DiscoveryFeedOptions, DiscoveryFeedPage, DiscoveryModule, DiscoveryRecommendationSources, DiscoveryTopSource } from './discovery.js';
+import type { SocialNetwork } from './protocols.js';
+/** A feed session a progressive feed reads, one per source: a DiscoveryFeedSession, or a reader of the same shape. */
+export interface DiscoveryFeedReader {
+    next(): Promise<DiscoveryFeedPage>;
+    retryFailed(): void;
+}
+/** What opens a progressive feed's per-source sessions: `sdk.discovery`, or a reader of the same shape (a visitor's, a For you feed's). */
+export interface DiscoveryFeedFactory {
+    createFeed(options: DiscoveryFeedOptions): DiscoveryFeedReader;
+}
+/**
+ * One source's page, as it arrived. `round` is the load that asked for it.
+ * `composed`: its modules are a first screen (composeFirstScreen), whose first module is its lead and whose rows are
+ * ordered by engagement across the networks; a client that moves clips out of it keeps both (`keepLead`).
+ * `mixed`: one of several sources' pages (a feed read per network) handed on as it landed, after the first screen: a
+ * client merges it by engagement with the rows the reader has not seen yet (mergeDiscoveryArrival). The first screen
+ * is ordered already, and a feed of one source keeps its server's order.
+ */
+export interface DiscoveryPart {
+    source: string;
+    round: number;
+    modules: DiscoveryModule[];
+    composed?: boolean;
+    mixed?: boolean;
+}
+/** A progressive feed's state: a page's summary without its modules. */
+export type DiscoveryFeedStatus = Omit<DiscoveryFeedPage, 'modules'>;
+export interface ProgressiveDiscoveryFeed {
+    /**
+     * Read the next page of every source that has one; each part goes to `onPart` as it lands. Resolves with the round's
+     * summary (every module the round handed on while it was open). Rejects only when every source it read failed and
+     * nothing arrived.
+     */
+    next(onPart: (part: DiscoveryPart) => void): Promise<DiscoveryFeedPage>;
+    /** Mark the failed sources readable again; the next `next()` reads them. */
+    retryFailed(): void;
+    /**
+     * Told when a source that was still reading after its round ended lands, with the feed's state then (its posts, if
+     * any, went to the open `onPart`), so a network that fails late says so without another load. Returns an unsubscribe.
+     */
+    onStatus(listener: (status: DiscoveryFeedStatus) => void): () => void;
+    /**
+     * The network catalog as it is now, for a feed opened before it answered (or on an older list kept on the device): a
+     * network it did not have joins as its own source, and one the catalog no longer offers stops being read. What was
+     * handed on stays. Only a feed over every source opened per source takes networks in. Returns whether a network
+     * joined (one it did not read, or had stopped reading): the feed has its posts still to read.
+     */
+    setNetworks(networks: SocialNetwork[]): boolean;
+}
+export interface ProgressiveFeedSettings {
+    /**
+     * Open one session per source (default true). False keeps the factory's session whole, as one source: a feed that
+     * picks its own networks (For you, `createPersonalFeed`) ignores a per-network `source`, so opening it once per
+     * network would read the whole feed that many times over.
+     */
+    perSource?: boolean;
+    /** Hold the first load over every source and hand it on as one composed first screen (default true). */
+    firstScreen?: boolean;
+    /** How long the first load waits for Minds once a source has answered: FIRST_SCREEN_MS (a member's, the default) or VISITOR_FIRST_SCREEN_MS. */
+    firstScreenMs?: number;
+    /** Told each time a source's read lands, and whether it failed: a client that shortens its next feed's wait while Minds is failing reads it here. */
+    onLanded?: (source: string, failed: boolean) => void;
+}
+/** How long a round keeps waiting for its slower sources once one of them has answered. */
+export declare const DISCOVERY_STRAGGLER_MS = 3000;
+/**
+ * How long the first load waits for Minds and a second network, once its first source has answered, before it hands on
+ * what it has. Measured live (2026-09-27): the Minds read answers in 0.8-2 s in a category and 1.7-3.4 s on All; the
+ * open networks' in 0.2-1.3 s. Counted from the first answer, not from the load. A member's wait, and the default: the
+ * API caches a Discover page per caller for 30 s, so a member's first load is a fresh build of their Minds page.
+ */
+export declare const FIRST_SCREEN_MS = 2500;
+/**
+ * A visitor's wait. Every visitor reads the same anonymous page, so once anyone has read it in the last 30 s it answers
+ * in about 0.13 s, well inside this wait, and Minds leads; cold, the networks lead and Minds joins below.
+ */
+export declare const VISITOR_FIRST_SCREEN_MS = 800;
+/**
+ * A module without the items in `seen` (item keys). Posts already shown by another source's module are not shown again:
+ * the sessions dedupe within themselves, but across them a story's member posts can also arrive in that network's own
+ * page. A module that loses items keeps its spec in step. A suggestion already shown leaves its rail, and a rail left
+ * with fewer than two is dropped; a story already shown is dropped whole, and keeps its headline and outlets when only
+ * its posts were shown; a post module with none left is dropped (null).
+ */
+export declare function withoutSeenItems(module: DiscoveryModule, seen: ReadonlySet<string>): DiscoveryModule | null;
+/** The other networks a feed over every source reads, in the session's own order. */
+export declare function discoveryRemoteSources(networks: SocialNetwork[], source?: string): string[];
+/**
+ * The suggestions a feed filtered to one network carries. The candidate lists are the whole app's: live on 2026-09-27
+ * Discover filtered to Nostr showed "People to follow" with three ActivityPub accounts. A network's own feed suggests
+ * only that network's accounts (a person's `protocol`, Minds when it has none); groups and tags are Minds', so they come
+ * with Minds' feed and with All's.
+ */
+export declare function discoveryRecommendationsFor(recommend: DiscoveryRecommendationSources | undefined, source?: string): DiscoveryRecommendationSources | undefined;
+/** A token for one feed open ([A-Za-z0-9_-], up to 64): its sessions read the top of the feed once between them, and the server keeps that open's order stable. */
+export declare function discoveryFeedOpenToken(): string;
+/** How long a top answer is shared by the feed opens that ask for it with the same params. */
+export declare const DISCOVERY_TOP_SHARE_MS = 60000;
+/** After the top route answers 404 (it is off), how long a share does not ask it again. */
+export declare const DISCOVERY_TOP_OFF_MS: number;
+/**
+ * A share of top reads for one viewer's reader: `share(read, scope)` reads the top once for every session that asks
+ * with the same params (ref, limit, the open's session token) and `scope` (e.g. the Politics choice it reads under),
+ * while the read is out and DISCOVERY_TOP_SHARE_MS after. A route that answered 404 (off) is not asked again for
+ * DISCOVERY_TOP_OFF_MS. Make one share per viewer: never hand it another viewer's reader.
+ */
+export declare function createDiscoveryTopShare(now?: () => number): (read: DiscoveryTopSource, scope?: string) => DiscoveryTopSource;
+/**
+ * A progressive Discover feed over `factory`'s sessions (see the note above). `feedOptions` are a session's: over every
+ * source, Minds' session carries the radar and the recommendations (scoped to the feed's network filter,
+ * discoveryRecommendationsFor), and each other network with public trends gets a session filtered to itself, which
+ * carries Hide politics (`compass: 'hide'`) and no other choice. A feed filtered to one network, or with no other
+ * networks, is one session. `top`, `seen`, `seenClusters` and `bucket` reach every session, under one session token
+ * per open. Create a new feed when the viewer, category or filter changes.
+ */
+export declare function createProgressiveFeed(factory: DiscoveryFeedFactory, feedOptions: DiscoveryFeedOptions, { perSource, firstScreen, firstScreenMs, onLanded }?: ProgressiveFeedSettings): ProgressiveDiscoveryFeed;