@recursiv/sdk 0.7.70 → 0.7.71

package/dist/resources/discovery-first-screen.js

@@ -0,0 +1,149 @@
+import { DISCOVERY_RAIL_LANE, DISCOVERY_STORY_LANE, DiscoveryEngagementMerge, discoveryLeadable, discoveryModuleLane, discoveryShowsMedia, discoveryTopPlace, isColumnModule, isDiscoveryPostModule, poolDiscoveryGalleries, promotedDiscoveryVideoItems, } from './discovery-merge.js';
+// ──────────────────────────────────────────────────────────────────────────
+// Discover's first screen, composed from every source that answered in time.
+// Ported from the Minds app (lib/firstScreen, 2026-10-04).
+//
+// Live (Minds, 2026-09-27) five of six categories opened on one network and
+// none opened on a post by a Minds member: each source's page was drawn the
+// moment it landed, so the open networks' fast trend reads filled the screen
+// before Minds landed. The first load of a progressive feed
+// (createProgressiveFeed) holds its sources' parts until Minds and one other
+// network have answered, or its wait has passed since the first of them
+// answered, and hands them on as one part in this order:
+//
+//  - it leads with a post that opens on a picture or a video (one post, or a
+//    gallery whose first card has one), from the best of the screen by
+//    engagement (FIRST_SCREEN_LEAD_WINDOW). A story, a suggestion rail, a
+//    video strip or a conversation never leads, and neither does a sensitive
+//    Minds post or an open-network post that links a porn site;
+//  - then the posts by engagement, every source's together
+//    (DiscoveryEngagementMerge), with the network mix as a soft constraint. A
+//    column of several posts goes in from FIRST_SCREEN_FEATURE_SLOT on;
+//  - the row under the lead is the best post from another network, while the
+//    screen has one of the same standing (FIRST_SCREEN_NETWORK_ROWS): a
+//    desktop or phone screen shows the lead and that one row, and live
+//    (2026-10-05) 7 of 8 category screens showed two posts of one network;
+//  - a story goes in as the third row (FIRST_SCREEN_STORY_SLOT), never right
+//    under another story, and a suggestion rail as the fifth
+//    (FIRST_SCREEN_RAIL_SLOT);
+//  - nothing is dropped. The sources' galleries are pooled into one.
+//
+// With the top of the feed (DiscoveryFeedSessionOptions.top: the posts a
+// member is most likely to engage with, each marked with its place), the
+// top's posts go first, in the top's order. A video may lead too: when the
+// top's first post is a video that can play, it is the screen's first row.
+// ──────────────────────────────────────────────────────────────────────────
+/** The row a story takes when there are posts enough above it: under the lead and one other post. */
+export const FIRST_SCREEN_STORY_SLOT = 2;
+/** The row a suggestion rail takes. */
+export const FIRST_SCREEN_RAIL_SLOT = 4;
+/** How far down the screen's engagement order a post may be and still lead it for its picture: about one screen. */
+export const FIRST_SCREEN_LEAD_WINDOW = 8;
+/** The first row a column of several posts (a conversation, a thread) may take. */
+export const FIRST_SCREEN_FEATURE_SLOT = 3;
+/** The first rows that each come from a network no row above them does, while the screen has one: the lead and the row under it. */
+export const FIRST_SCREEN_NETWORK_ROWS = 2;
+const isPostItem = (item) => item.kind === 'minds' || item.kind === 'social';
+/**
+ * A module that opens on a picture or a video: one post that shows one, or a gallery whose first card does. A column
+ * of posts whose picture is further down opens on text, and a video strip is not a post's picture.
+ */
+export function moduleOpensOnPicture(module) {
+    const first = module.items[0];
+    if (!first || !isPostItem(first) || !discoveryShowsMedia(first))
+        return false;
+    const presentation = module.presentation;
+    return module.items.length === 1 ? presentation !== 'video' : presentation === 'visual';
+}
+/** One post the reader may be shown first whose video can play. */
+function opensOnVideo(module) {
+    const first = module.items[0];
+    return module.items.length === 1 && !!first && isPostItem(first) && discoveryLeadable(first) && promotedDiscoveryVideoItems([first]).length > 0;
+}
+/** The top's first post (the smallest place among the modules), when it is a video that can play: it leads the screen. */
+export function discoveryTopVideoLead(modules) {
+    let first;
+    let place = Number.POSITIVE_INFINITY;
+    for (const module of modules) {
+        const at = discoveryTopPlace(module);
+        if (at !== null && at < place) {
+            first = module;
+            place = at;
+        }
+    }
+    return first && opensOnVideo(first) ? first : undefined;
+}
+/** A module of posts only, every one of them one the reader may be shown first, and never a video strip. */
+function mayLead(module) {
+    const presentation = module.presentation;
+    const posts = module.items.filter(isPostItem);
+    return presentation !== 'video' && posts.length > 0 && posts.length === module.items.length && posts.every(discoveryLeadable);
+}
+/**
+ * The first screen's modules, from the parts that landed (in landing order), in the order described above. Pure for a
+ * given `now` (the time the posts' ages are counted to): the same parts give the same screen.
+ * `keepLead`: the parts' first module is the lead already (a composed screen a client recomposes after moving its
+ * clips into a strip of its own).
+ */
+export function composeFirstScreen(parts, { keepLead = false, now = Date.now() } = {}) {
+    const modules = parts.flatMap(part => part.modules);
+    if (modules.length < 2)
+        return [...modules];
+    const kept = keepLead ? modules[0] : undefined;
+    // Equal scores keep each source's own order: a post's place among its source's posts, then its source, Minds first
+    // and the others as they landed. A pooled gallery, and a card of one that goes in as a post, take the gallery's place.
+    const lanes = [...new Set(modules.filter(isDiscoveryPostModule).map(discoveryModuleLane))].sort((a, b) => (a === 'minds' ? -1 : b === 'minds' ? 1 : 0));
+    const standing = new Map();
+    for (const part of parts) {
+        let place = 0;
+        for (const module of part.modules) {
+            if (!isDiscoveryPostModule(module))
+                continue;
+            standing.set(module.id, place++ * Math.max(1, lanes.length) + lanes.indexOf(discoveryModuleLane(module)));
+        }
+    }
+    const order = (module, index) => standing.get(module.id) ?? standing.get(module.id.split('~')[0]) ?? modules.length * lanes.length + index;
+    const pooled = poolDiscoveryGalleries(modules, now, kept);
+    const merge = new DiscoveryEngagementMerge(pooled.filter(isDiscoveryPostModule), { now, order });
+    const stories = pooled.filter(module => module !== kept && discoveryModuleLane(module) === DISCOVERY_STORY_LANE);
+    const rails = pooled.filter(module => module !== kept && discoveryModuleLane(module) === DISCOVERY_RAIL_LANE);
+    // The lead: the top's first post when it is a video that can play; else the best post near the top of the screen's
+    // engagement order that opens on a picture or a video; else the best single post; else the best post.
+    const best = merge.rest().filter(mayLead);
+    const lead = kept
+        ?? discoveryTopVideoLead(pooled)
+        ?? best.slice(0, FIRST_SCREEN_LEAD_WINDOW).find(moduleOpensOnPicture)
+        ?? best.find(module => !isColumnModule(module)) ?? best[0];
+    const out = [];
+    if (lead) {
+        merge.remove(lead);
+        out.push(lead);
+    }
+    const storyFits = () => {
+        const above = out[out.length - 1];
+        return out.length >= FIRST_SCREEN_STORY_SLOT && !!above && discoveryModuleLane(above) !== DISCOVERY_STORY_LANE;
+    };
+    for (;;) {
+        const [story] = stories;
+        const [rail] = rails;
+        if (story && storyFits()) {
+            out.push(story);
+            stories.shift();
+            continue;
+        }
+        if (rail && out.length >= FIRST_SCREEN_RAIL_SLOT && discoveryModuleLane(out[out.length - 1]) !== DISCOVERY_RAIL_LANE) {
+            out.push(rail);
+            rails.shift();
+            continue;
+        }
+        // Above FIRST_SCREEN_FEATURE_SLOT a column waits for the single posts of its standing.
+        const post = merge.take(out, { singles: out.length < FIRST_SCREEN_FEATURE_SLOT, newNetwork: out.length < FIRST_SCREEN_NETWORK_ROWS });
+        if (post) {
+            out.push(post);
+            continue;
+        }
+        break;
+    }
+    // Too few posts to reach their rows: a story or a rail still waiting goes in at the end.
+    return [...out, ...stories, ...rails];
+}

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

@@ -0,0 +1,144 @@
+import type { DiscoveryItem, DiscoveryModule, DiscoveryPostItem } from './discovery.js';
+/** A radar story's lane (discoveryModuleLane). */
+export declare const DISCOVERY_STORY_LANE = "story";
+/** A suggestion rail's lane (groups, people, tags). */
+export declare const DISCOVERY_RAIL_LANE = "rail";
+/** Rows the network share is counted over... */
+export declare const DISCOVERY_NETWORK_WINDOW = 20;
+/** ...and the most of them one network may take (40%). */
+export declare const DISCOVERY_NETWORK_ROWS_MAX = 8;
+/** The most rows in a row one network may take. */
+export declare 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 declare const DISCOVERY_MINDS_GAP_MAX = 5;
+/** Rows that separate two modules with the same title: more than a screen. */
+export declare 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 declare const DISCOVERY_FRESH_MS: number;
+/** The score halves with every this many hours of a post's age. */
+export declare const DISCOVERY_HALF_LIFE_HOURS = 24;
+/** A video that can play, and a picture, against a text post with the same engagement. */
+export declare const DISCOVERY_VIDEO_BOOST = 1.5;
+export declare const DISCOVERY_PICTURE_BOOST = 1.15;
+/** The least a network's (or the batch's) typical engagement is taken to be, in points. */
+export declare 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 declare const DISCOVERY_FRESH_NORM = 0.5;
+export declare const DISCOVERY_UNKNOWN_NORM = 0.5;
+/** A pooled gallery's cards, and the most of them from one network. */
+export declare const DISCOVERY_POOLED_GALLERY_MAX = 12;
+export declare const DISCOVERY_GALLERY_NETWORK_MAX = 5;
+/**
+ * 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 declare function mindsPostNetwork(post: {
+    author?: {
+        username?: string | null;
+    } | null;
+} | null | undefined): 'minds' | 'activitypub';
+/** The network a post item comes from: 'minds' only for a Minds member's own post. */
+export declare function discoveryPostNetwork(item: DiscoveryPostItem): string;
+/** 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 declare function discoveryModuleLane(module: DiscoveryModule): string;
+/** A module of posts (a post, a gallery, a conversation, a strip of clips): what the merge orders. */
+export declare function isDiscoveryPostModule(row: unknown): row is DiscoveryModule;
+/** 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 declare function discoveryRowTitle(row: unknown): string | null;
+/**
+ * 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 declare function discoveryLeadable(item: DiscoveryPostItem): boolean;
+/** A post with a picture or a video of its own that the reader sees unblurred. */
+export declare function discoveryShowsMedia(item: DiscoveryPostItem): boolean;
+/** A player found this video file (or HLS playlist) will not play: no Discover module promotes it, and it gets no video boost. */
+export declare function reportDiscoveryVideoUnavailable(url: string): void;
+/** Forget every report (a test seam, or a new viewer). */
+export declare function resetDiscoveryVideoReports(): void;
+/**
+ * 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 declare function promotableDiscoveryVideo(entry: unknown): boolean;
+/** A module's items whose post has a video that can play (promotableDiscoveryVideo). */
+export declare function promotedDiscoveryVideoItems<T extends DiscoveryItem>(items: readonly T[]): T[];
+/**
+ * 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 declare function discoveryEngagementPoints(item: DiscoveryPostItem): number | null;
+/** A batch's typical engagement: per network (by who counted it), and over the whole batch. */
+export interface DiscoveryEngagementReference {
+    networks: ReadonlyMap<string, number>;
+    batch: number;
+}
+/** The typical engagement of a batch of posts: the median of the posts with any, held to at least DISCOVERY_REFERENCE_FLOOR. */
+export declare function discoveryEngagementReference(items: readonly DiscoveryPostItem[]): DiscoveryEngagementReference;
+/** A post's place in the merge: its tier (0: engaged, fresh or unknown; 1: stale with no engagement) and its score. */
+export interface DiscoveryItemRank {
+    tier: 0 | 1;
+    score: number;
+}
+/** A post's tier and score in a batch. `now`: the time the scores are for. */
+export declare function rankDiscoveryItem(item: DiscoveryPostItem, reference: DiscoveryEngagementReference, now: number): DiscoveryItemRank;
+/** A module's best post: the lowest tier, then the highest score. Null for a module with no posts. */
+export declare function rankDiscoveryModule(module: DiscoveryModule, reference: DiscoveryEngagementReference, now: number): DiscoveryItemRank | null;
+/** 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 declare function discoveryTopPlace(module: DiscoveryModule): number | null;
+/** Several posts of one network one under another (a conversation, a thread of more than two): a screenful of one source. */
+export declare function isColumnModule(module: DiscoveryModule): boolean;
+/**
+ * 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 declare function poolDiscoveryGalleries(modules: readonly DiscoveryModule[], now: number, keep?: DiscoveryModule): DiscoveryModule[];
+/**
+ * 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 declare class DiscoveryEngagementMerge {
+    private left;
+    constructor(modules: readonly DiscoveryModule[], { now, order }?: {
+        now?: number;
+        order?: (module: DiscoveryModule, index: number) => number;
+    });
+    get size(): number;
+    /** The modules not taken yet, best first. */
+    rest(): DiscoveryModule[];
+    /** Whether a module is still to be taken. */
+    has(module: DiscoveryModule): boolean;
+    /** Takes this module out of the batch (a screen's lead). */
+    remove(module: DiscoveryModule): void;
+    /**
+     * 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: ReadonlyArray<unknown>, { singles, newNetwork }?: {
+        singles?: boolean;
+        newNetwork?: boolean;
+    }): DiscoveryModule | undefined;
+}
+/** 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 declare function weaveDiscoveryArrival<T extends {
+    id: string;
+}>(rows: readonly T[], arriving: readonly T[], reached: ReadonlySet<string>, floor?: number): T[];
+/**
+ * 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 declare function mergeDiscoveryArrival<T extends {
+    id: string;
+}>(rows: readonly T[], arriving: readonly T[], reached: ReadonlySet<string>, floor?: number, now?: number): T[];