@fecommunity/reactpress-theme-starter 1.0.0-beta.0

package/lib/mock-api/match-route.ts

@@ -0,0 +1,202 @@
+import { mockAuthGithub, mockAuthLogin, mockAuthRegister } from './auth'
+import {
+  filterMockArticlesByCategory,
+  filterMockArticlesByTag,
+  getMockArticleById,
+  getMockCategoryByValue,
+  getMockKnowledgeById,
+  getMockPageById,
+  getMockTagByValue,
+  mockArchives,
+  mockArticles,
+  mockCategories,
+  mockKnowledgeBooks,
+  mockPages,
+  mockRecommendedArticles,
+  mockSetting,
+  mockTags,
+  searchMockArticles,
+} from './data'
+
+function incrementViews<T extends { views?: number }>(item: T): T {
+  return { ...item, views: (item.views ?? 0) + 1 }
+}
+
+function findMockKnowledgeById(id: string) {
+  return getMockKnowledgeById(id)
+}
+
+type MatchOptions = {
+  keyword?: string
+  body?: unknown
+}
+
+function jsonEnvelope(data: unknown, status = 200): Response {
+  return Response.json(
+    { success: true, data },
+    {
+      status,
+      headers: { 'Content-Type': 'application/json; charset=utf-8' },
+    }
+  )
+}
+
+function normalizePath(segments: string[]): string {
+  const path = `/${segments.map((segment) => decodeURIComponent(segment)).join('/')}`
+  return (path.replace(/\/$/, '') || '/').toLowerCase()
+}
+
+function paginated<T>(items: T[]) {
+  return [items, items.length] as const
+}
+
+export function matchMockRoute(
+  method: string,
+  segments: string[],
+  options: MatchOptions = {}
+): Response | null {
+  const path = normalizePath(segments)
+
+  if (method === 'POST' && path === '/auth/login') {
+    return mockAuthLogin(options.body)
+  }
+  if (method === 'POST' && path === '/auth/github') {
+    return mockAuthGithub(options.body)
+  }
+  if (method === 'POST' && path === '/user/register') {
+    return mockAuthRegister(options.body)
+  }
+
+  if (method === 'POST' && path === '/setting/get') {
+    return jsonEnvelope(mockSetting)
+  }
+
+  if (method === 'POST' && path === '/view') {
+    return jsonEnvelope(null)
+  }
+
+  if (method === 'GET' && path.startsWith('/comment/host/')) {
+    return jsonEnvelope(paginated([]))
+  }
+  if (method === 'POST' && path === '/comment') {
+    return jsonEnvelope({
+      id: 'mock-comment',
+      hostId: '',
+      content: '',
+      status: 'approved',
+      createAt: new Date().toISOString(),
+      updateAt: new Date().toISOString(),
+    })
+  }
+
+  if (method === 'POST' && path.startsWith('/article/')) {
+    const rest = decodeURIComponent(path.slice('/article/'.length))
+    const slash = rest.indexOf('/')
+    if (slash === -1) {
+      return null
+    }
+    const id = rest.slice(0, slash)
+    const action = rest.slice(slash + 1)
+    const article = getMockArticleById(id)
+
+    if (action === 'views') {
+      return jsonEnvelope(incrementViews(article))
+    }
+    if (action === 'likes') {
+      return jsonEnvelope({ ...article, likes: (article.likes ?? 0) + 1 })
+    }
+    if (action === 'checkPassword') {
+      return jsonEnvelope({ pass: true, ...article, needPassword: false })
+    }
+  }
+
+  if (method === 'POST' && path.startsWith('/knowledge/')) {
+    const rest = decodeURIComponent(path.slice('/knowledge/'.length))
+    const slash = rest.indexOf('/')
+    if (slash === -1) {
+      return null
+    }
+    const id = rest.slice(0, slash)
+    const action = rest.slice(slash + 1)
+    const book = findMockKnowledgeById(id)
+    if (!book) {
+      return jsonEnvelope(null)
+    }
+    if (action === 'views') {
+      return jsonEnvelope(incrementViews(book))
+    }
+    if (action === 'likes') {
+      return jsonEnvelope({ ...book, likes: (book.likes ?? 0) + 1 })
+    }
+  }
+
+  if (method === 'GET' && path === '/article') {
+    return jsonEnvelope(paginated(mockArticles))
+  }
+  if (method === 'GET' && (path === '/article/recommend' || path === '/article/all/recommend')) {
+    return jsonEnvelope(mockRecommendedArticles)
+  }
+  if (method === 'GET' && path === '/article/archives') {
+    return jsonEnvelope(mockArchives)
+  }
+  if (method === 'GET' && path.startsWith('/article/category/')) {
+    const value = decodeURIComponent(path.slice('/article/category/'.length))
+    return jsonEnvelope(paginated(filterMockArticlesByCategory(value)))
+  }
+  if (method === 'GET' && path.startsWith('/article/tag/')) {
+    const value = decodeURIComponent(path.slice('/article/tag/'.length))
+    return jsonEnvelope(paginated(filterMockArticlesByTag(value)))
+  }
+  if (method === 'GET' && path.startsWith('/article/')) {
+    const id = decodeURIComponent(path.slice('/article/'.length))
+    if (!id.includes('/')) {
+      return jsonEnvelope(getMockArticleById(id))
+    }
+  }
+
+  if (method === 'GET' && path === '/category') {
+    return jsonEnvelope(mockCategories)
+  }
+  if (method === 'GET' && path.startsWith('/category/')) {
+    const value = decodeURIComponent(path.slice('/category/'.length))
+    return jsonEnvelope(getMockCategoryByValue(value))
+  }
+
+  if (method === 'GET' && path === '/tag') {
+    return jsonEnvelope(mockTags)
+  }
+  if (method === 'GET' && path.startsWith('/tag/')) {
+    const value = decodeURIComponent(path.slice('/tag/'.length))
+    return jsonEnvelope(getMockTagByValue(value))
+  }
+
+  if (method === 'GET' && path === '/page') {
+    return jsonEnvelope(paginated(mockPages))
+  }
+  if (method === 'GET' && path.startsWith('/page/')) {
+    const id = decodeURIComponent(path.slice('/page/'.length))
+    if (id.endsWith('/views')) {
+      return jsonEnvelope(null)
+    }
+    return jsonEnvelope(getMockPageById(id))
+  }
+  if (method === 'POST' && path.startsWith('/page/') && path.endsWith('/views')) {
+    const id = decodeURIComponent(path.slice('/page/'.length, -'/views'.length))
+    const page = getMockPageById(id)
+    return jsonEnvelope(incrementViews(page))
+  }
+
+  if (method === 'GET' && path === '/knowledge') {
+    return jsonEnvelope(paginated(mockKnowledgeBooks))
+  }
+  if (method === 'GET' && path.startsWith('/knowledge/')) {
+    const id = decodeURIComponent(path.slice('/knowledge/'.length))
+    return jsonEnvelope(getMockKnowledgeById(id))
+  }
+
+  if (method === 'GET' && path === '/search/article') {
+    return jsonEnvelope(searchMockArticles(options.keyword ?? ''))
+  }
+
+  return null
+}

package/lib/mock-api/proxy.ts

@@ -0,0 +1,28 @@
+import { resolveUpstreamApiBase } from './config'
+
+export async function proxyToUpstreamApi(request: Request, segments: string[]): Promise<Response> {
+  const base = resolveUpstreamApiBase()
+  const pathname = segments.map((segment) => decodeURIComponent(segment)).join('/')
+  const incoming = new URL(request.url)
+  const target = new URL(pathname ? `${base}/${pathname}` : base)
+  target.search = incoming.search
+
+  const headers = new Headers(request.headers)
+  headers.delete('host')
+  headers.delete('connection')
+
+  const body =
+    request.method === 'GET' || request.method === 'HEAD' ? undefined : await request.arrayBuffer()
+
+  const upstream = await fetch(target, {
+    method: request.method,
+    headers,
+    body,
+    redirect: 'manual',
+  })
+
+  return new Response(upstream.body, {
+    status: upstream.status,
+    headers: upstream.headers,
+  })
+}

package/lib/providers/client.ts

@@ -0,0 +1,58 @@
+import { createThemeHttpStack } from '@fecommunity/reactpress-toolkit/theme'
+import { normalizeList, normalizePaginated } from '@/lib/reactpress/normalizeApiResponse'
+import { materializeProvider } from '@/lib/providers/materializeProvider'
+
+/** API messages already shown in UI (login form, etc.) — skip dev console noise. */
+function isExpectedClientError(message: string, status?: number): boolean {
+  if (status === 400 || status === 401 || status === 403) return true
+  return /用户名|密码|登录|注册|邮箱|授权|已存在|锁定|未认证|无权|Unauthorized|Request failed/i.test(
+    message
+  )
+}
+
+const stack = createThemeHttpStack({
+  onError: (msg: string, status?: number) => {
+    if (process.env.NODE_ENV !== 'development') return
+    if (isExpectedClientError(msg, status)) return
+    console.error('[reactpress-theme-starter]', msg)
+  },
+})
+
+export const { CommentProvider, UserProvider, SettingProvider } = stack
+
+export const ArticleProvider = {
+  ...materializeProvider(stack.ArticleProvider),
+  getArticles: (params: Parameters<typeof stack.ArticleProvider.getArticles>[0]) =>
+    stack.ArticleProvider.getArticles(params).then(normalizePaginated),
+  getArticlesByCategory: (
+    category: Parameters<typeof stack.ArticleProvider.getArticlesByCategory>[0],
+    params: Parameters<typeof stack.ArticleProvider.getArticlesByCategory>[1]
+  ) => stack.ArticleProvider.getArticlesByCategory(category, params).then(normalizePaginated),
+  getArticlesByTag: (
+    tag: Parameters<typeof stack.ArticleProvider.getArticlesByTag>[0],
+    params: Parameters<typeof stack.ArticleProvider.getArticlesByTag>[1]
+  ) => stack.ArticleProvider.getArticlesByTag(tag, params).then(normalizePaginated),
+  getRecommend: (
+    articleId?: Parameters<typeof stack.ArticleProvider.getRecommend>[0],
+    pageSize?: Parameters<typeof stack.ArticleProvider.getRecommend>[1]
+  ) => stack.ArticleProvider.getRecommend(articleId, pageSize).then(normalizeList),
+  getAllRecommendArticles: () =>
+    stack.ArticleProvider.getAllRecommendArticles().then(normalizeList),
+} as typeof stack.ArticleProvider
+
+export const SearchProvider = {
+  ...materializeProvider(stack.SearchProvider),
+  searchArticles: (keyword: string) =>
+    stack.SearchProvider.searchArticles(keyword).then(normalizeList),
+} as typeof stack.SearchProvider
+
+export const PageProvider = {
+  ...materializeProvider(stack.PageProvider),
+  getAllPublisedPages: () => stack.PageProvider.getAllPublisedPages().then(normalizePaginated),
+} as typeof stack.PageProvider
+
+export const KnowledgeProvider = {
+  ...materializeProvider(stack.KnowledgeProvider),
+  getKnowledges: (params: Parameters<typeof stack.KnowledgeProvider.getKnowledges>[0]) =>
+    stack.KnowledgeProvider.getKnowledges(params).then(normalizePaginated),
+} as typeof stack.KnowledgeProvider

package/lib/providers/materializeProvider.ts

@@ -0,0 +1,9 @@
+/** Class static methods are not copied by object spread — materialize as a plain object. */
+export function materializeProvider<T extends object>(Provider: T): T {
+  const source = Provider as Record<string, unknown>
+  return Object.fromEntries(
+    Object.getOwnPropertyNames(Provider)
+      .filter((name) => typeof source[name] === 'function')
+      .map((name) => [name, source[name]])
+  ) as T
+}

package/lib/providers/server.ts

@@ -0,0 +1,8 @@
+import {
+  createThemeAxiosClient,
+  createThemeProviders,
+} from '@fecommunity/reactpress-toolkit/theme/server'
+
+const http = createThemeAxiosClient({ unwrapEnvelope: true })
+
+export const { SettingProvider, CategoryProvider, ArticleProvider } = createThemeProviders(http)

package/lib/reactpress/appearance.ts

@@ -0,0 +1,69 @@
+import {
+  buildBrandingAppearanceCss,
+  type ThemeMods,
+} from '@fecommunity/reactpress-toolkit/theme/server'
+
+function modValue(mods: ThemeMods, key: string): string | undefined {
+  const raw = mods?.[key]
+  if (typeof raw !== 'string') return undefined
+  const trimmed = raw.trim()
+  return trimmed || undefined
+}
+
+function normalizeHex(value: string | undefined): string | undefined {
+  if (!value) return undefined
+  const trimmed = value.trim()
+  if (!/^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6})$/.test(trimmed)) return undefined
+  if (trimmed.length === 4) {
+    const [, r, g, b] = trimmed
+    return `#${r}${r}${g}${g}${b}${b}`.toLowerCase()
+  }
+  return trimmed.toLowerCase()
+}
+
+function darkenHex(hex: string, amount = 0.22): string {
+  const normalized = normalizeHex(hex)
+  if (!normalized) return hex
+  const value = normalized.slice(1)
+  const channels = [0, 2, 4].map((start) => parseInt(value.slice(start, start + 2), 16))
+  const factor = 1 - amount
+  return `#${channels
+    .map((channel) =>
+      Math.max(0, Math.min(255, Math.round(channel * factor)))
+        .toString(16)
+        .padStart(2, '0')
+    )
+    .join('')}`
+}
+
+/** Maps Customizer color mods to Tailwind v4 primary scale overrides. */
+export function buildThemeStarterAppearanceCss(mods: ThemeMods): string {
+  const base = buildBrandingAppearanceCss(mods)
+  const lightPrimary = normalizeHex(modValue(mods, 'primaryColor'))
+  const darkPrimary = normalizeHex(modValue(mods, 'darkPrimaryColor'))
+  const lightBg = normalizeHex(modValue(mods, 'backgroundColor'))
+  const darkBg = normalizeHex(modValue(mods, 'darkBackgroundColor'))
+
+  const blocks: string[] = [base]
+
+  if (lightPrimary) {
+    const buttonBg = darkenHex(lightPrimary)
+    blocks.push(
+      `body:not(.dark) { --primary-color: ${lightPrimary}; --primary-button-bg: ${buttonBg}; --color-primary-500: ${lightPrimary}; --color-primary-600: ${buttonBg}; }`
+    )
+  }
+  if (darkPrimary) {
+    const buttonBg = darkenHex(darkPrimary)
+    blocks.push(
+      `body.dark { --primary-color: ${darkPrimary}; --primary-button-bg: ${buttonBg}; --color-primary-500: ${darkPrimary}; --color-primary-400: ${darkPrimary}; }`
+    )
+  }
+  if (lightBg) {
+    blocks.push(`body:not(.dark) { background-color: ${lightBg}; }`)
+  }
+  if (darkBg) {
+    blocks.push(`body.dark { background-color: ${darkBg}; }`)
+  }
+
+  return blocks.filter(Boolean).join('\n')
+}

package/lib/reactpress/bootstrap.ts

@@ -0,0 +1,48 @@
+import themeManifest from '../../theme.json'
+import {
+  createDefaultAppBootstrap,
+  fetchAppBootstrap,
+  slimAppBootstrapForRoute,
+  type AppBootstrapResult,
+} from '@fecommunity/reactpress-toolkit/theme/server'
+import type { IncomingMessage } from 'http'
+import { cookies, headers } from 'next/headers'
+
+type BootstrapCategory = {
+  value: string
+  label: string
+  articleCount?: number
+}
+
+async function buildVisitorRequest(): Promise<IncomingMessage> {
+  const cookieStore = await cookies()
+  const headerStore = await headers()
+  const cookieHeader = cookieStore
+    .getAll()
+    .map((item) => `${item.name}=${encodeURIComponent(item.value)}`)
+    .join('; ')
+
+  return {
+    headers: {
+      cookie: cookieHeader,
+      'accept-language': headerStore.get('accept-language') ?? '',
+    },
+  } as IncomingMessage
+}
+
+export async function loadAppBootstrap(pathname = '/'): Promise<AppBootstrapResult> {
+  try {
+    const req = await buildVisitorRequest()
+    const bootstrap = await fetchAppBootstrap({ manifest: themeManifest, req })
+    const slimmed = slimAppBootstrapForRoute(bootstrap, pathname)
+    const categories = (bootstrap.categories as BootstrapCategory[]).map(
+      ({ value, label, articleCount }) => ({ value, label, articleCount })
+    )
+    return { ...slimmed, categories }
+  } catch (error) {
+    console.error('[reactpress-theme-starter] fetchAppBootstrap failed, using defaults', error)
+    return createDefaultAppBootstrap()
+  }
+}
+
+export { themeManifest }

package/lib/reactpress/coercePublishedPage.ts

@@ -0,0 +1,12 @@
+import type { IPage } from '@fecommunity/reactpress-toolkit/types'
+
+/** CMS page props from toolkit SSR helpers are typed as `unknown`. */
+export function coercePublishedPage(page: unknown): IPage | null {
+  if (!page || typeof page !== 'object') return null
+
+  const candidate = page as Partial<IPage>
+  if (typeof candidate.id !== 'string' || !candidate.id.trim()) return null
+  if (candidate.status !== 'publish') return null
+
+  return candidate as IPage
+}

package/lib/reactpress/contentSeo.ts

@@ -0,0 +1,123 @@
+import type { IArticle, IKnowledge, IPage } from '@fecommunity/reactpress-toolkit/types'
+import type { Metadata } from 'next'
+
+import { buildPageMetadata, DEFAULT_OG_IMAGE } from './seoMetadata'
+
+export type SiteSeoContext = {
+  siteName?: string
+  siteDescription?: string
+  siteUrl?: string
+  seoKeyword?: string
+  seoDesc?: string
+}
+
+export function parseSiteSeoContext(
+  row: Record<string, unknown> | null,
+  siteMeta?: { siteName?: string; siteDescription?: string; siteUrl?: string }
+): SiteSeoContext {
+  return {
+    siteName: siteMeta?.siteName,
+    siteDescription: siteMeta?.siteDescription,
+    siteUrl: siteMeta?.siteUrl,
+    seoKeyword: row?.seoKeyword != null ? String(row.seoKeyword) : undefined,
+    seoDesc: row?.seoDesc != null ? String(row.seoDesc) : undefined,
+  }
+}
+
+function tagLabel(tag: string | { label?: string }) {
+  return typeof tag === 'string' ? tag : (tag?.label ?? '')
+}
+
+function buildKeywords(
+  title: string,
+  tags: Array<string | { label?: string }> | undefined,
+  siteKeywords?: string
+) {
+  return [title]
+    .concat((tags ?? []).map(tagLabel))
+    .concat(siteKeywords?.split(',') ?? [])
+    .filter(Boolean)
+    .join(',')
+}
+
+function resolveCmsPagePath(page: IPage): string {
+  const customPath = page.path?.trim()
+  if (customPath) {
+    return customPath.startsWith('/') ? customPath : `/${customPath}`
+  }
+  return `/page/${page.id}`
+}
+
+export function buildArticleMetadata(
+  article: IArticle,
+  site: SiteSeoContext,
+  imageUrl?: string
+): Metadata {
+  const siteName = site.siteName ?? 'Blog'
+  const description = article.summary || site.seoDesc || site.siteDescription
+  const keywords = buildKeywords(article.title, article.tags, site.seoKeyword)
+  const images = imageUrl ? [imageUrl] : [DEFAULT_OG_IMAGE]
+
+  return buildPageMetadata({
+    title: article.title,
+    description,
+    keywords,
+    path: `/article/${article.id}`,
+    siteUrl: site.siteUrl,
+    siteName,
+    ogType: 'article',
+    images,
+    publishedTime: article.publishAt,
+    modifiedTime: article.updateAt,
+    tags: (article.tags ?? []).map(tagLabel).filter(Boolean),
+  })
+}
+
+export function buildKnowledgeChapterMetadata(
+  chapter: IKnowledge,
+  book: IKnowledge,
+  site: SiteSeoContext
+): Metadata {
+  const description = chapter.summary || book.summary || site.seoDesc || site.siteDescription
+
+  return buildPageMetadata({
+    title: `${chapter.title} - ${book.title}`,
+    description,
+    path: `/knowledge/${book.id}/${chapter.id}`,
+    siteUrl: site.siteUrl,
+    siteName: site.siteName ?? 'Blog',
+    ogType: 'article',
+    images: [DEFAULT_OG_IMAGE],
+    publishedTime: chapter.publishAt,
+    modifiedTime: chapter.updateAt,
+  })
+}
+
+export function buildCmsPageMetadata(page: IPage, site: SiteSeoContext): Metadata {
+  const description = site.seoDesc || site.siteDescription
+
+  return buildPageMetadata({
+    title: page.name,
+    description,
+    path: resolveCmsPagePath(page),
+    siteUrl: site.siteUrl,
+    siteName: site.siteName ?? 'Blog',
+    images: [DEFAULT_OG_IMAGE],
+  })
+}
+
+export function buildArticleJsonLd(article: IArticle, siteUrl?: string, coverUrl?: string) {
+  const url = siteUrl ? new URL(`/article/${article.id}`, siteUrl).href : undefined
+
+  return {
+    '@context': 'https://schema.org',
+    '@type': 'Article',
+    headline: article.title,
+    description: article.summary,
+    datePublished: article.publishAt,
+    dateModified: article.updateAt ?? article.publishAt,
+    ...(url ? { url, mainEntityOfPage: url } : {}),
+    ...(coverUrl ? { image: [coverUrl] } : {}),
+    keywords: (article.tags ?? []).map(tagLabel).filter(Boolean).join(', '),
+  }
+}

package/lib/reactpress/env.ts

@@ -0,0 +1,31 @@
+/** App/runtime helpers — values are injected via next.config `env` when possible. */
+import { DEFAULT_LOCAL_ADMIN, DEFAULT_LOCAL_SITE } from '../../scripts/resolve-api-env.mjs'
+
+export {
+  DEFAULT_LOCAL_ADMIN,
+  DEFAULT_LOCAL_API,
+  DEFAULT_LOCAL_SITE,
+} from '../../scripts/resolve-api-env.mjs'
+
+export function getClientSiteUrl(): string {
+  return (process.env.CLIENT_SITE_URL || DEFAULT_LOCAL_SITE).replace(/\/$/, '')
+}
+
+export function getAdminBaseUrl(): string {
+  const configured = process.env.NEXT_PUBLIC_REACTPRESS_ADMIN_URL?.trim()
+  if (configured) return configured.replace(/\/$/, '')
+  return DEFAULT_LOCAL_ADMIN
+}
+
+export function getApiPreconnectOrigin(): string | null {
+  const api =
+    process.env.REACTPRESS_API_URL?.trim() ||
+    process.env.SERVER_API_URL?.trim() ||
+    process.env.NEXT_PUBLIC_REACTPRESS_API_URL?.trim()
+
+  if (!api || api.startsWith('/')) return null
+
+  const origin = api.replace(/\/api\/?$/, '')
+  if (/localhost|127\.0\.0\.1/i.test(origin)) return null
+  return origin
+}

package/lib/reactpress/feedFooterPlacement.ts

@@ -0,0 +1,16 @@
+export const FEED_PAGE_SIZE = 12
+
+export type FeedFooterPlacementOptions = {
+  hasMore?: boolean
+  itemCount?: number
+  pageSize?: number
+}
+
+/** 内容足够多、需要滚动加载时 footer 放右侧栏；否则放页面底部。 */
+export function shouldPlaceFooterInSidebar({
+  hasMore = false,
+  itemCount = 0,
+  pageSize = FEED_PAGE_SIZE,
+}: FeedFooterPlacementOptions = {}): boolean {
+  return hasMore || itemCount >= pageSize
+}

package/lib/reactpress/fetchSetting.ts

@@ -0,0 +1,19 @@
+/** Same-origin visitor setting fetch — avoids toolkit axios onError console noise. */
+export async function fetchVisitorSetting(): Promise<Record<string, unknown> | null> {
+  const apiBase = (process.env.NEXT_PUBLIC_REACTPRESS_API_URL || '/api').replace(/\/$/, '')
+  const url = apiBase.startsWith('http') ? `${apiBase}/setting/get` : `${apiBase}/setting/get`
+
+  try {
+    const response = await fetch(url, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: '{}',
+    })
+    if (!response.ok) return null
+
+    const payload = (await response.json()) as { success?: boolean; data?: Record<string, unknown> }
+    return payload?.success ? (payload.data ?? null) : null
+  } catch {
+    return null
+  }
+}

package/lib/reactpress/homeFooter.tsx

@@ -0,0 +1,27 @@
+'use client'
+
+import { createContext, useContext, useMemo, useState, type ReactNode } from 'react'
+
+type HomeFooterContextValue = {
+  /** 为 true 时在页面底部展示 SiteFooter（列表页内容较少时）。 */
+  showLayoutFooter: boolean
+  setShowLayoutFooter: (show: boolean) => void
+}
+
+const HomeFooterContext = createContext<HomeFooterContextValue | null>(null)
+
+export function HomeFooterProvider({ children }: { children: ReactNode }) {
+  // 默认展示底部 footer；列表页内容较多时由 useFeedFooterPlacement 在 layout 阶段切换为侧栏。
+  const [showLayoutFooter, setShowLayoutFooter] = useState(true)
+  const value = useMemo(() => ({ showLayoutFooter, setShowLayoutFooter }), [showLayoutFooter])
+
+  return <HomeFooterContext.Provider value={value}>{children}</HomeFooterContext.Provider>
+}
+
+export function useHomeFooter() {
+  const context = useContext(HomeFooterContext)
+  if (!context) {
+    throw new Error('useHomeFooter must be used within HomeFooterProvider')
+  }
+  return context
+}

package/lib/reactpress/layout-shell.tsx

@@ -0,0 +1,19 @@
+'use client'
+
+import { useReportPageView } from '@fecommunity/reactpress-toolkit/ui'
+import { type ReactNode } from 'react'
+
+import BackToTop from '@/components/layout/BackToTop'
+import PageLoadProgress from '@/components/layout/PageLoadProgress'
+
+export function LayoutShell({ children }: { children: ReactNode }) {
+  useReportPageView()
+
+  return (
+    <>
+      <PageLoadProgress />
+      {children}
+      <BackToTop />
+    </>
+  )
+}