@notion-headless-cms/core 0.3.6 → 0.3.8

package/dist/index.d.mts

@@ -1,6 +1,6 @@
-import { a as StorageBinary, c as ImageRef, i as CachedItemList, l as InlineNode, n as CMSSchemaProperties, o as ContentBlock, r as CachedItem, s as ContentResult, t as BaseContentItem } from "./content-WydAfQtk.mjs";
-import { a as CollectionConfig, c as InferCollectionItem, d as PropertyMap, f as WebhookConfig, i as CMSSchema, l as InvalidateScope, n as DocumentCacheAdapter, o as DataSource, r as ImageCacheAdapter, s as DataSourceFactory, t as CacheConfig, u as PropertyDef } from "./cache-D051BP4G.mjs";
-import { a as Logger, i as definePlugin, n as mergeLoggers, o as CMSHooks, r as CMSPlugin, s as MaybePromise, t as mergeHooks } from "./hooks-D8Lgf-Co.mjs";
+import { a as CachedItemMeta, c as ContentBlock, d as InlineNode, i as CachedItemList, l as ContentResult, n as CMSSchemaProperties, o as ItemContentPayload, r as CachedItemContent, s as StorageBinary, t as BaseContentItem, u as ImageRef } from "./content-DyrOwjbA.mjs";
+import { a as CollectionConfig, c as InferCollectionItem, d as PropertyDef, f as PropertyMap, i as CMSSchema, l as InvalidateKind, n as DocumentCacheAdapter, o as DataSource, p as WebhookConfig, r as ImageCacheAdapter, s as DataSourceFactory, t as CacheConfig, u as InvalidateScope } from "./cache-QrXdXYMs.mjs";
+import { a as Logger, i as definePlugin, n as mergeLoggers, o as CMSHooks, r as CMSPlugin, s as MaybePromise, t as mergeHooks } from "./hooks-CPRRo9IN.mjs";
 import { MemoryDocumentCacheOptions, MemoryImageCacheOptions, memoryDocumentCache, memoryImageCache } from "./cache/memory.mjs";
 import { noopDocumentCache, noopImageCache } from "./cache/noop.mjs";
 import { BuiltInCMSErrorCode, CMSError, CMSErrorCode, CMSErrorContext, isCMSError, isCMSErrorInNamespace } from "./errors.mjs";
@@ -32,19 +32,79 @@ interface GetListOptions<T extends BaseContentItem = BaseContentItem> {
 interface AdjacencyOptions<T extends BaseContentItem = BaseContentItem> {
   sort?: SortOption<T>;
 }
-/** `getItem` の返り値 (本文常時同梱)。 */
+/**
+ * `getItem` の返り値（メタデータ + lazy 本文アクセサ）。
+ * `content.html()` / `content.markdown()` / `content.blocks` を呼んだ時点で
+ * 初めてキャッシュ層から本文をロードする（または再生成する）。
+ */
 type ItemWithContent<T extends BaseContentItem> = T & {
   content: ContentResult;
 };
+/**
+ * `getList` の戻り値。アイテム配列とバージョン文字列を含む。
+ * version は DataSource.getListVersion() が生成するフィルタ済みアイテムの識別子。
+ */
+interface GetListResult<T extends BaseContentItem = BaseContentItem> {
+  items: T[];
+  /** フィルタ適用後のアイテム群を識別するバージョン文字列。 */
+  version: string;
+}
+/**
+ * `checkForUpdate` の戻り値。
+ *
+ * **本文（HTML 等）は含めない**。差分判定はメタデータのみで完結し、
+ * 本文は `invalidate({ kind: "content" })` で失効 + バックグラウンド再生成される。
+ * クライアント側 (useSWR) は `mutate(metaKey, result.meta)` と `mutate(contentKey)` を
+ * 順に呼ぶことで透過的に最新化できる。
+ */
+type CheckForUpdateResult<T extends BaseContentItem = BaseContentItem> = {
+  changed: false;
+} | {
+  changed: true;
+  meta: T;
+};
+/**
+ * `checkListForUpdate` の戻り値。
+ * changed: true の場合は最新のアイテム配列とバージョンを含む。
+ */
+type CheckListForUpdateResult<T extends BaseContentItem = BaseContentItem> = {
+  changed: false;
+} | {
+  changed: true;
+  items: T[];
+  version: string;
+};
 /**
  * コレクション別の CMS クライアント。
  * `cms.posts.getItem(slug)` のようにアクセスする。
  */
 interface CollectionClient<T extends BaseContentItem = BaseContentItem> {
-  /** スラッグで単件取得 (本文込み)。キャッシュを経由 (SWR)。 */
+  /**
+   * スラッグで単件取得 (本文 lazy アクセサ付き)。
+   *
+   * メタデータはキャッシュ or Notion から即時取得し、
+   * 本文（html/markdown/blocks）は `result.content.*()` を呼んだ時点で初めてロードする。
+   *
+   * SWR: TTL 未設定 or 期限内ならキャッシュ即時返却 + バックグラウンド差分チェック。
+   *      TTL 期限切れならブロッキングフェッチ。
+   *
+   * @returns キャッシュまたは Notion から取得したアイテム。存在しない場合は null。
+   */
   getItem(slug: string): Promise<ItemWithContent<T> | null>;
-  /** 公開済みアイテム一覧 (本文なし、一覧ページ向け)。 */
-  getList(opts?: GetListOptions<T>): Promise<T[]>;
+  /**
+   * メタデータのみを取得する軽量 API。
+   * `useSWR("/api/.../meta", () => cms.posts.getItemMeta(slug))` のような形で
+   * クライアントから fetcher として直接呼べる。本文は含まれない。
+   */
+  getItemMeta(slug: string): Promise<T | null>;
+  /**
+   * 本文ペイロード（html/markdown/blocks）を取得する。
+   * `useSWR("/api/.../content", () => cms.posts.getItemContent(slug))` で利用。
+   * 関数を含まない pure JSON を返す。
+   */
+  getItemContent(slug: string): Promise<ItemContentPayload | null>;
+  /** 公開済みアイテム一覧 (本文なし、一覧ページ向け)。items とバージョン文字列を返す。 */
+  getList(opts?: GetListOptions<T>): Promise<GetListResult<T>>;
   /** Next App Router の `generateStaticParams` 向け。 */
   getStaticParams(): Promise<{
     slug: string;
@@ -56,11 +116,36 @@ interface CollectionClient<T extends BaseContentItem = BaseContentItem> {
     prev: T | null;
     next: T | null;
   }>;
-  /** 指定スコープのキャッシュを無効化する。 */
-  revalidate(scope?: "all" | {
+  /**
+   * 指定スラッグのアイテムキャッシュを無効化する（メタ + 本文両方）。
+   * 次回の getItem 呼び出しで Notion から再取得される。
+   */
+  revalidate(slug: string): Promise<void>;
+  /** コレクション全体のキャッシュを無効化する。 */
+  revalidateAll(): Promise<void>;
+  /**
+   * 指定アイテムが since 以降に更新されたか確認する。
+   *
+   * メタデータのみを比較する軽量 API（本文 cache は破棄しない）。
+   * 差分があれば本文 cache を `kind: "content"` で失効させ、
+   * バックグラウンドで再生成を発火する（`waitUntil` あり時）。
+   *
+   * クライアント側 (useSWR) は戻り値の meta で `mutate(metaKey, meta)` し、
+   * `mutate(contentKey)` を呼べば透過的に最新化される。
+   */
+  checkForUpdate(args: {
     slug: string;
-  }): Promise<void>;
-  /** 全コンテンツをプリフェッチしてキャッシュに保存。 */
+    since: string;
+  }): Promise<CheckForUpdateResult<T>>;
+  /**
+   * リスト全体が since 以降に更新されたか確認する。
+   * 差分があった場合のみリストキャッシュを書き換える（本文 cache は触らない）。
+   */
+  checkListForUpdate(args: {
+    since: string;
+    filter?: GetListOptions<T>;
+  }): Promise<CheckListForUpdateResult<T>>;
+  /** 全コンテンツをプリフェッチしてキャッシュ（メタ + 本文）に保存。 */
   prefetch(opts?: {
     concurrency?: number;
     onProgress?: (done: number, total: number) => void;
@@ -308,7 +393,7 @@ interface CMSGlobalOps<D extends DataSourceMap> {
 declare function createCMS<D extends DataSourceMap>(opts: CreateCMSOptions<D>): CMSClient<D>;
 //#endregion
 //#region src/rendering.d.ts
-/** `buildCachedItem` に必要な CMS の依存を束ねたコンテキスト。 */
+/** 本文レンダリングに必要な依存を束ねたコンテキスト。 */
 interface RenderContext<T extends BaseContentItem> {
   source: DataSource<T>;
   rendererFn: RendererFn | undefined;
@@ -373,7 +458,9 @@ declare class CollectionClientImpl<T extends BaseContentItem> implements Collect
   private readonly ctx;
   constructor(ctx: CollectionContext<T>);
   getItem(slug: string): Promise<ItemWithContent<T> | null>;
-  getList(opts?: GetListOptions<T>): Promise<T[]>;
+  getItemMeta(slug: string): Promise<T | null>;
+  getItemContent(slug: string): Promise<ItemContentPayload | null>;
+  getList(opts?: GetListOptions<T>): Promise<GetListResult<T>>;
   getStaticParams(): Promise<{
     slug: string;
   }[]>;
@@ -382,9 +469,22 @@ declare class CollectionClientImpl<T extends BaseContentItem> implements Collect
     prev: T | null;
     next: T | null;
   }>;
-  revalidate(scope?: "all" | {
+  revalidate(slug: string): Promise<void>;
+  revalidateAll(): Promise<void>;
+  checkForUpdate({
+    slug,
+    since
+  }: {
     slug: string;
-  }): Promise<void>;
+    since: string;
+  }): Promise<CheckForUpdateResult<T>>;
+  checkListForUpdate({
+    since,
+    filter
+  }: {
+    since: string;
+    filter?: GetListOptions<T>;
+  }): Promise<CheckListForUpdateResult<T>>;
   prefetch(opts?: {
     concurrency?: number;
     onProgress?: (done: number, total: number) => void;
@@ -392,7 +492,19 @@ declare class CollectionClientImpl<T extends BaseContentItem> implements Collect
     ok: number;
     failed: number;
   }>;
-  private attachContent;
+  private persistMeta;
+  private invalidateContent;
+  /**
+   * 本文キャッシュをロードする。キャッシュが無いか、メタとの整合性が取れない場合は
+   * 再生成して書き戻す。
+   */
+  private loadOrBuildContent;
+  /**
+   * メタは既知（差分検出済み or 直前にフェッチ済み）の状態で本文だけ
+   * バックグラウンド再生成する。エラーは握りつぶしてログのみ。
+   */
+  private rebuildContentBg;
+  private attachLazyContent;
   private fetchList;
   private checkAndUpdateItemBg;
   private checkAndUpdateListBg;
@@ -430,5 +542,5 @@ interface NodePresetOptions {
  */
 declare function nodePreset(opts?: NodePresetOptions): Pick<CreateCMSOptions, "cache" | "renderer">;
 //#endregion
-export { type AdjacencyOptions, type BaseContentItem, type BuiltInCMSErrorCode, type CMSClient, CMSError, type CMSErrorCode, type CMSErrorContext, type CMSGlobalOps, type CMSHooks, type CMSPlugin, type CMSSchema, type CMSSchemaProperties, type CacheConfig, type CachedItem, type CachedItemList, type CollectionClient, CollectionClientImpl, type CollectionConfig, type CollectionContext, type CollectionSemantics, type ContentBlock, type ContentConfig, type ContentResult, type CreateCMSOptions, DEFAULT_RETRY_CONFIG, type DataSource, type DataSourceFactory, type DataSourceMap, type DocumentCacheAdapter, type GetListOptions, type HandlerAdapter, type HandlerOptions, type ImageCacheAdapter, type ImageRef, type InferCollectionItem, type InferDataSourceItem, type InlineNode, type InvalidateScope, type ItemWithContent, type Logger, type MaybePromise, type MemoryDocumentCacheOptions, type MemoryImageCacheOptions, type NodePresetOptions, type PropertyDef, type PropertyMap, type RateLimiterConfig, type RenderOptions, type RendererFn, type RendererPluginList, type RetryConfig, type SortOption, type StorageBinary, type WebhookConfig, collectionKey, createCMS, createHandler, definePlugin, isCMSError, isCMSErrorInNamespace, isStale, memoryDocumentCache, memoryImageCache, mergeHooks, mergeLoggers, nodePreset, noopDocumentCache, noopImageCache, sha256Hex, withRetry };
+export { type AdjacencyOptions, type BaseContentItem, type BuiltInCMSErrorCode, type CMSClient, CMSError, type CMSErrorCode, type CMSErrorContext, type CMSGlobalOps, type CMSHooks, type CMSPlugin, type CMSSchema, type CMSSchemaProperties, type CacheConfig, type CachedItemContent, type CachedItemList, type CachedItemMeta, type CheckForUpdateResult, type CheckListForUpdateResult, type CollectionClient, CollectionClientImpl, type CollectionConfig, type CollectionContext, type CollectionSemantics, type ContentBlock, type ContentConfig, type ContentResult, type CreateCMSOptions, DEFAULT_RETRY_CONFIG, type DataSource, type DataSourceFactory, type DataSourceMap, type DocumentCacheAdapter, type GetListOptions, type GetListResult, type HandlerAdapter, type HandlerOptions, type ImageCacheAdapter, type ImageRef, type InferCollectionItem, type InferDataSourceItem, type InlineNode, type InvalidateKind, type InvalidateScope, type ItemContentPayload, type ItemWithContent, type Logger, type MaybePromise, type MemoryDocumentCacheOptions, type MemoryImageCacheOptions, type NodePresetOptions, type PropertyDef, type PropertyMap, type RateLimiterConfig, type RenderOptions, type RendererFn, type RendererPluginList, type RetryConfig, type SortOption, type StorageBinary, type WebhookConfig, collectionKey, createCMS, createHandler, definePlugin, isCMSError, isCMSErrorInNamespace, isStale, memoryDocumentCache, memoryImageCache, mergeHooks, mergeLoggers, nodePreset, noopDocumentCache, noopImageCache, sha256Hex, withRetry };
 //# sourceMappingURL=index.d.mts.map

package/dist/index.mjs

@@ -94,10 +94,20 @@ function buildCacheImageFn(cache, imageProxyBase, logger) {
 //#endregion
 //#region src/rendering.ts
 /**
-* コンテンツアイテムをソースから Markdown ロード → blocks 生成 → HTML レンダリング
-* → フック適用まで実行し、キャッシュ保存用の `CachedItem` を返す。
+* メタデータキャッシュエントリを生成する。Notion API も renderer も呼ばない軽量関数。
 */
-async function buildCachedItem(item, ctx) {
+function buildCachedItemMeta(item, source) {
+	return {
+		item,
+		notionUpdatedAt: source.getLastModified(item),
+		cachedAt: Date.now()
+	};
+}
+/**
+* アイテム本文を Markdown ロード → blocks 生成 → HTML レンダリング → フック適用まで
+* 実行し、本文キャッシュ用の `CachedItemContent` を返す。
+*/
+async function buildCachedItemContent(item, ctx) {
 	const start = Date.now();
 	ctx.logger?.info?.("コンテンツのレンダリング開始", {
 		slug: item.slug,
@@ -114,7 +124,7 @@ async function buildCachedItem(item, ctx) {
 			message: "Failed to load markdown from source.",
 			cause: err,
 			context: {
-				operation: "buildCachedItem:loadMarkdown",
+				operation: "buildCachedItemContent:loadMarkdown",
 				pageId: item.id,
 				slug: item.slug
 			}
@@ -147,7 +157,7 @@ async function buildCachedItem(item, ctx) {
 			message: "Failed to render markdown.",
 			cause: err,
 			context: {
-				operation: "buildCachedItem:renderMarkdown",
+				operation: "buildCachedItemContent:renderMarkdown",
 				pageId: item.id,
 				slug: item.slug
 			}
@@ -158,11 +168,10 @@ async function buildCachedItem(item, ctx) {
 		html,
 		blocks,
 		markdown,
-		item,
 		notionUpdatedAt: ctx.source.getLastModified(item),
 		cachedAt: Date.now()
 	};
-	if (ctx.hooks.beforeCache) result = await ctx.hooks.beforeCache(result);
+	if (ctx.hooks.beforeCacheContent) result = await ctx.hooks.beforeCacheContent(result, item);
 	const durationMs = Date.now() - start;
 	ctx.logger?.info?.("コンテンツのレンダリング完了", {
 		slug: item.slug,
@@ -240,9 +249,9 @@ var CollectionClientImpl = class {
 		this.ctx = ctx;
 	}
 	async getItem(slug) {
-		const cached = await this.ctx.docCache.getItem(slug);
-		if (cached) {
-			if (this.ctx.ttlMs !== void 0 && isStale(cached.cachedAt, this.ctx.ttlMs)) {
+		const cachedMeta = await this.ctx.docCache.getItemMeta(slug);
+		if (cachedMeta) {
+			if (this.ctx.ttlMs !== void 0 && isStale(cachedMeta.cachedAt, this.ctx.ttlMs)) {
 				this.ctx.logger?.debug?.("キャッシュ期限切れ（TTL）、フェッチ", {
 					operation: "getItem",
 					slug,
@@ -252,21 +261,21 @@ var CollectionClientImpl = class {
 				this.ctx.hooks.onCacheMiss?.(slug);
 				const item = await this.findRaw(slug);
 				if (!item) return null;
-				const entry = await buildCachedItem(item, this.ctx.render);
-				await this.ctx.docCache.setItem(slug, entry);
-				return this.attachContent(entry.item, entry);
+				const meta = await this.persistMeta(slug, item);
+				await this.invalidateContent(slug);
+				return this.attachLazyContent(meta);
 			}
-			const bg = this.checkAndUpdateItemBg(slug, cached);
+			const bg = this.checkAndUpdateItemBg(slug, cachedMeta);
 			if (this.ctx.waitUntil) this.ctx.waitUntil(bg);
 			this.ctx.logger?.debug?.("キャッシュヒット", {
 				operation: "getItem",
 				slug,
 				collection: this.ctx.collection,
 				cacheAdapter: this.ctx.docCache.name,
-				cachedAt: cached.cachedAt
+				cachedAt: cachedMeta.cachedAt
 			});
-			this.ctx.hooks.onCacheHit?.(slug, cached);
-			return this.attachContent(cached.item, cached);
+			this.ctx.hooks.onCacheHit?.(slug, cachedMeta);
+			return this.attachLazyContent(cachedMeta);
 		}
 		this.ctx.logger?.debug?.("キャッシュミス、フェッチ", {
 			operation: "getItem",
@@ -284,14 +293,42 @@ var CollectionClientImpl = class {
 			});
 			return null;
 		}
-		const entry = await buildCachedItem(item, this.ctx.render);
-		const save = this.ctx.docCache.setItem(slug, entry);
-		if (this.ctx.waitUntil) this.ctx.waitUntil(save);
-		else await save;
-		return this.attachContent(entry.item, entry);
+		const meta = await this.persistMeta(slug, item, { background: true });
+		return this.attachLazyContent(meta);
+	}
+	async getItemMeta(slug) {
+		const cachedMeta = await this.ctx.docCache.getItemMeta(slug);
+		if (cachedMeta) {
+			if (this.ctx.ttlMs !== void 0 && isStale(cachedMeta.cachedAt, this.ctx.ttlMs)) {
+				const item = await this.findRaw(slug);
+				if (!item) return null;
+				const meta = await this.persistMeta(slug, item);
+				await this.invalidateContent(slug);
+				return meta.item;
+			}
+			const bg = this.checkAndUpdateItemBg(slug, cachedMeta);
+			if (this.ctx.waitUntil) this.ctx.waitUntil(bg);
+			this.ctx.hooks.onCacheHit?.(slug, cachedMeta);
+			return cachedMeta.item;
+		}
+		this.ctx.hooks.onCacheMiss?.(slug);
+		const item = await this.findRaw(slug);
+		if (!item) return null;
+		return (await this.persistMeta(slug, item, { background: true })).item;
+	}
+	async getItemContent(slug) {
+		const meta = await this.ctx.docCache.getItemMeta(slug);
+		const item = meta?.item ?? await this.findRaw(slug);
+		if (!item) return null;
+		if (!meta) await this.persistMeta(slug, item);
+		return toContentPayload(await this.loadOrBuildContent(slug, item));
 	}
 	async getList(opts) {
-		return applyGetListOptions(await this.fetchList(), opts);
+		const items = applyGetListOptions(await this.fetchList(), opts);
+		return {
+			items,
+			version: this.ctx.source.getListVersion(items)
+		};
 	}
 	async getStaticParams() {
 		return (await this.fetchList()).map((item) => ({ slug: item.slug }));
@@ -311,20 +348,73 @@ var CollectionClientImpl = class {
 			next: index < items.length - 1 ? items[index + 1] ?? null : null
 		};
 	}
-	async revalidate(scope) {
-		this.ctx.logger?.debug?.("キャッシュを無効化", {
+	async revalidate(slug) {
+		this.ctx.logger?.debug?.("アイテムキャッシュを無効化", {
 			operation: "revalidate",
 			collection: this.ctx.collection,
 			cacheAdapter: this.ctx.docCache.name,
-			slug: typeof scope === "object" ? scope.slug : void 0
+			slug
 		});
 		if (!this.ctx.docCache.invalidate) return;
-		if (scope === void 0 || scope === "all") await this.ctx.docCache.invalidate({ collection: this.ctx.collection });
-		else await this.ctx.docCache.invalidate({
+		await this.ctx.docCache.invalidate({
 			collection: this.ctx.collection,
-			slug: scope.slug
+			slug
 		});
 	}
+	async revalidateAll() {
+		this.ctx.logger?.debug?.("コレクション全体のキャッシュを無効化", {
+			operation: "revalidateAll",
+			collection: this.ctx.collection,
+			cacheAdapter: this.ctx.docCache.name
+		});
+		if (!this.ctx.docCache.invalidate) return;
+		await this.ctx.docCache.invalidate({ collection: this.ctx.collection });
+	}
+	async checkForUpdate({ slug, since }) {
+		const fresh = await this.findRaw(slug);
+		if (!fresh) return { changed: false };
+		const lm = this.ctx.source.getLastModified(fresh);
+		if (lm === since) {
+			this.ctx.logger?.debug?.("checkForUpdate: 差分なし", {
+				operation: "checkForUpdate",
+				slug,
+				collection: this.ctx.collection,
+				since
+			});
+			return { changed: false };
+		}
+		const meta = await this.persistMeta(slug, fresh);
+		await this.invalidateContent(slug);
+		this.ctx.hooks.onCacheRevalidated?.(slug, meta);
+		this.ctx.logger?.debug?.("checkForUpdate: 差分を検出", {
+			operation: "checkForUpdate",
+			slug,
+			collection: this.ctx.collection,
+			since,
+			notionUpdatedAt: lm
+		});
+		const bg = this.rebuildContentBg(slug, fresh);
+		if (this.ctx.waitUntil) this.ctx.waitUntil(bg);
+		return {
+			changed: true,
+			meta: fresh
+		};
+	}
+	async checkListForUpdate({ since, filter }) {
+		const allItems = await this.fetchListRaw();
+		const items = applyGetListOptions(allItems, filter);
+		const version = this.ctx.source.getListVersion(items);
+		if (version === since) return { changed: false };
+		await this.ctx.docCache.setList({
+			items: allItems,
+			cachedAt: Date.now()
+		});
+		return {
+			changed: true,
+			items,
+			version
+		};
+	}
 	async prefetch(opts) {
 		const items = await this.fetchListRaw();
 		const concurrency = opts?.concurrency ?? this.ctx.maxConcurrent;
@@ -334,8 +424,9 @@ var CollectionClientImpl = class {
 			const chunk = items.slice(i, i + concurrency);
 			await Promise.all(chunk.map(async (item) => {
 				try {
-					const rendered = await buildCachedItem(item, this.ctx.render);
-					await this.ctx.docCache.setItem(item.slug, rendered);
+					await this.persistMeta(item.slug, item);
+					const content = await buildCachedItemContent(item, this.ctx.render);
+					await this.ctx.docCache.setItemContent(item.slug, content);
 					ok++;
 				} catch (err) {
 					failed++;
@@ -357,32 +448,71 @@ var CollectionClientImpl = class {
 			failed
 		};
 	}
-	attachContent(item, cached) {
-		const ctx = this.ctx;
-		let blocksCache;
-		let htmlCache = cached.html;
-		let markdownCache;
-		const content = {
-			get blocks() {
-				if (!blocksCache) blocksCache = [{
-					type: "raw",
-					html: cached.html
-				}];
-				return blocksCache;
+	async persistMeta(slug, item, opts = {}) {
+		let meta = buildCachedItemMeta(item, this.ctx.source);
+		if (this.ctx.hooks.beforeCacheMeta) meta = await this.ctx.hooks.beforeCacheMeta(meta);
+		const save = this.ctx.docCache.setItemMeta(slug, meta);
+		if (opts.background && this.ctx.waitUntil) this.ctx.waitUntil(save);
+		else await save;
+		return meta;
+	}
+	async invalidateContent(slug) {
+		if (!this.ctx.docCache.invalidate) return;
+		await this.ctx.docCache.invalidate({
+			collection: this.ctx.collection,
+			slug,
+			kind: "content"
+		});
+	}
+	/**
+	* 本文キャッシュをロードする。キャッシュが無いか、メタとの整合性が取れない場合は
+	* 再生成して書き戻す。
+	*/
+	async loadOrBuildContent(slug, item) {
+		const expected = this.ctx.source.getLastModified(item);
+		const cached = await this.ctx.docCache.getItemContent(slug);
+		if (cached && cached.notionUpdatedAt === expected) return cached;
+		const fresh = await buildCachedItemContent(item, this.ctx.render);
+		await this.ctx.docCache.setItemContent(slug, fresh);
+		this.ctx.hooks.onContentRevalidated?.(slug, fresh);
+		return fresh;
+	}
+	/**
+	* メタは既知（差分検出済み or 直前にフェッチ済み）の状態で本文だけ
+	* バックグラウンド再生成する。エラーは握りつぶしてログのみ。
+	*/
+	async rebuildContentBg(slug, item) {
+		try {
+			const fresh = await buildCachedItemContent(item, this.ctx.render);
+			await this.ctx.docCache.setItemContent(slug, fresh);
+			this.ctx.hooks.onContentRevalidated?.(slug, fresh);
+		} catch (err) {
+			this.ctx.logger?.warn?.("本文のバックグラウンド再生成に失敗", {
+				slug,
+				collection: this.ctx.collection,
+				error: err instanceof Error ? err.message : String(err)
+			});
+		}
+	}
+	attachLazyContent(meta) {
+		const slug = meta.item.slug;
+		const item = meta.item;
+		let payloadPromise;
+		const loadPayload = () => {
+			if (!payloadPromise) payloadPromise = this.loadOrBuildContent(slug, item);
+			return payloadPromise;
+		};
+		return Object.assign(Object.create(null), item, { content: {
+			async blocks() {
+				return (await loadPayload()).blocks;
 			},
 			async html() {
-				if (htmlCache !== void 0) return htmlCache;
-				htmlCache = cached.html;
-				return htmlCache;
+				return (await loadPayload()).html;
 			},
 			async markdown() {
-				if (markdownCache !== void 0) return markdownCache;
-				markdownCache = await ctx.source.loadMarkdown(item);
-				return markdownCache;
+				return (await loadPayload()).markdown;
 			}
-		};
-		if (cached.blocks) blocksCache = cached.blocks;
-		return Object.assign(Object.create(null), item, { content });
+		} });
 	}
 	async fetchList() {
 		const cached = await this.ctx.docCache.getList();
@@ -432,17 +562,18 @@ var CollectionClientImpl = class {
 			const item = await this.findRaw(slug);
 			if (!item) return;
 			if (this.ctx.source.getLastModified(item) !== cached.notionUpdatedAt) {
-				const entry = await buildCachedItem(item, this.ctx.render);
-				await this.ctx.docCache.setItem(slug, entry);
-				this.ctx.logger?.debug?.("SWR: 差分を検出、キャッシュを差し替え", {
+				const meta = await this.persistMeta(slug, item);
+				await this.invalidateContent(slug);
+				this.ctx.logger?.debug?.("SWR: 差分を検出、メタを差し替え", {
 					operation: "getItem:bg",
 					slug,
 					collection: this.ctx.collection,
 					notionUpdatedAt: cached.notionUpdatedAt
 				});
-				this.ctx.hooks.onCacheRevalidated?.(slug, entry);
+				this.ctx.hooks.onCacheRevalidated?.(slug, meta);
+				await this.rebuildContentBg(slug, item);
 			} else if (this.ctx.ttlMs !== void 0) {
-				await this.ctx.docCache.setItem(slug, {
+				await this.ctx.docCache.setItemMeta(slug, {
 					...cached,
 					cachedAt: Date.now()
 				});
@@ -524,6 +655,14 @@ var CollectionClientImpl = class {
 		return item;
 	}
 };
+function toContentPayload(c) {
+	return {
+		html: c.html,
+		markdown: c.markdown,
+		blocks: c.blocks,
+		notionUpdatedAt: c.notionUpdatedAt
+	};
+}
 function applyGetListOptions(items, opts) {
 	if (!opts) return items;
 	let result = items;
@@ -673,6 +812,15 @@ function scopeDocumentCache(base, collection) {
 	const itemKey = (slug) => `${collection}:${slug}`;
 	let listSlot = null;
 	let listInitialized = false;
+	const mapInvalidateScope = (scope) => {
+		if (scope === "all") return { collection };
+		if ("slug" in scope) return {
+			collection: scope.collection,
+			slug: itemKey(scope.slug),
+			kind: scope.kind
+		};
+		return scope;
+	};
 	return {
 		name: `${base.name}@${collection}`,
 		getList: async () => {
@@ -687,18 +835,18 @@ function scopeDocumentCache(base, collection) {
 			listInitialized = true;
 			return Promise.resolve();
 		},
-		getItem: (slug) => base.getItem(itemKey(slug)),
-		setItem: (slug, data) => base.setItem(itemKey(slug), data),
+		getItemMeta: (slug) => base.getItemMeta(itemKey(slug)),
+		setItemMeta: (slug, data) => base.setItemMeta(itemKey(slug), data),
+		getItemContent: (slug) => base.getItemContent(itemKey(slug)),
+		setItemContent: (slug, data) => base.setItemContent(itemKey(slug), data),
 		async invalidate(scope) {
-			listSlot = null;
-			listInitialized = true;
+			const kind = scope === "all" ? "all" : scope.kind ?? "all";
+			if (kind === "all" || kind === "meta") {
+				listSlot = null;
+				listInitialized = true;
+			}
 			if (!base.invalidate) return;
-			if (scope === "all") return base.invalidate({ collection });
-			if ("slug" in scope) return base.invalidate({
-				collection: scope.collection,
-				slug: itemKey(scope.slug)
-			});
-			return base.invalidate(scope);
+			return base.invalidate(mapInvalidateScope(scope));
 		}
 	};
 }