pixivflow 3.0.1 → 3.0.3

package/dist/cli/fatalError.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Handles fatal errors, prints user-friendly messages, and exits the process.
+ *
+ * Failure Contract (Deploy `AGENTS.md` §25): a startup failure must be both
+ * human-readable *and* machine-readable. The human text is printed here; the
+ * structured log carries `stage` and the **error object** — never
+ * `error.message` alone, because that drops the contract fields a
+ * `PixivFlowError` subclass owns (`code`, `statusCode`, `cause`), which is the
+ * same class of defect as a log line rendered as `"error":{}`.
+ */
+export declare function handleFatalError(error: unknown, exit?: (code: number) => void): void;
+//# sourceMappingURL=fatalError.d.ts.map

package/dist/cli/fatalError.js

@@ -0,0 +1,45 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.handleFatalError = handleFatalError;
+const logger_1 = require("../logger");
+const errors_1 = require("../utils/errors");
+/**
+ * Handles fatal errors, prints user-friendly messages, and exits the process.
+ *
+ * Failure Contract (Deploy `AGENTS.md` §25): a startup failure must be both
+ * human-readable *and* machine-readable. The human text is printed here; the
+ * structured log carries `stage` and the **error object** — never
+ * `error.message` alone, because that drops the contract fields a
+ * `PixivFlowError` subclass owns (`code`, `statusCode`, `cause`), which is the
+ * same class of defect as a log line rendered as `"error":{}`.
+ */
+function handleFatalError(error, exit = (code) => process.exit(code)) {
+    if (error instanceof errors_1.ConfigError) {
+        console.error(`\n❌ Configuration Error: ${error.message}\n`);
+        logger_1.logger.error('Configuration error', { stage: 'application.startup', error });
+    }
+    else if (error instanceof errors_1.AuthenticationError) {
+        console.error('\n❌ Authentication Error');
+        console.error('════════════════════════════════════════════════════════════════');
+        console.error(error.message);
+        console.error('');
+        console.error('💡 Your refresh token may have expired or is invalid.');
+        console.error('   Please login again to get a new refresh token:');
+        console.error('');
+        console.error('   • Interactive login:  pixivflow login');
+        console.error('   • Headless login:     pixivflow login-headless');
+        console.error('════════════════════════════════════════════════════════════════\n');
+        logger_1.logger.error('Authentication failed', { stage: 'application.startup', error });
+    }
+    else {
+        logger_1.logger.error('Fatal error during application startup', {
+            stage: 'application.startup',
+            error: error instanceof Error ? error : String(error),
+        });
+        // Even an unrecognised failure must say something on the console; the log
+        // line alone is invisible to the operator who ran the command.
+        console.error(`\n❌ ${error instanceof Error ? error.message : String(error)}\n`);
+    }
+    exit(1);
+}
+//# sourceMappingURL=fatalError.js.map

package/dist/config/types.d.ts

@@ -12,12 +12,22 @@ export interface TopicDiscoveryConfig {
     sampleWorks?: number;
     /** Cache lifetime in days for the resolved tag space (default 7). */
     cacheDays?: number;
-    /** Minimum relatedness score for a tag to enter the space (default 0.18). */
+    /** Minimum relatedness score for a tag to enter the space (default 0.22). */
     minScore?: number;
     /** Ignore a fresh cache and re-discover now (default false). */
     refresh?: boolean;
     /** Include R-18 works in topic sampling and collection (default false). */
     includeR18?: boolean;
+    /**
+     * When related tags may be searched as their own recall channel (§topic-recall).
+     *
+     * - `'always'` (default): walk the whole resolved tag space every day.
+     * - `'when_seed_insufficient'`: search the topic tag first and only fall back
+     *   to related tags when it cannot fill `limit` for that day — a related tag
+     *   is a hint, never a substitute for the topic the operator asked for.
+     * - `'never'`: search the topic tag alone.
+     */
+    relatedTags?: 'always' | 'when_seed_insufficient' | 'never';
 }
 /** Candidate collection tuning for mode='topic'. */
 export interface CandidateCollectionConfig {

package/dist/config/validation.js

@@ -191,6 +191,9 @@ function validateConfig(config, location, databasePath) {
                 if (td.includeR18 !== undefined && typeof td.includeR18 !== 'boolean') {
                     errors.push(`targets[${index}].topicDiscovery.includeR18: Must be a boolean (got ${typeof td.includeR18})`);
                 }
+                if (td.relatedTags !== undefined && !['always', 'when_seed_insufficient', 'never'].includes(td.relatedTags)) {
+                    errors.push(`targets[${index}].topicDiscovery.relatedTags: Must be "always", "when_seed_insufficient" or "never" (got ${String(td.relatedTags)})`);
+                }
             }
             const cc = target.candidateCollection;
             if (cc) {

package/dist/download/NovelDownloader.d.ts

@@ -16,5 +16,16 @@ export declare class NovelDownloader {
     private readonly materializationPolicy;
     constructor(client: IPixivClient, database: IDatabase, fileService: IFileService, metadataDb?: Database | undefined, materializer?: MediaMaterializer, materializationPolicy?: MaterializationPolicy);
     download(novel: PixivNovel, tag: string, target: TargetConfig): Promise<DownloadedArtifact | undefined>;
+    /**
+     * Resolves the cover URL a novel should ship with (§novel-cover).
+     *
+     * Pixiv's "author set no cover" case is invisible in the API: the design it
+     * renders (title typeset on a template) is served from the same CDN path with
+     * a unique hash as a real cover, so the URL cannot decide. The candidate cover
+     * is therefore fetched once and its header inspected; Pixiv's design canvas is
+     * exactly 640x900. Anything that cannot be classified keeps the cover — a
+     * failed probe must never cost a real cover.
+     */
+    private resolveCoverUrl;
 }
 //# sourceMappingURL=NovelDownloader.d.ts.map

package/dist/download/NovelDownloader.js

@@ -226,10 +226,11 @@ class NovelDownloader {
             }
         }
         // Novel cover (§novel-cover): normalized to null for Pixiv's default
-        // placeholder, carried as a dedicated `novelcover` MediaAsset so TelePost
-        // can build `cover root + TXT reply` without positional guessing. The
-        // cover is never materialized locally — Telegram fetches it (via proxy).
-        const coverUrl = (0, novelCover_1.normalizeNovelCoverUrl)(typeof textResponse === 'string' ? undefined : textResponse.coverUrl);
+        // placeholder AND for Pixiv's generated design covers, carried as a
+        // dedicated `novelcover` MediaAsset so TelePost can build
+        // `cover root + TXT reply` without positional guessing. The cover is never
+        // materialized locally — Telegram fetches it (via proxy).
+        const coverUrl = await this.resolveCoverUrl(detail.id, typeof textResponse === 'string' ? undefined : textResponse.coverUrl);
         const coverAsset = coverUrl ? (0, novelCover_1.novelCoverAsset)(String(detail.id), coverUrl) : undefined;
         const downloadByAssetKey = new Map(assets.filter((a) => a.status === 'downloaded' && a.localPath)
             .map((a) => [`${a.kind}:${a.sourceId}`, a]));
@@ -398,6 +399,37 @@ class NovelDownloader {
             language: detectedLang ? `${detectedLang.name} (${detectedLang.code})` : undefined,
         };
     }
+    /**
+     * Resolves the cover URL a novel should ship with (§novel-cover).
+     *
+     * Pixiv's "author set no cover" case is invisible in the API: the design it
+     * renders (title typeset on a template) is served from the same CDN path with
+     * a unique hash as a real cover, so the URL cannot decide. The candidate cover
+     * is therefore fetched once and its header inspected; Pixiv's design canvas is
+     * exactly 640x900. Anything that cannot be classified keeps the cover — a
+     * failed probe must never cost a real cover.
+     */
+    async resolveCoverUrl(novelId, coverUrl) {
+        const normalized = (0, novelCover_1.normalizeNovelCoverUrl)(coverUrl);
+        if (!normalized)
+            return null;
+        try {
+            const cover = await this.client.downloadImage(normalized);
+            if ((0, novelCover_1.isPixivDesignCoverImage)(cover)) {
+                logger_1.logger.info(`Novel ${novelId} cover is a Pixiv design cover (${novelCover_1.PIXIV_DESIGN_COVER_WIDTH}x${novelCover_1.PIXIV_DESIGN_COVER_HEIGHT}); delivering without a cover`, { novelId, coverUrl: normalized, designCover: true });
+                return null;
+            }
+            return normalized;
+        }
+        catch (error) {
+            logger_1.logger.warn(`Novel ${novelId} cover probe failed; keeping the cover`, {
+                novelId,
+                coverUrl: normalized,
+                reason: error instanceof Error ? error.message : String(error),
+            });
+            return normalized;
+        }
+    }
 }
 exports.NovelDownloader = NovelDownloader;
 function buildMediaAssetById(mediaAsset, artifactIdValue) {

package/dist/download/novelCover.d.ts

@@ -2,12 +2,23 @@
  * Novel cover normalization (§novel-cover).
  *
  * Pixiv exposes the novel cover as `coverUrl` on the webview v2 text response.
- * Novels WITHOUT a custom cover return the stock "novel-cover-master-default"
- * placeholder — that is NOT a real cover and must never ship as Telegram
- * media. The normalized model is therefore `string | null`:
+ * Novels WITHOUT a custom cover used to return the stock
+ * "novel-cover-master-default" placeholder; today Pixiv instead RENDERS a
+ * per-novel design (floral / seasonal / genre template with the novel title
+ * typeset) and serves it from `novel-cover-master/img/...` with a unique hash,
+ * so it is URL-indistinguishable from an author cover. Those design covers are
+ * NOT real covers and must never ship as Telegram media, and no API field
+ * (app-api `novel/detail`, webview v2) marks them: the one reliable
+ * discriminator is the canvas Pixiv renders them on, always exactly 640x900
+ * (`PIXIV_DESIGN_COVER_*` below). The normalized model is therefore
+ * `string | null`:
  *
- *   real cover       → the Pixiv CDN URL (original size when derivable)
- *   default / absent → null
+ *   real cover             → the Pixiv CDN URL (original size when derivable)
+ *   default / design / absent → null
+ *
+ * Callers cannot tell a design cover from the URL alone, so the fetch-and-check
+ * step (`isPixivDesignCoverImage`) lives in the downloader; this module stays a
+ * pure URL/bytes helper.
  *
  * The cover rides the canonical MediaAsset contract with a dedicated
  * `novelcover` pixivKind, so consumers (TelePost) can distinguish it from
@@ -15,6 +26,20 @@
  * positional guessing.
  */
 import { MediaAsset } from '../domain/media/MediaAsset';
+/**
+ * The canvas Pixiv renders its built-in novel cover designs on. Every design
+ * observed in production (floral, seasonal sweets, treasure map, genre label)
+ * is delivered at exactly this size, while author covers keep their own
+ * dimensions (512x512, 768x768, 800x1200, 822x1200, 826x1169, 1024x1024 …).
+ */
+export declare const PIXIV_DESIGN_COVER_WIDTH = 640;
+export declare const PIXIV_DESIGN_COVER_HEIGHT = 900;
+/**
+ * True when the fetched cover bytes are one of Pixiv's generated designs.
+ * Unknown formats / unreadable payloads return false so callers fail open and
+ * keep the cover rather than dropping a real one.
+ */
+export declare function isPixivDesignCoverImage(cover: ArrayBuffer | Uint8Array | null | undefined): boolean;
 export declare function normalizeNovelCoverUrl(coverUrl?: string | null): string | null;
 export declare function novelCoverAsset(workId: string, coverUrl: string): MediaAsset;
 //# sourceMappingURL=novelCover.d.ts.map

package/dist/download/novelCover.js

@@ -1,17 +1,30 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.PIXIV_DESIGN_COVER_HEIGHT = exports.PIXIV_DESIGN_COVER_WIDTH = void 0;
+exports.isPixivDesignCoverImage = isPixivDesignCoverImage;
 exports.normalizeNovelCoverUrl = normalizeNovelCoverUrl;
 exports.novelCoverAsset = novelCoverAsset;
 /**
  * Novel cover normalization (§novel-cover).
  *
  * Pixiv exposes the novel cover as `coverUrl` on the webview v2 text response.
- * Novels WITHOUT a custom cover return the stock "novel-cover-master-default"
- * placeholder — that is NOT a real cover and must never ship as Telegram
- * media. The normalized model is therefore `string | null`:
+ * Novels WITHOUT a custom cover used to return the stock
+ * "novel-cover-master-default" placeholder; today Pixiv instead RENDERS a
+ * per-novel design (floral / seasonal / genre template with the novel title
+ * typeset) and serves it from `novel-cover-master/img/...` with a unique hash,
+ * so it is URL-indistinguishable from an author cover. Those design covers are
+ * NOT real covers and must never ship as Telegram media, and no API field
+ * (app-api `novel/detail`, webview v2) marks them: the one reliable
+ * discriminator is the canvas Pixiv renders them on, always exactly 640x900
+ * (`PIXIV_DESIGN_COVER_*` below). The normalized model is therefore
+ * `string | null`:
  *
- *   real cover       → the Pixiv CDN URL (original size when derivable)
- *   default / absent → null
+ *   real cover             → the Pixiv CDN URL (original size when derivable)
+ *   default / design / absent → null
+ *
+ * Callers cannot tell a design cover from the URL alone, so the fetch-and-check
+ * step (`isPixivDesignCoverImage`) lives in the downloader; this module stays a
+ * pure URL/bytes helper.
  *
  * The cover rides the canonical MediaAsset contract with a dedicated
  * `novelcover` pixivKind, so consumers (TelePost) can distinguish it from
@@ -19,9 +32,28 @@ exports.novelCoverAsset = novelCoverAsset;
  * positional guessing.
  */
 const MediaAsset_1 = require("../domain/media/MediaAsset");
+const imageDimensions_1 = require("../utils/imageDimensions");
 const DEFAULT_COVER_PATTERN = /novel-cover-(master-)?default/i;
 /** Strip the `/c/<spec>/` resizer segment to recover the original-size URL. */
 const RESIZED_COVER_PATTERN = /\/c\/[^/]+\/(novel-cover-master\/)/;
+/**
+ * The canvas Pixiv renders its built-in novel cover designs on. Every design
+ * observed in production (floral, seasonal sweets, treasure map, genre label)
+ * is delivered at exactly this size, while author covers keep their own
+ * dimensions (512x512, 768x768, 800x1200, 822x1200, 826x1169, 1024x1024 …).
+ */
+exports.PIXIV_DESIGN_COVER_WIDTH = 640;
+exports.PIXIV_DESIGN_COVER_HEIGHT = 900;
+/**
+ * True when the fetched cover bytes are one of Pixiv's generated designs.
+ * Unknown formats / unreadable payloads return false so callers fail open and
+ * keep the cover rather than dropping a real one.
+ */
+function isPixivDesignCoverImage(cover) {
+    const dimensions = (0, imageDimensions_1.readImageDimensions)(cover);
+    return (dimensions?.width === exports.PIXIV_DESIGN_COVER_WIDTH &&
+        dimensions?.height === exports.PIXIV_DESIGN_COVER_HEIGHT);
+}
 function normalizeNovelCoverUrl(coverUrl) {
     const url = typeof coverUrl === 'string' ? coverUrl.trim() : '';
     if (!url)

package/dist/index.js

@@ -7,36 +7,9 @@ const CommandRegistry_1 = require("./commands/CommandRegistry");
 const CommandResultRenderer_1 = require("./commands/CommandResultRenderer");
 const commands_1 = require("./commands");
 const ArgumentParser_1 = require("./cli/ArgumentParser");
+const fatalError_1 = require("./cli/fatalError");
 const errors_1 = require("./utils/errors");
 const schedules_1 = require("./scheduler/schedules");
-/**
- * Handles fatal errors, prints user-friendly messages, and exits the process.
- */
-function handleFatalError(error) {
-    if (error instanceof errors_1.ConfigError) {
-        console.error(`\n❌ Configuration Error: ${error.message}\n`);
-        logger_1.logger.error('Configuration error', { error: error.message });
-    }
-    else if (error instanceof errors_1.AuthenticationError) {
-        console.error('\n❌ Authentication Error');
-        console.error('════════════════════════════════════════════════════════════════');
-        console.error(error.message);
-        console.error('');
-        console.error('💡 Your refresh token may have expired or is invalid.');
-        console.error('   Please login again to get a new refresh token:');
-        console.error('');
-        console.error('   • Interactive login:  pixivflow login');
-        console.error('   • Headless login:     pixivflow login-headless');
-        console.error('════════════════════════════════════════════════════════════════\n');
-        logger_1.logger.error('Authentication failed', { error: error.message });
-    }
-    else {
-        logger_1.logger.error('Fatal error during application startup', {
-            error: error instanceof Error ? error.stack ?? error.message : String(error),
-        });
-    }
-    process.exit(1);
-}
 /**
  * Executes the given command.
  */
@@ -106,10 +79,16 @@ async function executeCommand(registry, commandName, context, args) {
         }
     }
     catch (error) {
+        // Pass the error itself: the logger expands it into
+        // `{name, message, stack, cause, …contract fields}`. A pre-formatted
+        // `error.stack` string dropped the `code` an operator greps for.
         logger_1.logger.error('Unexpected error during command execution', {
             command: commandName,
-            error: error instanceof Error ? error.stack ?? error.message : String(error),
+            stage: 'command.execute',
+            retryable: false,
+            error: error instanceof Error ? error : String(error),
         });
+        console.error((0, CommandResultRenderer_1.formatCommandFailure)({ error: error instanceof Error ? error : undefined }, commandName));
         process.exit(1);
     }
 }
@@ -125,15 +104,22 @@ async function executeDefaultBehavior(context, args) {
     try {
         const result = await command.execute(context, args);
         if (!result.success) {
-            logger_1.logger.error('Default command execution failed', { command: commandName, error: result.error });
-            process.exit(1);
+            logger_1.logger.error('Default command execution failed', {
+                command: commandName,
+                stage: 'command.execute',
+                reason: (0, CommandResultRenderer_1.commandFailureReason)(result, commandName),
+                retryable: false,
+                error: result.error,
+            });
+            console.error((0, CommandResultRenderer_1.formatCommandFailure)(result, commandName));
+            process.exit(result.exitCode ?? 1);
         }
         if (commandName === 'download') {
             process.exit(0);
         }
     }
     catch (error) {
-        handleFatalError(error);
+        (0, fatalError_1.handleFatalError)(error);
     }
 }
 /**
@@ -175,7 +161,7 @@ async function bootstrap() {
         config = (0, config_1.loadConfig)(configPath, isLoginCommand || isTokenOptional || !commandName);
     }
     catch (error) {
-        return handleFatalError(error);
+        return (0, fatalError_1.handleFatalError)(error);
     }
     const context = { config, logger: logger_1.logger, configPath };
     // --- Command execution ---
@@ -186,5 +172,5 @@ async function bootstrap() {
         await executeDefaultBehavior(context, commandArgs);
     }
 }
-bootstrap().catch(handleFatalError);
+bootstrap().catch(fatalError_1.handleFatalError);
 //# sourceMappingURL=index.js.map

package/dist/logger.js

@@ -13,17 +13,31 @@ const ctxStore = new node_async_hooks_1.AsyncLocalStorage();
  * non-enumerable — so a structured line carrying an error used to say
  * `"error":{}` and hide the failing stage (the exact shape that made
  * `pixivflow reconcile` undiagnosable in production). Errors are expanded
- * explicitly, `cause` included.
+ * explicitly, `cause` included, and every own enumerable field is kept:
+ * `PixivFlowError` subclasses carry the machine-readable contract there
+ * (`code`, `statusCode`, `url`, `isRateLimit`, `waitTime`, `itemId`,
+ * `itemType`), which is what the deploy Failure Contract requires an operator
+ * to be able to grep.
  */
 function serializeLogValue(value) {
     return JSON.stringify(value, (_key, item) => {
         if (item instanceof Error) {
-            return {
+            const serialized = {
                 name: item.name,
                 message: item.message,
-                ...(item.stack ? { stack: item.stack } : {}),
-                ...(item.cause !== undefined ? { cause: item.cause } : {}),
             };
+            for (const key of Object.keys(item)) {
+                if (!(key in serialized)) {
+                    serialized[key] = item[key];
+                }
+            }
+            if (item.stack) {
+                serialized.stack = item.stack;
+            }
+            if (item.cause !== undefined) {
+                serialized.cause = item.cause;
+            }
+            return serialized;
         }
         return item;
     });

package/dist/package.json

@@ -1,6 +1,6 @@
 {
   "type": "commonjs",
   "name": "pixivflow",
-  "version": "3.0.1",
+  "version": "3.0.3",
   "private": true
 }

package/dist/topic/TopicPipeline.d.ts

@@ -5,6 +5,12 @@ export interface TopicSelection {
     candidates: TopicCandidate[];
     selected: TopicCandidate[];
     resolvedTagCount: number;
+    /**
+     * Tags actually searched for the day. Under `relatedTags: 'always'` this is
+     * the whole resolved space; under the seed-first modes it is the seed tag and
+     * only the related tags that were really needed (§topic-recall).
+     */
+    searchedTags?: string[];
     rawCount: number;
     dedupedCount: number;
     acceptedCount: number;
@@ -44,6 +50,15 @@ export declare class TopicPipeline {
     }>;
     private searchDay;
     private toCandidate;
+    /**
+     * Applies the metadata gate to everything collected so far. When nothing at
+     * all clears the threshold but the seed tag is present, the seed-tag works are
+     * kept anyway: a sparse day must stay usable instead of reporting "no
+     * candidates" for a topic that visibly has works. Extracted from selection so
+     * the seed pass can be evaluated before deciding whether the related channel
+     * is needed at all (§topic-recall).
+     */
+    private acceptedWorks;
     /**
      * Lightweight metadata relevance. Tags dominate (Pixiv's own taxonomy);
      * title/caption add smaller boosts. The seed tag is strong evidence.
@@ -56,8 +71,16 @@ export declare class TopicPipeline {
      * as on-topic, and the choice between accepted works is decided by popularity
      * alone. A work with a higher metadata score does NOT outrank a more popular
      * accepted work.
+     *
+     * `seedKey` adds a single tier in front of that popularity order and is only
+     * passed by the seed-first recall modes (§topic-recall): when related tags
+     * were reached as a fallback, a work that actually carries the topic tag must
+     * outrank a related-only work, and popularity decides within each tier. The
+     * default mode passes no `seedKey`, so the documented popularity-only ranking
+     * is unchanged.
      */
     private popCompare;
+    private rankCompare;
     private topByPopularity;
     private onDay;
     private normalize;

package/dist/topic/TopicPipeline.js

@@ -47,18 +47,24 @@ class TopicPipeline {
         const maxCandidates = this.bound(collect.maxCandidates, COLLECT_DEFAULTS.maxCandidates, 20, 500);
         const minMetadataScore = collect.minMetadataScore ?? COLLECT_DEFAULTS.minMetadataScore;
         const includeR18 = discovery.includeR18 === true;
+        // An unknown mode (hand-written config bypassing validation) falls back to
+        // the historical behaviour rather than silently narrowing recall.
+        const requestedMode = discovery.relatedTags;
+        const relatedMode = requestedMode === 'when_seed_insufficient' || requestedMode === 'never' ? requestedMode : 'always';
         const byId = new Map();
         let rawCount = 0;
         let aiExcludedCount = 0;
         let duplicateRemovedCount = 0;
         const tagNames = space.tags.map((t) => t.name);
-        for (let i = 0; i < tagNames.length; i++) {
-            if (byId.size >= maxCandidates)
-                break;
+        const seedKey = this.key(topic);
+        const seedTags = tagNames.filter((name) => this.key(name) === seedKey);
+        const relatedTags = tagNames.filter((name) => this.key(name) !== seedKey);
+        const searchedTags = [];
+        const collectTag = async (tag) => {
             // Cancellation is checked between tags, so a cancelled run stops issuing
             // new searches even when the aborted request itself had already returned.
             (0, errors_1.throwIfAborted)(this.signal, 'topic collection cancelled');
-            const tag = tagNames[i];
+            searchedTags.push(tag);
             const works = await this.searchDay(contentType, tag, day, maxPerTag, includeR18);
             rawCount += works.length;
             for (const work of works) {
@@ -75,26 +81,45 @@ class TopicPipeline {
                     break;
             }
             logger_1.logger.debug('[TopicCollector] type=' + contentType + ' tag=' + tag + ' day=' + day + ' fetched=' + works.length + ' pool=' + byId.size);
-            if (i < tagNames.length - 1 && this.requestDelayMs > 0)
-                await (0, promises_1.setTimeout)(this.requestDelayMs);
-        }
-        const dedupedCount = byId.size;
-        logger_1.logger.info('[TopicCollector] type=' + contentType + ' raw=' + rawCount + ' deduplicated=' + dedupedCount + ' aiExcluded=' + aiExcludedCount);
-        const seedKey = this.key(topic);
-        const accepted = [];
-        for (const entry of byId.values()) {
-            entry.candidate.metadataScore = this.metadataScore(entry.candidate, seedKey, tagScores);
-            if (entry.candidate.metadataScore >= minMetadataScore)
-                accepted.push(entry);
+        };
+        const runTags = async (names) => {
+            for (let i = 0; i < names.length; i++) {
+                if (byId.size >= maxCandidates)
+                    break;
+                await collectTag(names[i]);
+                if (i < names.length - 1 && this.requestDelayMs > 0)
+                    await (0, promises_1.setTimeout)(this.requestDelayMs);
+            }
+        };
+        // §topic-recall: a resolved tag space is a hierarchy, not a bag of
+        // interchangeable tags. 'always' keeps the historical behaviour — every
+        // resolved tag is a recall channel for the day. The seed-first modes search
+        // the topic tag the operator actually asked for and only walk the related
+        // channel when that cannot fill the target, so a second high-weight tag
+        // (丸吞) cannot take the only slot of a 西瓜肚 target.
+        if (seedTags.length === 0 || relatedMode === 'always') {
+            // No seed tag in the space (hand-written space): keep walking everything
+            // rather than returning nothing.
+            await runTags(seedTags.length === 0 ? tagNames : [...seedTags, ...relatedTags]);
         }
-        if (accepted.length === 0 && byId.size > 0) {
-            const fallback = [...byId.values()]
-                .filter((e) => e.candidate.tags.some((t) => this.key(t) === seedKey))
-                .sort((a, b) => b.candidate.popularity - a.candidate.popularity);
-            accepted.push(...fallback.slice(0, Math.max(limit, 1)));
-            logger_1.logger.warn('[MetadataTopicFilter] type=' + contentType + ' none above threshold ' + minMetadataScore + '; kept ' + accepted.length + ' seed-tag fallback');
+        else {
+            await runTags(seedTags);
+            const seedAccepted = this.acceptedWorks(byId, seedKey, tagScores, minMetadataScore, limit, contentType).length;
+            if (relatedMode === 'never') {
+                logger_1.logger.info('[TopicRecall] mode=never tag=' + topic + ' day=' + day + ' accepted=' + seedAccepted);
+            }
+            else if (seedAccepted < limit) {
+                logger_1.logger.info('[TopicRecall] mode=when_seed_insufficient tag=' + topic + ' seedAccepted=' + seedAccepted + '/' + limit + ' relatedTags=' + relatedTags.length + '; expanding');
+                await runTags(relatedTags);
+            }
+            else {
+                logger_1.logger.info('[TopicRecall] mode=when_seed_insufficient tag=' + topic + ' seedAccepted=' + seedAccepted + '/' + limit + '; related tags not searched');
+            }
         }
-        const chosen = this.topByPopularity(accepted, limit);
+        const dedupedCount = byId.size;
+        logger_1.logger.info('[TopicCollector] type=' + contentType + ' raw=' + rawCount + ' deduplicated=' + dedupedCount + ' aiExcluded=' + aiExcludedCount + ' searchedTags=' + searchedTags.length);
+        const accepted = this.acceptedWorks(byId, seedKey, tagScores, minMetadataScore, limit, contentType);
+        const chosen = this.topByPopularity(accepted, limit, relatedMode === 'always' ? undefined : seedKey);
         const selected = chosen.map((e) => e.candidate);
         logger_1.logger.info('[MetadataTopicFilter] accepted=' + accepted.length);
         if (selected[0]) {
@@ -106,6 +131,7 @@ class TopicPipeline {
                 candidates: [...byId.values()].map((e) => e.candidate),
                 selected,
                 resolvedTagCount: space.tags.length,
+                searchedTags,
                 rawCount,
                 dedupedCount,
                 acceptedCount: accepted.length,
@@ -150,6 +176,30 @@ class TopicPipeline {
             ...(work.illust_ai_type !== undefined ? { aiType: work.illust_ai_type } : {}),
         };
     }
+    /**
+     * Applies the metadata gate to everything collected so far. When nothing at
+     * all clears the threshold but the seed tag is present, the seed-tag works are
+     * kept anyway: a sparse day must stay usable instead of reporting "no
+     * candidates" for a topic that visibly has works. Extracted from selection so
+     * the seed pass can be evaluated before deciding whether the related channel
+     * is needed at all (§topic-recall).
+     */
+    acceptedWorks(byId, seedKey, tagScores, minMetadataScore, limit, contentType) {
+        const accepted = [];
+        for (const entry of byId.values()) {
+            entry.candidate.metadataScore = this.metadataScore(entry.candidate, seedKey, tagScores);
+            if (entry.candidate.metadataScore >= minMetadataScore)
+                accepted.push(entry);
+        }
+        if (accepted.length === 0 && byId.size > 0) {
+            const fallback = [...byId.values()]
+                .filter((e) => e.candidate.tags.some((t) => this.key(t) === seedKey))
+                .sort((a, b) => b.candidate.popularity - a.candidate.popularity);
+            accepted.push(...fallback.slice(0, Math.max(limit, 1)));
+            logger_1.logger.warn('[MetadataTopicFilter] type=' + contentType + ' none above threshold ' + minMetadataScore + '; kept ' + accepted.length + ' seed-tag fallback');
+        }
+        return accepted;
+    }
     /**
      * Lightweight metadata relevance. Tags dominate (Pixiv's own taxonomy);
      * title/caption add smaller boosts. The seed tag is strong evidence.
@@ -205,13 +255,31 @@ class TopicPipeline {
      * as on-topic, and the choice between accepted works is decided by popularity
      * alone. A work with a higher metadata score does NOT outrank a more popular
      * accepted work.
+     *
+     * `seedKey` adds a single tier in front of that popularity order and is only
+     * passed by the seed-first recall modes (§topic-recall): when related tags
+     * were reached as a fallback, a work that actually carries the topic tag must
+     * outrank a related-only work, and popularity decides within each tier. The
+     * default mode passes no `seedKey`, so the documented popularity-only ranking
+     * is unchanged.
      */
     popCompare(a, b) {
         return b.popularity - a.popularity;
     }
-    topByPopularity(items, limit) {
+    rankCompare(seedKey) {
+        if (!seedKey)
+            return (a, b) => this.popCompare(a, b);
+        const tier = (c) => (c.tags.some((t) => this.key(t) === seedKey) ? 0 : 1);
+        return (a, b) => {
+            const diff = tier(a) - tier(b);
+            return diff !== 0 ? diff : this.popCompare(a, b);
+        };
+    }
+    topByPopularity(items, limit, seedKey) {
         if (items.length <= limit)
-            return items.sort((a, b) => this.popCompare(a.candidate, b.candidate));
+            return items.sort((a, b) => this.rankCompare(seedKey)(a.candidate, b.candidate));
+        if (seedKey)
+            return items.sort((a, b) => this.rankCompare(seedKey)(a.candidate, b.candidate)).slice(0, limit);
         // O(n) top-`limit` selection (limit is tiny, e.g. 1); avoids a full sort.
         const top = [];
         for (const item of items) {

package/dist/topic/types.d.ts

@@ -35,6 +35,8 @@ export interface TopicSpace {
     sampledWorks: number;
     tags: ResolvedTag[];
 }
+/** When related tags may be used as their own recall channel (§topic-recall). */
+export type RelatedTagMode = 'always' | 'when_seed_insufficient' | 'never';
 export interface TopicDiscoveryOptions {
     /** Include R-18 works in topic sampling and collection (default false). */
     includeR18?: boolean;
@@ -43,6 +45,18 @@ export interface TopicDiscoveryOptions {
     cacheDays?: number;
     minScore?: number;
     refresh?: boolean;
+    /**
+     * Related-tag recall mode (default `'always'`).
+     *
+     * A resolved tag space is a hierarchy, not a bag of interchangeable tags: the
+     * seed tag is the topic the operator asked for and every other tag is a hint.
+     * Under `'always'` each resolved tag is searched for the day's works, so a
+     * second high-weight tag (丸吞) can occupy the only slot of a 西瓜肚 target.
+     * `'when_seed_insufficient'` searches the seed tag first and only walks the
+     * related channel when the seed cannot fill the limit for that day;
+     * `'never'` searches the seed tag alone.
+     */
+    relatedTags?: RelatedTagMode;
 }
 export interface TopicCollectOptions {
     maxPerTag?: number;

package/dist/utils/imageDimensions.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Intrinsic image dimensions read straight from the container header.
+ *
+ * PixivFlow ships no image decoder on purpose (§novel-cover): the only question
+ * it ever asks about a remote image is "what canvas is this?", and a handful of
+ * header bytes answer it for JPEG/PNG/GIF without decoding any pixels. Unknown
+ * containers, truncated input and non-image payloads return `undefined` so
+ * callers can fail open instead of guessing.
+ */
+export interface ImageDimensions {
+    width: number;
+    height: number;
+}
+/**
+ * Reads the intrinsic canvas of a JPEG, PNG or GIF payload.
+ * Returns `undefined` when the format is unknown or the header is incomplete.
+ */
+export declare function readImageDimensions(input: ArrayBuffer | Uint8Array | null | undefined): ImageDimensions | undefined;
+//# sourceMappingURL=imageDimensions.d.ts.map

package/dist/utils/imageDimensions.js

@@ -0,0 +1,95 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readImageDimensions = readImageDimensions;
+/** JPEG frame markers that carry the sample dimensions (SOF0..SOF15 minus DHT/JPG/DAC). */
+const JPEG_SOF_MARKERS = new Set([
+    0xc0, 0xc1, 0xc2, 0xc3, 0xc5, 0xc6, 0xc7, 0xc9, 0xca, 0xcb, 0xcd, 0xce, 0xcf,
+]);
+const PNG_SIGNATURE = [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a];
+function toBytes(input) {
+    if (!input)
+        return undefined;
+    if (input instanceof Uint8Array)
+        return input;
+    if (input instanceof ArrayBuffer)
+        return new Uint8Array(input);
+    return undefined;
+}
+function readPngDimensions(bytes) {
+    // signature (8) + chunk length (4) + "IHDR" (4) + width (4) + height (4)
+    if (bytes.length < 24)
+        return undefined;
+    for (let i = 0; i < PNG_SIGNATURE.length; i += 1) {
+        if (bytes[i] !== PNG_SIGNATURE[i])
+            return undefined;
+    }
+    if (!(bytes[12] === 0x49 && bytes[13] === 0x48 && bytes[14] === 0x44 && bytes[15] === 0x52)) {
+        return undefined;
+    }
+    const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+    return { width: view.getUint32(16), height: view.getUint32(20) };
+}
+function readGifDimensions(bytes) {
+    if (bytes.length < 10)
+        return undefined;
+    const magic = String.fromCharCode(bytes[0], bytes[1], bytes[2]);
+    if (magic !== 'GIF')
+        return undefined;
+    const width = bytes[6] | (bytes[7] << 8);
+    const height = bytes[8] | (bytes[9] << 8);
+    if (!width || !height)
+        return undefined;
+    return { width, height };
+}
+function readJpegDimensions(bytes) {
+    if (bytes.length < 4 || bytes[0] !== 0xff || bytes[1] !== 0xd8)
+        return undefined;
+    let offset = 2;
+    while (offset + 9 < bytes.length) {
+        if (bytes[offset] !== 0xff) {
+            offset += 1;
+            continue;
+        }
+        const marker = bytes[offset + 1];
+        // Fill bytes / standalone markers carry no payload.
+        if (marker === 0xff) {
+            offset += 1;
+            continue;
+        }
+        if (marker === 0x01 || (marker >= 0xd0 && marker <= 0xd8)) {
+            offset += 2;
+            continue;
+        }
+        if (marker === 0xda)
+            return undefined; // entropy-coded data: no frame header left
+        const length = (bytes[offset + 2] << 8) | bytes[offset + 3];
+        if (length < 2)
+            return undefined;
+        if (JPEG_SOF_MARKERS.has(marker)) {
+            const height = (bytes[offset + 5] << 8) | bytes[offset + 6];
+            const width = (bytes[offset + 7] << 8) | bytes[offset + 8];
+            if (!width || !height)
+                return undefined;
+            return { width, height };
+        }
+        offset += 2 + length;
+    }
+    return undefined;
+}
+/**
+ * Reads the intrinsic canvas of a JPEG, PNG or GIF payload.
+ * Returns `undefined` when the format is unknown or the header is incomplete.
+ */
+function readImageDimensions(input) {
+    const bytes = toBytes(input);
+    if (!bytes || bytes.length < 10)
+        return undefined;
+    if (bytes[0] === 0xff && bytes[1] === 0xd8)
+        return readJpegDimensions(bytes);
+    if (bytes[0] === 0x89 && bytes[1] === 0x50)
+        return readPngDimensions(bytes);
+    if (bytes[0] === 0x47 && bytes[1] === 0x49 && bytes[2] === 0x46)
+        return readGifDimensions(bytes);
+    return undefined;
+}
+//# sourceMappingURL=imageDimensions.js.map

package/dist/version.js

@@ -2,5 +2,5 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.BUILD = void 0;
 // GENERATED by scripts/write-version.js — do not edit manually.
-exports.BUILD = { version: '3.0.1', commit: '33362ac35c11' };
+exports.BUILD = { version: '3.0.3', commit: 'b01a93d49e63' };
 //# sourceMappingURL=version.js.map

package/dist/webui/package.json

@@ -1,6 +1,6 @@
 {
   "type": "commonjs",
   "name": "pixivflow-webui-backend",
-  "version": "3.0.1",
+  "version": "3.0.3",
   "description": "PixivFlow WebUI Backend - CommonJS module"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pixivflow",
-  "version": "3.0.1",
+  "version": "3.0.3",
   "description": "🎨 Pixiv 下载、筛选与自动收集工具 - 批量下载插画和小说、按标签/热度/日期筛选、定时任务与可靠 HTTP 交付 | Pixiv downloader and automation toolkit with filtering, scheduling and reliable HTTP delivery",
   "repository": {
     "type": "git",