feedkeeper 0.25.0 → 0.26.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "feedkeeper",
-  "version": "0.25.0",
+  "version": "0.26.0",
   "description": "A lightweight, self-hosted RSS reader and remote MCP server for your news, blogs, and AI workflows.",
   "keywords": [
     "rss",

package/server/dist/api/v1/index.js

@@ -38,6 +38,7 @@ const FEATURES = [
     "native-preferences",
     "native-preferences.edition-size",
     "edition.overview",
+    "edition.layout",
     "search.fts",
     "account-capabilities",
     "mcp",

package/server/dist/db/migrations/0034_edition_layout.sql

@@ -0,0 +1,2 @@
+-- Optional presentation plan for native editions; null for automatic and unstructured issues.
+ALTER TABLE editions ADD COLUMN layout TEXT CHECK (layout IS NULL OR json_valid(layout));

package/server/dist/mcp/server.js

@@ -500,7 +500,7 @@ export function createMcpServerForUser(userId, scope) {
     if (scope === "write")
         server.registerTool("publish_edition", {
             title: "Publish curated edition",
-            description: "Publishes an ordered list of 1 to 24 accessible article IDs. Curated editions override automatic ones until expiry (default 24 hours, maximum seven days). App-only hidden sections and muted keywords are respected. Supply the revision from get_edition as expectedRevision and a UUID requestId for conflict detection and safe retries. Optional title and summary are editorial text; original articles stay unchanged.",
+            description: "Publishes an ordered list of 1 to 24 accessible article IDs. Curated editions override automatic ones until expiry (default 24 hours, maximum seven days). App-only hidden sections and muted keywords are respected. Supply the revision from get_edition as expectedRevision and a UUID requestId for conflict detection and safe retries. Optional title and summary are editorial text; original articles stay unchanged. Optional layout (version 1) says how the issue is set: a character (dominant, calm or briefing) and blocks (lead, dossier, feature, standard, briefs, photo, quote) that reference the issue's article IDs at most once each; it never changes the articles.",
             inputSchema: publishEditionFields,
         }, async (input) => capabilityAction("editions", () => publishCuratedEdition(userId, input)));
     if (scope === "write")

package/server/dist/native/editionLayout.js

@@ -0,0 +1,66 @@
+import { z } from "zod";
+import { NativeError } from "./requests.js";
+/**
+ * A presentation plan for an edition. It says what the issue's writer considers important and what belongs together,
+ * never how a screen draws it: clients map the roles onto their own columns, sizes and type.
+ *
+ * Versioned and strict. A client that meets a block type it does not know sets that block's stories as plain ones.
+ */
+const itemId = z.number().int().positive();
+/** A short label above a headline: a classification, not a statement. */
+const kicker = z.string().trim().min(1).max(40)
+    .refine((value) => !/[\r\n]/.test(value) && !/[.!?:;,]$/.test(value), "A kicker is one short phrase without closing punctuation");
+const story = { itemId, kicker: kicker.optional() };
+const block = z.discriminatedUnion("type", [
+    /** The story of the day; only once and only first. */
+    z.object({ type: z.literal("lead"), ...story }).strict(),
+    /** One overview topic (1-based position in `overview`) with the stories it is about. */
+    z.object({ type: z.literal("dossier"), topic: z.number().int().min(1).max(5), itemIds: z.array(itemId).min(1).max(4) }).strict(),
+    z.object({ type: z.literal("feature"), ...story }).strict(),
+    z.object({ type: z.literal("standard"), stories: z.array(z.object(story).strict()).min(1).max(3) }).strict(),
+    z.object({ type: z.literal("briefs"), itemIds: z.array(itemId).min(2).max(8), title: z.string().trim().min(1).max(60).optional() }).strict(),
+    z.object({ type: z.literal("photo"), itemId }).strict(),
+    /** A statement of an article set large. The issuer vouches that the text is quoted from the article. */
+    z.object({ type: z.literal("quote"), itemId, text: z.string().trim().min(1).max(160) }).strict(),
+]);
+export const editionLayoutSchema = z.object({
+    version: z.literal(1),
+    character: z.enum(["dominant", "calm", "briefing"]),
+    blocks: z.array(block).min(1).max(24),
+}).strict();
+function blockItemIds(block) {
+    switch (block.type) {
+        case "standard": return block.stories.map((entry) => entry.itemId);
+        case "dossier":
+        case "briefs": return block.itemIds;
+        default: return [block.itemId];
+    }
+}
+/**
+ * Checks a well-formed plan against the issue it is published with: every story is in the issue and appears once,
+ * the lead stands first, and every topic exists and has one dossier at most.
+ */
+export function checkEditionLayout(layout, itemIds, topicCount) {
+    const allowed = new Set(itemIds);
+    const used = new Set();
+    const topics = new Set();
+    layout.blocks.forEach((block, index) => {
+        if (block.type === "lead" && index !== 0)
+            throw new NativeError("invalid_layout");
+        if (block.type === "dossier") {
+            if (block.topic > topicCount)
+                throw new NativeError("invalid_layout_reference");
+            if (topics.has(block.topic))
+                throw new NativeError("invalid_layout");
+            topics.add(block.topic);
+        }
+        for (const id of blockItemIds(block)) {
+            if (!allowed.has(id))
+                throw new NativeError("invalid_layout_reference");
+            if (used.has(id))
+                throw new NativeError("invalid_layout");
+            used.add(id);
+        }
+    });
+}
+//# sourceMappingURL=editionLayout.js.map

package/server/dist/native/editions.js

@@ -7,6 +7,7 @@ import { canAccessItem } from "../feeds/repository.js";
 import { decodeEntities } from "../feeds/text.js";
 import { editionPeriod, nextEditionBoundary, selectEdition } from "./editionSelection.js";
 import { getNativePreferences } from "./preferences.js";
+import { checkEditionLayout, editionLayoutSchema } from "./editionLayout.js";
 import { NativeError, nativeRequest } from "./requests.js";
 export const overviewSchema = z.array(z.object({
     heading: z.string().trim().min(1).max(160),
@@ -24,7 +25,8 @@ function serialize(row) {
         id: row.edition_id, revision: row.revision, source: row.source,
         createdAt: row.created_at, updatedAt: row.updated_at, expiresAt: row.expires_at,
         period: row.period?.split(":")[1] ?? editionPeriod(new Date(row.created_at), prefs.timeZone).period,
-        title: row.title, summary: row.summary, overview: row.overview ? JSON.parse(row.overview) : null, preferencesRevision: row.preferences_revision,
+        title: row.title, summary: row.summary, overview: row.overview ? JSON.parse(row.overview) : null, layout: row.layout ? JSON.parse(row.layout) : null,
+        preferencesRevision: row.preferences_revision,
         itemIds: JSON.parse(row.item_ids),
     };
 }
@@ -43,18 +45,19 @@ function checkRevision(userId, expectedRevision, now) {
     if (expectedRevision !== undefined && current.revision !== expectedRevision)
         throw new NativeError("revision_conflict", 409, current);
 }
-function writeEdition(userId, itemIds, source, expiry, now, title = null, summary = null, overview = null) {
+function writeEdition(userId, itemIds, source, expiry, now, title = null, summary = null, overview = null, layout = null) {
     const prefs = getNativePreferences(userId);
     const id = randomUUID();
     const revision = (storedEdition(userId)?.revision ?? 0) + 1;
     const created = now.toISOString();
-    db.prepare(`INSERT INTO editions (user_id, edition_id, item_ids, revision, source, status, created_at, updated_at, expires_at, period, title, summary, preferences_revision, overview)
-    VALUES (?, ?, ?, ?, ?, 'active', ?, ?, ?, ?, ?, ?, ?, ?)
+    db.prepare(`INSERT INTO editions (user_id, edition_id, item_ids, revision, source, status, created_at, updated_at, expires_at, period, title, summary, preferences_revision, overview, layout)
+    VALUES (?, ?, ?, ?, ?, 'active', ?, ?, ?, ?, ?, ?, ?, ?, ?)
     ON CONFLICT(user_id) DO UPDATE SET edition_id = excluded.edition_id, item_ids = excluded.item_ids,
       revision = excluded.revision, source = excluded.source, status = 'active', created_at = excluded.created_at,
       updated_at = excluded.updated_at, expires_at = excluded.expires_at, period = excluded.period,
-      title = excluded.title, summary = excluded.summary, preferences_revision = excluded.preferences_revision, overview = excluded.overview`)
-        .run(userId, id, JSON.stringify(itemIds), revision, source, created, created, expiry.toISOString(), editionPeriod(now, prefs.timeZone).key, title, summary, prefs.revision, overview ? JSON.stringify(overview.map((block, index) => ({ id: `topic-${index + 1}`, ...block }))) : null);
+      title = excluded.title, summary = excluded.summary, preferences_revision = excluded.preferences_revision, overview = excluded.overview,
+      layout = excluded.layout`)
+        .run(userId, id, JSON.stringify(itemIds), revision, source, created, created, expiry.toISOString(), editionPeriod(now, prefs.timeZone).key, title, summary, prefs.revision, overview ? JSON.stringify(overview.map((block, index) => ({ id: `topic-${index + 1}`, ...block }))) : null, layout ? JSON.stringify(layout) : null);
     db.prepare("INSERT INTO edition_history (user_id, edition_id, item_ids, revision, created_at) VALUES (?, ?, ?, ?, ?)")
         .run(userId, id, JSON.stringify(itemIds), revision, created);
     db.prepare(`DELETE FROM edition_history WHERE user_id = ? AND edition_id NOT IN
@@ -71,11 +74,14 @@ export const publishEditionFields = {
     title: z.string().trim().min(1).max(200).optional(),
     summary: z.string().trim().min(1).max(2000).optional(),
     overview: overviewSchema.optional(),
+    layout: editionLayoutSchema.optional(),
 };
 const publishSchema = z.object(publishEditionFields).strict().refine((input) => !(input.expiresAt && input.durationHours), "Use expiresAt or durationHours, not both");
 /** Both automatic and MCP editions obey the app's hard exclusions. Read/saved articles
  * may be selected deliberately by an agent, but foreign and muted items cannot be published. */
 export function publishCuratedEdition(userId, input, now = new Date()) {
+    if (input.layout !== undefined && !editionLayoutSchema.safeParse(input.layout).success)
+        throw new NativeError("invalid_layout");
     const parsed = publishSchema.safeParse(input);
     if (!parsed.success)
         throw new NativeError("invalid_input");
@@ -88,6 +94,8 @@ export function publishCuratedEdition(userId, input, now = new Date()) {
             block.segments.some((segment) => segment.itemId !== undefined && !data.itemIds.includes(segment.itemId)))) {
             throw new NativeError("invalid_overview_reference");
         }
+        if (data.layout)
+            checkEditionLayout(data.layout, data.itemIds, data.overview?.length ?? 0);
         const prefs = getNativePreferences(userId);
         for (const id of data.itemIds) {
             if (!canAccessItem(userId, id))
@@ -103,7 +111,7 @@ export function publishCuratedEdition(userId, input, now = new Date()) {
         const expiry = data.expiresAt ? new Date(data.expiresAt) : new Date(now.getTime() + (data.durationHours ?? 24) * 3_600_000);
         if (expiry.getTime() <= now.getTime() || expiry.getTime() > now.getTime() + 168 * 3_600_000)
             throw new NativeError("invalid_expiry");
-        return writeEdition(userId, data.itemIds, "curated", expiry, now, data.title ?? null, data.summary ?? (data.overview?.map((block) => `${block.heading}: ${block.segments.map((segment) => segment.text).join("")}`).join("\n\n").slice(0, 2000).replace(/[\uD800-\uDBFF]$/, "") ?? null), data.overview ?? null);
+        return writeEdition(userId, data.itemIds, "curated", expiry, now, data.title ?? null, data.summary ?? (data.overview?.map((block) => `${block.heading}: ${block.segments.map((segment) => segment.text).join("")}`).join("\n\n").slice(0, 2000).replace(/[\uD800-\uDBFF]$/, "") ?? null), data.overview ?? null, data.layout ?? null);
     }, now);
 }
 /** Compatibility entry point for existing internal callers. New agents supply a
@@ -127,9 +135,76 @@ export function deleteEdition(userId) {
     dismissEdition(userId);
     return existed;
 }
+/** The automatic edition looks at every candidate; smaller limits are shortlists for an agent or the curator. */
+const AUTOMATIC_EDITION_LIMIT = 4000;
+/** How often each feed appeared in the editions of the last 72 hours, so a feed that was shown a lot waits its turn. */
+function recentSourceUse(userId, itemIds) {
+    const use = new Map();
+    for (let start = 0; start < itemIds.length; start += 500) {
+        const chunk = itemIds.slice(start, start + 500);
+        const rows = db.prepare(`SELECT i.feed_id FROM items i JOIN subscriptions s ON s.feed_id = i.feed_id AND s.user_id = ?
+       WHERE i.id IN (${chunk.map(() => "?").join(",")})`).all(userId, ...chunk);
+        for (const row of rows)
+            use.set(row.feed_id, (use.get(row.feed_id) ?? 0) + 1);
+    }
+    return use;
+}
+/**
+ * Takes candidates round by round, one per source: volume says nothing about relevance, so a feed with three
+ * articles a week competes on equal terms with one that posts eighty. Sources that were shown less lately (and are
+ * not yet in the head of the list) go first within a round; inside a source the better scored article goes first,
+ * and an article offered before only after the new ones.
+ */
+export function takeFairly(rest, head, recentUse) {
+    const queues = new Map();
+    for (const item of [...rest].sort((a, b) => Number(a.previouslySelected) - Number(b.previouslySelected) || b.score - a.score || b.id - a.id)) {
+        const queue = queues.get(item.subscriptionId);
+        if (queue)
+            queue.push(item);
+        else
+            queues.set(item.subscriptionId, [item]);
+    }
+    const inHead = new Map();
+    for (const item of head)
+        inHead.set(item.subscriptionId, (inHead.get(item.subscriptionId) ?? 0) + 1);
+    const order = [...queues.keys()].sort((a, b) => (inHead.get(a) ?? 0) - (inHead.get(b) ?? 0) || (recentUse.get(a) ?? 0) - (recentUse.get(b) ?? 0) ||
+        queues.get(b)[0].score - queues.get(a)[0].score || a - b);
+    const result = [];
+    for (let round = 0; result.length < rest.length; round++) {
+        for (const source of order) {
+            const item = queues.get(source)[round];
+            if (item)
+                result.push(item);
+        }
+    }
+    return result;
+}
+/**
+ * A source may fill at most its fair share of the shortlist (the size divided by the number of sources), however
+ * much it publishes; the surplus of busy feeds is left out instead of crowding out the rest. A shortlist that would
+ * become too small to choose from is topped up in the same fair order, so no account ends up with an empty one.
+ */
+export function fairShortlist(head, fairOrder, limit, sources) {
+    const share = Math.max(2, Math.ceil(limit / Math.max(1, sources)));
+    const used = new Map();
+    const kept = [];
+    const surplus = [];
+    for (const item of [...head, ...fairOrder]) {
+        const count = used.get(item.subscriptionId) ?? 0;
+        if (count < share) {
+            used.set(item.subscriptionId, count + 1);
+            kept.push(item);
+        }
+        else
+            surplus.push(item);
+    }
+    const minimum = Math.min(limit, 24);
+    return [...kept, ...surplus.slice(0, Math.max(0, minimum - kept.length))].slice(0, limit);
+}
 export function editionCandidates(userId, now = new Date(), limit = 200) {
     const prefs = getNativePreferences(userId);
-    const previous = new Set(db.prepare("SELECT item_ids FROM edition_history WHERE user_id = ? AND created_at >= ?").all(userId, new Date(now.getTime() - 72 * 3_600_000).toISOString()).flatMap((row) => JSON.parse(row.item_ids)));
+    const previousItemIds = db.prepare("SELECT item_ids FROM edition_history WHERE user_id = ? AND created_at >= ?").all(userId, new Date(now.getTime() - 72 * 3_600_000).toISOString()).flatMap((row) => JSON.parse(row.item_ids));
+    const previous = new Set(previousItemIds);
     // Fetch bounded candidates per source, so a busy feed cannot hide the others.
     const rows = db.prepare(`SELECT * FROM (
       SELECT i.id, i.feed_id, s.folder_id, i.title, i.link, i.content_snippet, i.image_url,
@@ -153,11 +228,12 @@ export function editionCandidates(userId, now = new Date(), limit = 200) {
         score: Math.pow(0.5, Math.max(0, now.getTime() - Date.parse(row.published)) / (18 * 3_600_000)) *
             (row.folder_id !== null && prefs.preferredFolderIds.includes(row.folder_id) ? 1.4 : 1),
     }));
-    // Candidate requests expose a diversified shortlist rather than only the busiest source.
-    if (limit < scored.length) {
+    // Candidate requests expose a shortlist in which every source has a fair chance, not only the busiest one.
+    if (limit < AUTOMATIC_EDITION_LIMIT) {
         const sorted = selectEdition(scored, { ...prefs, editionSize: Math.min(limit, 24), readingMinutes: null });
         const selected = new Set(sorted.map((item) => item.id));
-        return [...sorted, ...scored.filter((item) => !selected.has(item.id)).sort((a, b) => b.score - a.score || b.id - a.id)].slice(0, limit);
+        const rest = scored.filter((item) => !selected.has(item.id));
+        return fairShortlist(sorted, takeFairly(rest, sorted, recentSourceUse(userId, previousItemIds)), limit, new Set(scored.map((item) => item.subscriptionId)).size);
     }
     return scored.sort((a, b) => b.score - a.score || b.id - a.id);
 }
@@ -187,7 +263,7 @@ export function generateEdition(userId, input = {}, now = new Date()) {
         if (row?.status === "active" && !state.edition) {
             db.prepare("UPDATE editions SET status = 'expired', revision = revision + 1, updated_at = ? WHERE user_id = ?").run(now.toISOString(), userId);
         }
-        const chosen = selectEdition(editionCandidates(userId, now, 4000), prefs);
+        const chosen = selectEdition(editionCandidates(userId, now, AUTOMATIC_EDITION_LIMIT), prefs);
         if (!chosen.length)
             return state.edition;
         if (state.edition && JSON.stringify(state.edition.itemIds) === JSON.stringify(chosen.map((item) => item.id)))

package/server/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@feedkeeper/server",
-  "version": "0.25.0",
+  "version": "0.26.0",
   "private": true,
   "type": "module"
 }