pixivflow 2.38.0 → 2.40.0

package/dist/delivery/TelePressRichNovel.d.ts

@@ -1,4 +1,5 @@
 import type { DownloadedArtifact } from './types';
+import { type MediaAsset } from '../domain/media/MediaAsset';
 export interface RichNovelPreviewResult {
     /** Telegraph "read online" URL for the published page. */
     url: string;
@@ -25,11 +26,17 @@ export interface RichNovelManifestEntry {
     local: string;
     /** Original Pixiv CDN source URL (``https://i.pximg.net/...``). */
     source: string;
+    /** Canonical MediaAsset id (new contract, optional for backward compat). */
+    assetId?: string;
+    /** Canonical source URL (new contract; same as ``source`` today). */
+    sourceUrl?: string;
 }
 export interface RichNovelSources {
     txtPath: string;
     mdPath: string;
     imagePaths: string[];
+    /** Canonical media references derived from the novel metadata file. */
+    mediaAssets: MediaAsset[];
     /** Optional Pixiv CDN source map derived from the novel metadata file. */
     manifest: RichNovelManifestEntry[];
 }

package/dist/delivery/TelePressRichNovel.js

@@ -39,6 +39,8 @@ exports.publishRichNovelPreview = publishRichNovelPreview;
 const fs = __importStar(require("node:fs"));
 const path = __importStar(require("node:path"));
 const node_crypto_1 = require("node:crypto");
+const MediaAsset_1 = require("../domain/media/MediaAsset");
+const novelMarkers_1 = require("../download/novelMarkers");
 const logger_1 = require("../logger");
 const redact_1 = require("../utils/redact");
 /**
@@ -55,29 +57,84 @@ function interpolateEnv(value) {
         return resolved;
     });
 }
-/** Read ``{local, source}`` entries from the novel's metadata sidecar. */
-function readNovelManifest(artifact) {
+function isDownloadedPixivAsset(asset) {
+    return Boolean(asset && asset.status === 'downloaded' && asset.url && asset.localPath);
+}
+function isPendingPixivAsset(asset) {
+    return Boolean(asset && asset.status === 'pending' && asset.url && asset.sourceId && !asset.localPath);
+}
+/** Build a canonical MediaAsset without requiring a local file. */
+function mediaAssetFrom(asset, workId, localPath) {
+    const kind = asset.kind === 'uploadedimage' || asset.kind === 'pixivimage'
+        ? asset.kind
+        : undefined;
+    const source = String(asset.url);
+    if (!source || !kind)
+        return undefined;
+    return (0, MediaAsset_1.buildMediaAsset)({
+        workId,
+        kind,
+        sourceId: asset.sourceId ? String(asset.sourceId) : undefined,
+        marker: asset.marker ? String(asset.marker) : undefined,
+        sourceUrl: source,
+        artifactId: localPath,
+    });
+}
+/**
+ * Read the novel metadata sidecar into canonical `MediaAsset` values, plus the
+ * legacy `{local, source}` manifest projection (local is only a render hint for
+ * the markdown refs; source is the media fact).
+ */
+function readNovelMediaAssets(artifact) {
     const metadataFile = (artifact.cleanupFiles ?? []).find((f) => /\.json$/i.test(f));
-    if (!metadataFile || !fs.existsSync(metadataFile))
-        return [];
+    if (!metadataFile || !fs.existsSync(metadataFile)) {
+        return { mediaAssets: [], manifest: [] };
+    }
     try {
         const meta = JSON.parse(fs.readFileSync(metadataFile, 'utf8'));
         if (!Array.isArray(meta.assets))
-            return [];
-        const entries = [];
-        for (const asset of meta.assets) {
-            if (!asset || asset.status !== 'downloaded' || !asset.url || !asset.localPath)
-                continue;
+            return { mediaAssets: [], manifest: [] };
+        const workId = meta.pixiv_id ? String(meta.pixiv_id) : artifact.pixivId;
+        const mediaAssets = [];
+        const manifest = [];
+        const downloaded = meta.assets.filter(isDownloadedPixivAsset);
+        for (const asset of downloaded) {
             const source = String(asset.url);
             const localPath = String(asset.localPath);
-            if (!source || !localPath)
+            const media = mediaAssetFrom(asset, workId, localPath);
+            if (!media)
                 continue;
-            entries.push({ local: `images/${path.basename(localPath)}`, source });
+            mediaAssets.push(media);
+            manifest.push({
+                local: `images/${path.basename(localPath)}`,
+                source,
+                assetId: mediaAssets[mediaAssets.length - 1]?.id,
+                sourceUrl: source,
+            });
+        }
+        // On-demand previews: no local downloads for this work, but the metadata
+        // carries resolvable Pixiv CDN sources. Pass those through as pending
+        // references (no artifactId) so TelePress can proxy them without files.
+        if (mediaAssets.length === 0) {
+            for (const asset of meta.assets.filter(isPendingPixivAsset)) {
+                const source = String(asset.url);
+                const refName = (0, novelMarkers_1.novelReferenceFileName)(source, String(asset.sourceId));
+                const media = mediaAssetFrom(asset, workId);
+                if (!media)
+                    continue;
+                mediaAssets.push(media);
+                manifest.push({
+                    local: refName,
+                    source,
+                    assetId: mediaAssets[mediaAssets.length - 1]?.id,
+                    sourceUrl: source,
+                });
+            }
         }
-        return entries;
+        return { mediaAssets, manifest };
     }
     catch {
-        return [];
+        return { mediaAssets: [], manifest: [] };
     }
 }
 function findRichNovelSources(artifact) {
@@ -98,11 +155,13 @@ function findRichNovelSources(artifact) {
             .map((name) => path.join(imagesDir, name))
             .sort((a, b) => a.localeCompare(b, undefined, { numeric: true }));
     }
+    const { mediaAssets, manifest } = readNovelMediaAssets(artifact);
     return {
         txtPath,
         mdPath,
         imagePaths,
-        manifest: readNovelManifest(artifact),
+        mediaAssets,
+        manifest,
     };
 }
 /**
@@ -116,7 +175,7 @@ async function publishRichNovelPreview(artifact, options) {
     const sources = findRichNovelSources(artifact);
     if (!sources)
         return { url: '', retryable: false, operatorHint: 'no_rich_novel_assets' };
-    if (sources.imagePaths.length === 0) {
+    if (sources.imagePaths.length === 0 && sources.manifest.length === 0) {
         return { url: '', retryable: false, operatorHint: 'no_rich_novel_assets' };
     }
     const mdName = path.basename(sources.mdPath);

package/dist/delivery/types.d.ts

@@ -1,4 +1,6 @@
 import { DeliveryFieldValue } from '../config';
+import type { MediaAsset } from '../domain/media/MediaAsset';
+import type { Artifact } from '../domain/media/Artifact';
 export type DeliveryItemType = 'illustration' | 'novel';
 /** Files produced for one Pixiv work and needed by a delivery provider. */
 export interface DownloadedArtifact {
@@ -11,6 +13,10 @@ export interface DownloadedArtifact {
     files: string[];
     /** Optional per-file lightweight preview sources, aligned with ``files``. */
     previewFiles?: string[];
+    /** Canonical media facts for the work (remote source, stable id). */
+    mediaAssets?: MediaAsset[];
+    /** Canonical materialized file facts backing ``files``. */
+    artifacts?: Artifact[];
     /** Local sidecars deleted with cache files after successful delivery. */
     cleanupFiles?: string[];
     /** R-18 work (x_restrict > 0): delivery templates may open Telegram spoiler. */

package/dist/domain/media/Artifact.d.ts

@@ -0,0 +1,32 @@
+/**
+ * A materialized file produced for a work.
+ *
+ * `Artifact` is the file fact (which file, which variant), separate from
+ * `MediaAsset` (the media fact). Legacy `DownloadedArtifact.files[]` remains a
+ * compatibility projection until all consumers migrate.
+ */
+export type ArtifactVariant = 'original' | 'text' | 'markdown' | 'zip' | 'metadata' | 'delivery';
+export interface Artifact {
+    /** Stable deterministic id, derived from the work + variant, not delivery state. */
+    id: string;
+    /** When this file is a materialized medium, the source MediaAsset id. */
+    sourceAssetId?: string;
+    workId: string;
+    variant: ArtifactVariant;
+    path: string;
+    mimeType?: string;
+    size?: number;
+    checksum?: string;
+}
+/**
+ * Deterministic artifact identity: `pixiv:<workId>:<variant>:<basename>`.
+ * The basename may be empty for generated variants; callers should pass a sane
+ * label so the id stays unique within a work.
+ */
+export declare function artifactId(workId: string, variant: ArtifactVariant, label: string): string;
+/**
+ * Legacy projection: old consumers can keep reading `files[]`, which the new
+ * canonical list of artifacts backs. Only file-backed variants are projected.
+ */
+export declare function projectLegacyFiles(artifacts: Artifact[]): string[];
+//# sourceMappingURL=Artifact.d.ts.map

package/dist/domain/media/Artifact.js

@@ -0,0 +1,24 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.artifactId = artifactId;
+exports.projectLegacyFiles = projectLegacyFiles;
+/**
+ * Deterministic artifact identity: `pixiv:<workId>:<variant>:<basename>`.
+ * The basename may be empty for generated variants; callers should pass a sane
+ * label so the id stays unique within a work.
+ */
+function artifactId(workId, variant, label) {
+    const cleanWork = String(workId).trim();
+    const cleanLabel = String(label).trim();
+    return `pixiv:${cleanWork}:${variant}${cleanLabel ? `:${cleanLabel}` : ''}`;
+}
+/**
+ * Legacy projection: old consumers can keep reading `files[]`, which the new
+ * canonical list of artifacts backs. Only file-backed variants are projected.
+ */
+function projectLegacyFiles(artifacts) {
+    return artifacts
+        .filter((a) => Boolean(a && a.path))
+        .map((a) => a.path);
+}
+//# sourceMappingURL=Artifact.js.map

package/dist/domain/media/MaterializationPolicy.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Materialization policy: whether a resolved MediaAsset becomes a local file
+ * eagerly or is deferred for a consumer.
+ */
+export type MaterializationMode = 'eager' | 'on-demand';
+export interface MaterializationPolicy {
+    mode: MaterializationMode;
+}
+/** Production-safe default: eager (current behavior unchanged). */
+export declare const DEFAULT_MATERIALIZATION_POLICY: MaterializationPolicy;
+/** True when the policy says a resolved medium should be materialized now. */
+export declare function shouldMaterialize(policy: MaterializationPolicy): boolean;
+//# sourceMappingURL=MaterializationPolicy.d.ts.map

package/dist/domain/media/MaterializationPolicy.js

@@ -0,0 +1,11 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_MATERIALIZATION_POLICY = void 0;
+exports.shouldMaterialize = shouldMaterialize;
+/** Production-safe default: eager (current behavior unchanged). */
+exports.DEFAULT_MATERIALIZATION_POLICY = { mode: 'eager' };
+/** True when the policy says a resolved medium should be materialized now. */
+function shouldMaterialize(policy) {
+    return policy.mode === 'eager';
+}
+//# sourceMappingURL=MaterializationPolicy.js.map

package/dist/domain/media/MediaAsset.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Canonical media reference for a download work.
+ *
+ * `MediaAsset` is the media fact (remote source + stable identity). It is NOT a
+ * local file: consumers decide whether / when to materialize it. The legacy
+ * `DownloadedArtifact.files[]` compatibility projection stays in place until all
+ * consumers migrate.
+ */
+export type PixivMediaKind = 'uploadedimage' | 'pixivimage' | 'illust';
+export interface MediaSourceRef {
+    /** Pixiv work id, e.g. the novel/illust id. */
+    workId: string;
+    /** Pixiv-side image identifier (illust page / uploaded image id). */
+    sourceId?: string;
+    /** Original in-text marker, when known. */
+    marker?: string;
+    /** Pixiv-specific media subtype (uploadedimage vs pixivimage vs illust). */
+    pixivKind?: PixivMediaKind;
+}
+export interface MediaAsset {
+    /** Stable deterministic id, independent of any consumer/delivery system. */
+    id: string;
+    source: 'pixiv';
+    kind: 'image';
+    sourceUrl: string;
+    mimeType?: string;
+    width?: number;
+    height?: number;
+    page?: number;
+    /** Optional materialized file reference; never required. */
+    artifactId?: string;
+    sourceRef?: MediaSourceRef;
+}
+/**
+ * Deterministic stable identity: `pixiv:<workId>:<pixivKind>[:<sourceId>]`.
+ * Never carries Telegram/thelegraph/catbox ids.
+ */
+export declare function mediaAssetId(workId: string, pixivKind: PixivMediaKind, sourceId?: string): string;
+export interface MediaAssetInput {
+    workId: string;
+    kind: PixivMediaKind;
+    sourceId?: string;
+    marker?: string;
+    sourceUrl: string;
+    artifactId?: string;
+}
+/** Build a canonical MediaAsset from a resolved Pixiv media reference. */
+export declare function buildMediaAsset(input: MediaAssetInput): MediaAsset;
+//# sourceMappingURL=MediaAsset.d.ts.map

package/dist/domain/media/MediaAsset.js

@@ -0,0 +1,31 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.mediaAssetId = mediaAssetId;
+exports.buildMediaAsset = buildMediaAsset;
+/**
+ * Deterministic stable identity: `pixiv:<workId>:<pixivKind>[:<sourceId>]`.
+ * Never carries Telegram/thelegraph/catbox ids.
+ */
+function mediaAssetId(workId, pixivKind, sourceId) {
+    const cleanWork = String(workId).trim();
+    const cleanKind = String(pixivKind).trim();
+    const cleanSource = sourceId ? String(sourceId).trim() : '';
+    return `pixiv:${cleanWork}:${cleanKind}${cleanSource ? `:${cleanSource}` : ''}`;
+}
+/** Build a canonical MediaAsset from a resolved Pixiv media reference. */
+function buildMediaAsset(input) {
+    return {
+        id: mediaAssetId(input.workId, input.kind, input.sourceId),
+        source: 'pixiv',
+        kind: 'image',
+        sourceUrl: input.sourceUrl,
+        artifactId: input.artifactId,
+        sourceRef: {
+            workId: input.workId,
+            sourceId: input.sourceId,
+            marker: input.marker,
+            pixivKind: input.kind,
+        },
+    };
+}
+//# sourceMappingURL=MediaAsset.js.map

package/dist/domain/media/Work.d.ts

@@ -0,0 +1,27 @@
+import { type MediaAsset, type PixivMediaKind } from './MediaAsset';
+/** Minimal domain work descriptor; does not carry scheduler/delivery state. */
+export interface Work {
+    id: string;
+    type: 'novel' | 'illustration';
+    title?: string;
+    sourceUrl?: string;
+    tags?: string[];
+}
+/**
+ * Result of resolving a work WITHOUT materializing files: the work descriptor
+ * plus the canonical media facts consumers may choose to materialize.
+ */
+export interface ResolvedWork {
+    work: Work;
+    mediaAssets: MediaAsset[];
+}
+export interface WorkMediaInput {
+    workId: string;
+    kind: PixivMediaKind;
+    sourceId?: string;
+    marker?: string;
+    sourceUrl: string;
+}
+/** Build a ResolvedWork from already-fetched Pixiv detail + inline media refs. */
+export declare function toResolvedWork(work: Work, mediaInputs: WorkMediaInput[]): ResolvedWork;
+//# sourceMappingURL=Work.d.ts.map

package/dist/domain/media/Work.js

@@ -0,0 +1,12 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toResolvedWork = toResolvedWork;
+const MediaAsset_1 = require("./MediaAsset");
+/** Build a ResolvedWork from already-fetched Pixiv detail + inline media refs. */
+function toResolvedWork(work, mediaInputs) {
+    return {
+        work,
+        mediaAssets: mediaInputs.map((m) => (0, MediaAsset_1.buildMediaAsset)(m)),
+    };
+}
+//# sourceMappingURL=Work.js.map

package/dist/download/NovelDownloader.d.ts

@@ -4,13 +4,17 @@ import { IDatabase } from '../interfaces/IDatabase';
 import { IFileService } from '../interfaces/IFileService';
 import { PixivNovel } from '@redtidev/pixiv-client';
 import { DownloadedArtifact } from '../delivery/types';
+import { type MaterializationPolicy } from '../domain/media/MaterializationPolicy';
+import { type MediaMaterializer } from './materialization/MediaMaterializer';
 import type { Database } from '../storage/Database';
 export declare class NovelDownloader {
     private readonly client;
     private readonly database;
     private readonly fileService;
     private readonly metadataDb?;
-    constructor(client: IPixivClient, database: IDatabase, fileService: IFileService, metadataDb?: Database | undefined);
+    private readonly materializer;
+    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>;
 }
 //# sourceMappingURL=NovelDownloader.d.ts.map

package/dist/download/NovelDownloader.js

@@ -37,6 +37,10 @@ exports.NovelDownloader = void 0;
 const logger_1 = require("../logger");
 const node_path_1 = require("node:path");
 const language_detection_1 = require("../utils/language-detection");
+const Work_1 = require("../domain/media/Work");
+const MaterializationPolicy_1 = require("../domain/media/MaterializationPolicy");
+const Artifact_1 = require("../domain/media/Artifact");
+const MediaMaterializer_1 = require("./materialization/MediaMaterializer");
 const novelMarkers_1 = require("./novelMarkers");
 const zip_1 = require("../utils/zip");
 const LANGUAGE_CACHE_TTL_MS = 7 * 24 * 60 * 60 * 1000;
@@ -45,11 +49,15 @@ class NovelDownloader {
     database;
     fileService;
     metadataDb;
-    constructor(client, database, fileService, metadataDb) {
+    materializer;
+    materializationPolicy;
+    constructor(client, database, fileService, metadataDb, materializer, materializationPolicy = MaterializationPolicy_1.DEFAULT_MATERIALIZATION_POLICY) {
         this.client = client;
         this.database = database;
         this.fileService = fileService;
         this.metadataDb = metadataDb;
+        this.materializer = materializer ?? new MediaMaterializer_1.PixivMediaMaterializer(client, fileService);
+        this.materializationPolicy = materializationPolicy;
     }
     async download(novel, tag, target) {
         // Metadata cache: language filtering otherwise pulls FULL text per candidate
@@ -163,22 +171,52 @@ class NovelDownloader {
             ? []
             : (0, novelMarkers_1.extractNovelAssets)(text, textResponse);
         const hadImages = assets.length > 0;
-        const pendingAssets = assets.filter((a) => Boolean(a.url));
-        if (pendingAssets.length) {
+        // Step 6: resolve first (work + media facts), materialize second.
+        const resolved = (0, Work_1.toResolvedWork)({
+            id: String(detail.id),
+            type: 'novel',
+            title: detail.title,
+            sourceUrl: `https://www.pixiv.net/novel/show.php?id=${detail.id}`,
+            tags: tags.map((item) => item.name).filter(Boolean),
+        }, assets
+            .filter((a) => Boolean(a.url))
+            .map((a) => ({
+            workId: String(detail.id),
+            kind: a.kind,
+            sourceId: a.sourceId,
+            marker: a.marker,
+            sourceUrl: a.url,
+        })));
+        if (resolved.mediaAssets.length) {
             const imagesDir = (0, node_path_1.join)((0, node_path_1.dirname)(filePath), 'images');
-            for (const asset of pendingAssets) {
+            for (const mediaAsset of resolved.mediaAssets) {
+                if (!(0, MaterializationPolicy_1.shouldMaterialize)(this.materializationPolicy)) {
+                    continue; // on-demand: keep the media reference, defer local file creation
+                }
                 try {
-                    const buffer = await this.client.downloadImage(asset.url);
-                    asset.localPath = await this.fileService.saveBinary(buffer, novelAssetFileName(asset), imagesDir);
-                    asset.status = 'downloaded';
+                    const artifact = await this.materializer.materialize(mediaAsset, {
+                        variant: 'original',
+                        destination: imagesDir,
+                    });
+                    const key = `${mediaAsset.sourceRef?.pixivKind}:${mediaAsset.sourceRef?.sourceId}`;
+                    const asset = assets.find((a) => `${a.kind}:${a.sourceId}` === key);
+                    if (asset) {
+                        asset.localPath = artifact.path;
+                        asset.status = 'downloaded';
+                    }
                 }
                 catch (error) {
-                    asset.status = 'failed';
-                    asset.failureReason = error instanceof Error ? error.message : String(error);
-                    logger_1.logger.warn(`Failed to download novel inline image ${asset.sourceId} for novel ${detail.id}`, {
+                    const key = `${mediaAsset.sourceRef?.pixivKind}:${mediaAsset.sourceRef?.sourceId}`;
+                    const asset = assets.find((a) => `${a.kind}:${a.sourceId}` === key);
+                    if (asset) {
+                        asset.status = 'failed';
+                        asset.failureReason = error instanceof Error ? error.message : String(error);
+                    }
+                    const assetId = mediaAsset.sourceRef?.sourceId ?? 'unknown';
+                    logger_1.logger.warn(`Failed to download novel inline image ${assetId} for novel ${detail.id}`, {
                         novelId: detail.id,
-                        sourceId: asset.sourceId,
-                        reason: asset.failureReason,
+                        sourceId: assetId,
+                        reason: error instanceof Error ? error.message : String(error),
                     });
                 }
             }
@@ -186,13 +224,22 @@ class NovelDownloader {
                 logger_1.logger.info(`Novel ${detail.id} inline images: ${assets.filter((a) => a.status === 'downloaded').length}/${assets.length} downloaded`, { novelId: detail.id });
             }
         }
+        const downloadByAssetKey = new Map(assets.filter((a) => a.status === 'downloaded' && a.localPath)
+            .map((a) => [`${a.kind}:${a.sourceId}`, a]));
         // Rich-media markdown sidecar (RFC 1 Phase 2): same path as the .txt
         // (compat format stays), inline images become relative ![](images/x.jpg)
         // refs so a later TelePress/TelePost phase can render the Telegraph page.
         let richMediaPath;
-        if (assets.some((a) => a.status === 'downloaded')) {
+        const hasDownloadedImages = assets.some((a) => a.status === 'downloaded');
+        // On-demand mode (no local images) still emits a resolvable md sidecar from
+        // media references so TelePress can render via proxy without a download.
+        const hasResolvablePending = assets.some((a) => a.status === 'pending' && Boolean(a.url));
+        if (hasDownloadedImages || hasResolvablePending) {
             try {
-                const mdPath = await this.fileService.saveText(`${header}\n${(0, novelMarkers_1.renderNovelMarkdown)(text, assets)}`, fileName.replace(/\.txt$/, '.md'), metadata);
+                const mdContent = hasDownloadedImages
+                    ? (0, novelMarkers_1.renderNovelMarkdown)(text, assets)
+                    : (0, novelMarkers_1.renderNovelMarkdownReference)(text, assets);
+                const mdPath = await this.fileService.saveText(`${header}\n${mdContent}`, fileName.replace(/\.txt$/, '.md'), metadata);
                 richMediaPath = mdPath;
                 logger_1.logger.info(`Saved novel ${detail.id} rich-media markdown sidecar`, { filePath: mdPath });
             }
@@ -289,12 +336,45 @@ class NovelDownloader {
             filePath,
             ...(detectedLang ? { language: detectedLang.name, isChinese: detectedLang.isChinese } : {}),
         });
+        const workId = String(detail.id);
+        const mediaAssets = [];
+        const artifacts = [];
+        if (filePath) {
+            artifacts.push({ id: (0, Artifact_1.artifactId)(workId, 'text', (0, node_path_1.basename)(filePath)), workId, variant: 'text', path: filePath });
+        }
+        if (richMediaPath) {
+            artifacts.push({ id: (0, Artifact_1.artifactId)(workId, 'markdown', (0, node_path_1.basename)(richMediaPath)), workId, variant: 'markdown', path: richMediaPath });
+        }
+        if (metadataPath) {
+            artifacts.push({ id: (0, Artifact_1.artifactId)(workId, 'metadata', (0, node_path_1.basename)(metadataPath)), workId, variant: 'metadata', path: metadataPath });
+        }
+        if (archivePath) {
+            artifacts.push({ id: (0, Artifact_1.artifactId)(workId, 'zip', (0, node_path_1.basename)(archivePath)), workId, variant: 'zip', path: archivePath });
+        }
+        for (const mediaAsset of resolved.mediaAssets) {
+            const a = downloadByAssetKey.get(`${mediaAsset.sourceRef?.pixivKind}:${mediaAsset.sourceRef?.sourceId}`);
+            if (!a?.localPath)
+                continue;
+            const imageArtifactId = (0, Artifact_1.artifactId)(workId, 'original', (0, node_path_1.basename)(a.localPath));
+            mediaAssets.push(buildMediaAssetById(mediaAsset, imageArtifactId));
+            artifacts.push({
+                id: imageArtifactId,
+                sourceAssetId: mediaAsset.id,
+                workId,
+                variant: 'original',
+                path: a.localPath,
+            });
+        }
+        // On-demand mode carries resolved references without local originals.
+        const returnedMediaAssets = mediaAssets.length ? mediaAssets : resolved.mediaAssets;
         return {
-            pixivId: String(detail.id),
+            pixivId: workId,
             type: 'novel',
             title: detail.title,
             tags: tags.map((item) => item.name).filter(Boolean),
             files: archivePath ? [filePath, archivePath] : [filePath],
+            mediaAssets: returnedMediaAssets,
+            artifacts,
             cleanupFiles: metadataPath ? [metadataPath] : [],
             spoiler: (detail.x_restrict ?? 0) > 0,
             xRestrict: detail.x_restrict,
@@ -306,18 +386,7 @@ class NovelDownloader {
     }
 }
 exports.NovelDownloader = NovelDownloader;
-function novelAssetFileName(asset) {
-    let ext = '';
-    try {
-        const pathname = new URL(asset.url).pathname;
-        const last = pathname.split('/').pop() || '';
-        const dot = last.lastIndexOf('.');
-        if (dot >= 0)
-            ext = last.slice(dot);
-    }
-    catch {
-        // fall through: no extension
-    }
-    return `${asset.sourceId}${ext}` || asset.sourceId;
+function buildMediaAssetById(mediaAsset, artifactIdValue) {
+    return { ...mediaAsset, artifactId: artifactIdValue };
 }
 //# sourceMappingURL=NovelDownloader.js.map

package/dist/download/materialization/MediaMaterializer.d.ts

@@ -0,0 +1,24 @@
+import { IPixivClient } from '../../interfaces/IPixivClient';
+import { IFileService } from '../../interfaces/IFileService';
+import { type MediaAsset } from '../../domain/media/MediaAsset';
+import { type Artifact } from '../../domain/media/Artifact';
+export interface MaterializationOptions {
+    variant?: 'original' | 'delivery';
+    destination?: string;
+}
+/**
+ * Turns a canonical MediaAsset into a local Artifact on demand. This is the
+ * future lazy-materialization boundary; today it wraps the existing
+ * IPixivClient.downloadImage + IFileService.saveBinary path so no new HTTP
+ * download implementation exists.
+ */
+export interface MediaMaterializer {
+    materialize(asset: MediaAsset, options?: MaterializationOptions): Promise<Artifact>;
+}
+export declare class PixivMediaMaterializer implements MediaMaterializer {
+    private readonly client;
+    private readonly fileService;
+    constructor(client: IPixivClient, fileService: IFileService);
+    materialize(asset: MediaAsset, options?: MaterializationOptions): Promise<Artifact>;
+}
+//# sourceMappingURL=MediaMaterializer.d.ts.map

package/dist/download/materialization/MediaMaterializer.js

@@ -0,0 +1,44 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PixivMediaMaterializer = void 0;
+const Artifact_1 = require("../../domain/media/Artifact");
+function fileNameFor(asset) {
+    const sourceId = asset.sourceRef?.sourceId ?? '';
+    let ext = '';
+    try {
+        const last = new URL(asset.sourceUrl).pathname.split('/').pop() || '';
+        const dot = last.lastIndexOf('.');
+        if (dot >= 0)
+            ext = last.slice(dot);
+    }
+    catch {
+        // keep no extension
+    }
+    return `${sourceId}${ext}` || 'image';
+}
+class PixivMediaMaterializer {
+    client;
+    fileService;
+    constructor(client, fileService) {
+        this.client = client;
+        this.fileService = fileService;
+    }
+    async materialize(asset, options = {}) {
+        if (!options.destination) {
+            throw new Error('PixivMediaMaterializer requires options.destination');
+        }
+        const buffer = await this.client.downloadImage(asset.sourceUrl);
+        const fileName = fileNameFor(asset);
+        const path = await this.fileService.saveBinary(buffer, fileName, options.destination);
+        const variant = options.variant ?? 'original';
+        return {
+            id: (0, Artifact_1.artifactId)(asset.sourceRef?.workId ?? '', variant, fileName),
+            sourceAssetId: asset.id,
+            workId: asset.sourceRef?.workId ?? '',
+            variant,
+            path,
+        };
+    }
+}
+exports.PixivMediaMaterializer = PixivMediaMaterializer;
+//# sourceMappingURL=MediaMaterializer.js.map

package/dist/download/novelMarkers.d.ts

@@ -75,4 +75,18 @@ export declare function demo(): void;
  * original text so nothing is silently dropped (partial success).
  */
 export declare function renderNovelMarkdown(source: string, assets: NovelAsset[]): string;
+/**
+ * Stable relative filename for an inline novel media reference without a local
+ * download. Uses the sourceId plus the URL extension so the manifest can point
+ * at a proxy URL while the rendered Markdown still resolves to
+ * `images/<sourceId>.jpg`.
+ */
+export declare function novelReferenceFileName(url: string | undefined, sourceId: string): string;
+/**
+ * Markdown sidecar for on-demand (non-downloading) previews. Renders
+ * `![](images/<ref>)` for every resolvable asset so the manifest can be
+ * rehydrated by TelePress via proxy; markers without a resolvable URL stay as
+ * their original text.
+ */
+export declare function renderNovelMarkdownReference(source: string, assets: NovelAsset[]): string;
 //# sourceMappingURL=novelMarkers.d.ts.map

package/dist/download/novelMarkers.js

@@ -4,6 +4,8 @@ exports.scanNovelMarkers = scanNovelMarkers;
 exports.extractNovelAssets = extractNovelAssets;
 exports.demo = demo;
 exports.renderNovelMarkdown = renderNovelMarkdown;
+exports.novelReferenceFileName = novelReferenceFileName;
+exports.renderNovelMarkdownReference = renderNovelMarkdownReference;
 const node_path_1 = require("node:path");
 const linkRegex = /https?:\/\/\S+/;
 function parseMarker(span) {
@@ -141,4 +143,50 @@ function renderNovelMarkdown(source, assets) {
     })
         .join('');
 }
+/**
+ * Stable relative filename for an inline novel media reference without a local
+ * download. Uses the sourceId plus the URL extension so the manifest can point
+ * at a proxy URL while the rendered Markdown still resolves to
+ * `images/<sourceId>.jpg`.
+ */
+function novelReferenceFileName(url, sourceId) {
+    let ext = '';
+    if (url) {
+        try {
+            const path = new URL(url).pathname;
+            const match = /\.(jpg|jpeg|png|gif|webp)$/i.exec(path);
+            if (match)
+                ext = match[1].toLowerCase();
+        }
+        catch {
+            // non-URL fall through to default ext
+        }
+    }
+    const safeId = sourceId.replace(/[^\w.-]+/g, '_');
+    return `images/${safeId}${ext ? `.${ext}` : '.jpg'}`;
+}
+/**
+ * Markdown sidecar for on-demand (non-downloading) previews. Renders
+ * `![](images/<ref>)` for every resolvable asset so the manifest can be
+ * rehydrated by TelePress via proxy; markers without a resolvable URL stay as
+ * their original text.
+ */
+function renderNovelMarkdownReference(source, assets) {
+    return scanNovelMarkers(source)
+        .map((marker) => {
+        if (marker.type === 'text')
+            return marker.value;
+        const asset = assets.find((a) => a.marker === marker.raw);
+        if (!asset)
+            return marker.raw;
+        if (asset.status === 'downloaded' && asset.localPath) {
+            return `![](images/${(0, node_path_1.basename)(asset.localPath)})`;
+        }
+        if (asset.status === 'pending' && asset.url) {
+            return `![](${novelReferenceFileName(asset.url, asset.sourceId)})`;
+        }
+        return marker.raw;
+    })
+        .join('');
+}
 //# sourceMappingURL=novelMarkers.js.map

package/dist/package.json

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

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: '2.38.0', commit: '66e1379b588c' };
+exports.BUILD = { version: '2.40.0', commit: '8d72f5f5761a' };
 //# sourceMappingURL=version.js.map

package/dist/webui/package.json

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

package/package.json

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