hexo-theme-stellar 2.0.0-rc.2 → 2.0.0-rc.4

package/layout/_partial/menubtn.ejs

@@ -1,4 +1,4 @@
-<div class="site-dock" role="group" aria-label="Layout panels">
+<div data-stellar-runtime-region class="site-dock" role="group" aria-label="Layout panels">
   <button type="button" class="<%- ui_classes('site-dock__button site-dock__button--rightbar', 'interactive') %>" aria-label="Open rightbar" aria-controls="rightbar-region" aria-expanded="false" data-shell-action="toggle-rightbar-drawer">
     <%- icon('default:rightbar', '', true) %>
   </button>

package/layout/_partial/primitives/region.ejs

@@ -6,11 +6,11 @@ if (!allowedSlots.includes(slot)) {
 var regionBody = typeof body === 'string' ? body : ''
 var html = ''
 if (slot === 'topbar') {
-  html = `<header id="topbar-region" class="site-region site-region--topbar ui-surface" data-region="topbar"><div class="site-region__viewport">${regionBody}</div></header>`
+  html = `<header data-stellar-runtime-region id="topbar-region" class="site-region site-region--topbar ui-surface" data-region="topbar"><div class="site-region__viewport">${regionBody}</div></header>`
 } else if (slot === 'leftbar') {
-  html = `<aside id="leftbar-region" class="site-region site-region--leftbar" data-region="leftbar" aria-label="Leftbar"><div class="site-region__surface ui-surface"><div class="site-region__decoration" aria-hidden="true"></div><div class="site-region__viewport">${regionBody}</div></div></aside>`
+  html = `<aside data-stellar-runtime-region id="leftbar-region" class="site-region site-region--leftbar" data-region="leftbar" aria-label="Leftbar"><div class="site-region__surface ui-surface"><div class="site-region__decoration" aria-hidden="true"></div><div class="site-region__viewport">${regionBody}</div></div></aside>`
 } else if (slot === 'rightbar') {
-  html = `<aside id="rightbar-region" class="site-region site-region--rightbar" data-region="rightbar" aria-label="Rightbar"><div class="site-region__surface ui-drawer-surface"><div class="site-region__viewport">${regionBody}</div></div></aside>`
+  html = `<aside data-stellar-runtime-region id="rightbar-region" class="site-region site-region--rightbar" data-region="rightbar" aria-label="Rightbar"><div class="site-region__surface ui-drawer-surface"><div class="site-region__viewport">${regionBody}</div></div></aside>`
 }
 %>
 <%- html %>

package/layout/_partial/primitives/shell.ejs

@@ -22,7 +22,7 @@ html += `<div class="site-shell" id="start" data-regions="${presentRegions.join(
 html += shellRegions.topbar || ''
 html += '<div class="site-workspace">'
 html += shellRegions.leftbar || ''
-html += `<main class="site-main" id="main">${main || ''}</main>`
+html += `<main data-stellar-runtime-region class="site-main" id="main">${main || ''}</main>`
 html += shellRegions.rightbar || ''
 html += '</div>'
 html += '<button type="button" class="site-scrim" data-shell-action="dismiss-drawer" aria-label="Close navigation" tabindex="-1"></button>'

package/layout/_partial/scripts/defines.ejs

@@ -21,121 +21,35 @@
   var searchProvider = extensions.search.provider === 'local' ? 'local_search' : extensions.search.provider
 %>
 
-<script type="text/javascript">
-  window.canonical = <%- JSON.stringify(canonicalWithEncoded) %>;
-  window.canonical["param"] = <%- JSON.stringify({permalink, checklink}) %>;
-  // Fix: Ensure page is at the correct top position on data load
-  if (history.scrollRestoration) {
-    history.scrollRestoration = 'auto';
-  }
-  (function() {
-    const scrollHandler = () => {
-      // 存在有效锚点时，等待布局稳定后滚动到目标
-      // （浏览器原生锚点滚动发生在布局完成前，长文章的懒加载图片/异步组件会把目标顶偏）
-      const hash = window.location.hash;
-      if (hash.length > 1) {
-        let anchorId = hash.slice(1);
-        try {
-          anchorId = decodeURIComponent(anchorId);
-        } catch (e) {
-          // 片段含非法编码时按原样查找
-        }
-        const anchor = document.getElementById(anchorId);
-        if (anchor) {
-          // #start 锚点贴顶，不预留 offset；其余锚点与 TOC 点击滚动保持一致
-          const offset = anchorId === 'start' ? 0 : 32;
-          const targetY = () => anchor.getBoundingClientRect().top + window.scrollY - offset;
-          let timer = null;
-          let lastY = null;
-          let quiet = 0;
-          let attempts = 0;
-          // 记录最近一次资源加载完成时间，判断异步数据/图片是否仍在改变布局
-          let lastResourceTime = performance.now();
-          let observer = null;
-          try {
-            observer = new PerformanceObserver(function (list) {
-              lastResourceTime = performance.now();
-            });
-            observer.observe({ entryTypes: ['resource'] });
-          } catch (e) {}
-          // 只跟踪主题 request/cache 客户端，不替换浏览器原生 fetch/XHR。
-          const pendingRequests = new Set();
-          const onRequestStart = event => pendingRequests.add(event.detail.key);
-          const onRequestEnd = event => pendingRequests.delete(event.detail.key);
-          document.addEventListener('stellar:request-start', onRequestStart);
-          document.addEventListener('stellar:request-end', onRequestEnd);
-          const cancel = () => {
-            if (timer !== null) {
-              clearInterval(timer);
-              timer = null;
-            }
-            if (observer !== null) {
-              try {
-                observer.disconnect();
-              } catch (e) {}
-            }
-            document.removeEventListener('stellar:request-start', onRequestStart);
-            document.removeEventListener('stellar:request-end', onRequestEnd);
-          };
-          const adjust = () => {
-            const y = targetY();
-            const atTarget = Math.abs(window.scrollY - y) <= 2;
-            if (!atTarget || lastY === null || Math.abs(y - lastY) > 2) {
-              window.scrollTo({ top: y, behavior: 'instant' });
-              lastY = y;
-              quiet = 0;
-            } else {
-              quiet++;
-            }
-            attempts++;
-            const resourceQuiet = performance.now() - lastResourceTime > 3000;
-            // 位置连续 1.8 秒无变化、无进行中的请求且最近 3 秒无资源加载才视为稳定；最长等待 30 秒
-            if ((quiet >= 3 && pendingRequests.size === 0 && resourceQuiet) || attempts >= 50) {
-              cancel();
-            }
-          };
-          requestAnimationFrame(() => {
-            // 锚点链接打开时直接定位，不做动画；用户主动点击（如 TOC）仍走平滑滚动
-            window.scrollTo({ top: targetY(), behavior: 'instant' });
-            timer = setInterval(adjust, 600);
-          });
-          // 用户主动滚动时停止自动校正
-          window.addEventListener('wheel', cancel, { passive: true });
-          window.addEventListener('touchstart', cancel, { passive: true });
-          window.addEventListener('mousedown', cancel, { passive: true });
-          window.addEventListener('keydown', cancel, { passive: true });
-          return;
-        }
-      }
-      // 没有锚点时始终保持页面顶部；Wiki Hero 只在用户显式访问 #start 时定位正文。
-      window.scrollTo(0, 0);
-    };
-    if (document.readyState !== 'loading') scrollHandler();
-    else document.addEventListener('DOMContentLoaded', scrollHandler);
-  })();
+<script data-stellar-script="defines" type="text/javascript">
+  window.canonical = <%- script_json(canonicalWithEncoded) %>;
+  window.canonical["param"] = <%- script_json({permalink, checklink}) %>;
   const ctx = {
     date_suffix: {
-      just: `<%- __('meta.date_suffix.just') %>`,
-      min: `<%- __('meta.date_suffix.min') %>`,
-      hour: `<%- __('meta.date_suffix.hour') %>`,
-      day: `<%- __('meta.date_suffix.day') %>`,
+      just: <%- script_json(__('meta.date_suffix.just')) %>,
+      min: <%- script_json(__('meta.date_suffix.min')) %>,
+      hour: <%- script_json(__('meta.date_suffix.hour')) %>,
+      day: <%- script_json(__('meta.date_suffix.day')) %>,
     },
-    root : `<%- config.root %>`,
+    root : <%- script_json(config.root) %>,
     tag_plugins: {
-      chat: {api: <%- JSON.stringify(assets.services.chat.endpoint) %>},
+      chat: {api: <%- script_json(assets.services.chat.endpoint) %>},
     },
     // 图标由构建期生成的 /js/stellar-icons.js 填充（defer，早于 DOMContentLoaded 就绪）
     icons: {},
-    ui: { classes: <%- JSON.stringify(ui_capabilities()) %> },
-    services: <%- JSON.stringify(clientServices) %>,
+    ui: { classes: <%- script_json(ui_capabilities()) %> },
+    services: <%- script_json(clientServices) %>,
   };
 
   // required plugins (only load if needs)
-  if (`<%- searchProvider || '' %>`) {
-    ctx.search = {};
-    ctx.search.service = `<%- searchProvider || '' %>`;
+  if (<%- script_json(searchProvider || '') %>) {
+    ctx.search = {
+      more: <%- script_json(__('meta.more')) %>,
+      no_more: <%- script_json(__('search.no_more')) %>
+    };
+    ctx.search.service = <%- script_json(searchProvider || '') %>;
     if (ctx.search.service == 'local_search') {
-      let service_obj = <%- JSON.stringify({
+      let service_obj = <%- script_json({
         field: localSearch.scope,
         path: '/search.json',
         content: localSearch.includeContent,
@@ -147,24 +61,11 @@
     }
   }
   const def = {
-    avatar: `<%- stellar_config('fallbacks.avatar') %>`,
-    cover: `<%- stellar_config('fallbacks.cover') %>`,
+    avatar: <%- script_json(stellar_config('fallbacks.avatar')) %>,
+    cover: <%- script_json(stellar_config('fallbacks.cover')) %>,
   };
   // 经典脚本仍消费这些只读投影。
   window.ctx = ctx;
   window.def = def;
 
-  // 搜索跳转高亮：URL 带 ?kw= 时按需加载，定位正文中的匹配词
-  (function () {
-    try {
-      if (!window.location.search) return;
-      if (!new URLSearchParams(window.location.search).has('kw')) return;
-      document.addEventListener('DOMContentLoaded', function () {
-        // utils 由前置 /js/utils.js 同步定义（同时暴露 window.utils）。
-        if (typeof utils === 'object' && typeof utils.js === 'function') {
-          utils.js('<%- url_for('/js/search/highlight.js') %>', { defer: true }).catch(function () {});
-        }
-      });
-    } catch (e) {}
-  })();
 </script>

package/layout/_partial/scripts/runtime.ejs

@@ -48,8 +48,10 @@ var runtimeJson = browser_runtime_manifest({
   messages: runtimeMessages
 })
 %>
-<% if (runtimeMathProvider === 'katex') { %>
-<link rel="stylesheet" href="<%- url_for(runtimeAssets.features.katexCss) %>" integrity="sha384-//SZkxyB7axjCAopkAL1E1rve+ZSPKapD89Lo/lLhcsXR+zOYl5z6zJZEFXil+q0" crossorigin="anonymous">
+<% if (runtimeMathProvider === 'katex') {
+var katexStyle = katex_stylesheet()
+%>
+<link data-stellar-page-style rel="stylesheet" href="<%= url_for(katexStyle.css) %>"<% if (katexStyle.integrity) { %> integrity="<%= katexStyle.integrity %>" crossorigin="anonymous"<% } %>>
 <% } %>
-<script type="application/json" id="stellar-runtime-config"><%- runtimeJson %></script>
-<script type="module" src="<%- url_for(runtimeAssets.runtime.bootstrap) %>?v=<%- stellar_info('version') %>&runtime=1"></script>
+<script data-stellar-script="core" type="application/json" id="stellar-runtime-config"><%- runtimeJson %></script>
+<script data-stellar-script="core" type="module" src="<%- url_for(runtimeAssets.runtime.bootstrap) %>?v=<%- stellar_info('version') %>&runtime=1"></script>

package/layout/_partial/scripts.ejs

@@ -5,41 +5,21 @@ function custom_inject() {
   return stellar_inject('bodyEnd', renderViewModel ? renderViewModel.render.document.bodyEndInject : content_config(page).inject?.bodyEnd)
 }
 
-// tagtree 脚本仅在最终 Region 实例包含 tagtree 时加载。
-function tagtreeWidgetOnPage() {
-  var layout = renderViewModel?.render.layout
-    || page.notebookIndex?.collection?.layout
-    || {};
-  var regions = [layout.topbar, layout.leftbar, layout.rightbar];
-  var widgets = regions.flatMap(function (region) {
-    return Array.isArray(region?.widgets) ? region.widgets : []
-  })
-  if (!Array.isArray(widgets)) {
-    return false;
-  }
-  return widgets.some(function (w) {
-    if (w && typeof w === 'object') {
-      return w.id === 'tagtree' || w.layout === 'tagtree' || w.override === 'tagtree';
-    }
-    return false;
-  });
-}
 
 %>
 <%- partial('scripts/defines') %>
 
 <!-- core: 迁移期 DOM/资源兼容工具；Extension 注册与生命周期由 ESM runtime 所有 -->
-<script src="<%- url_for('/js/utils.js') %>?v=<%- stellar_info('version') %>"></script>
-<script defer src="<%- url_for('/js/stellar-icons.js') %>?v=<%- stellar_info('version') %>"></script>
-<script src="<%- url_for(`${stellar_info('main_js')}?v=${stellar_info('version')}`) %>" defer></script>
-<script defer src="<%- url_for('/js/profile.js') %>?v=<%- stellar_info('version') %>"></script>
+<script data-stellar-script="core" src="<%- url_for('/js/utils.js') %>?v=<%- stellar_info('version') %>"></script>
+<script data-stellar-script="core" defer src="<%- url_for('/js/stellar-icons.js') %>?v=<%- stellar_info('version') %>"></script>
+<script data-stellar-script="core" src="<%- url_for(`${stellar_info('main_js')}?v=${stellar_info('version')}`) %>" defer></script>
+<script data-stellar-script="core" defer src="<%- url_for('/js/profile.js') %>?v=<%- stellar_info('version') %>"></script>
+
 
-<% if (tagtreeWidgetOnPage()) { %>
-  <script>window.__STELLAR_TAGTREE__ = { expand_active: <%- JSON.stringify(!!(stellar_data('widgets').tagtree && stellar_data('widgets').tagtree.expand_active)) %> };</script>
-  <script defer src="<%- url_for('/js/tagtree.js') %>?v=<%- stellar_info('version') %>"></script>
-<% } %>
 
 <%- partial('scripts/runtime', {viewModel: typeof viewModel !== 'undefined' ? viewModel : null}) %>
 
 <!-- inject -->
 <%- custom_inject() %>
+
+<script data-stellar-script="core" defer src="<%- url_for('/js/navigation-init.js') %>?v=<%- stellar_info('version') %>"></script>

package/layout/_partial/search/dialog.ejs

@@ -1,7 +1,7 @@
 <%
 var localSearch = stellar_config('search.provider') === 'local'
 %>
-<dialog class="search-dialog" id="site-search-dialog" aria-labelledby="site-search-title">
+<dialog data-stellar-runtime-region class="search-dialog" id="site-search-dialog" aria-labelledby="site-search-title">
   <div class="search-dialog__panel search-wrapper" id="site-search-wrapper" searching="false">
     <div class="search-dialog__header">
       <div class="search-form" role="search">

package/layout/_partial/sidebar/brand.ejs

@@ -4,7 +4,7 @@ var brandPlacement = typeof placement !== 'undefined' ? placement : 'leftbar'
 var activeViewModel = typeof viewModel !== 'undefined' ? viewModel : null
 var brandStyle = brandPlacement === 'topbar'
   ? 'topbar'
-  : brand.style === 'compact' ? 'compact' : 'regular'
+  : brandPlacement === 'main' || brand.style === 'compact' ? 'compact' : 'regular'
 
 function layoutBrandNavigation() {
   if (brandPlacement !== 'leftbar' || brand.source !== 'collection' || brand.backButton !== true) return ''
@@ -82,7 +82,7 @@ function layoutCollectionStats(apiBase) {
 }
 
 function layoutSiteStats(apiBase) {
-  var username = typeof brandGithubUsername === 'function' ? brandGithubUsername() : ''
+  var username = typeof brand.ghuser === 'string' ? brand.ghuser.trim() : ''
   if (!username) return ''
   var encodedUsername = encodeURIComponent(username)
   var githubHref = `https://github.com/${encodedUsername}`

package/layout/_partial/widgets/related.ejs

@@ -8,7 +8,7 @@ function relatedPostsInTopic() {
     return {
       href: pretty_url(post.path),
       title: post.title,
-      active: post.current
+      active: post.id === topicViewModel.item.id
     }
   })
   var body = partial('_partial/components/collection', {options: {

package/layout/_partial/widgets/tagtree.ejs

@@ -75,7 +75,7 @@ function layoutDiv() {
     className: 'tag-tree-widget',
     title: __('meta.tag_tree'),
     body: body,
-    attrs: {'data-notebook': notebookId}
+    attrs: {'data-notebook': notebookId, 'data-expand-active': !!item.expand_active}
   })
 }
 %>

package/layout/archive.ejs

@@ -9,11 +9,6 @@ function layoutArchiveList() {
   var cls = ''
   if (page.author) {
     page.title = page.author.name
-    page.banner = {
-      image: page.author.banner,
-      avatar: page.author.avatar,
-      tagline: page.author.description
-    }
     el += partial('_partial/main/navbar/article_banner')
     cls += ' author'
   } else {
@@ -21,7 +16,7 @@ function layoutArchiveList() {
     el += partial('_partial/main/listing_nav/blog')
   }
   el += `<div class="post-list${cls} archives">`
-  var years = []
+  var groups = new Map()
   function requirePostViewModel(post) {
     var viewModel = post_view_model(post)
     if (!['post', 'topic'].includes(viewModel?.collection?.profile) || !viewModel.render?.listing) {
@@ -29,26 +24,22 @@ function layoutArchiveList() {
     }
     return viewModel
   }
-  var posts = site.posts.filter(function(post) {
-    var listing = requirePostViewModel(post).render.listing
-    if (!listing.listed) return false
-    return page.author == null || listing.authorId == page.author.id
-  })
-  posts.sort('date', -1).each(function(post) {
-    post.year = date(post.date, 'YYYY')
-    if (post.year && (years.includes(post.year) == false) && (post.title || post.date)) {
-      years.push(post.year)
-    }
+  site.posts.sort('date', -1).each(function(post) {
+    var viewModel = requirePostViewModel(post)
+    var listing = viewModel.render.listing
+    if (!listing.listed) return
+    if (page.author != null && listing.authorId != page.author.id) return
+    var year = date(post.date, 'YYYY')
+    if (!year || !(post.title || post.date)) return
+    if (!groups.has(year)) groups.set(year, [])
+    groups.get(year).push({viewModel: viewModel})
   })
-  for (var year of years) {
+  for (var [year, records] of groups) {
     el += `<article class="${scrollreveal('')}" id="archive">`
     el += `<div class='archive-header h4'>${year}</div>`
-    posts.sort('date', -1).filter(function (post) {
-      post.year = date(post.date, 'YYYY')
-      return post.year == year
-    }).each(function(post) {
-      el += partial('_partial/main/post_list/archive_item', {viewModel: requirePostViewModel(post)})
-    })
+    for (var record of records) {
+      el += partial('_partial/main/post_list/archive_item', record)
+    }
     el += `</article>`
   }
   el += `</div>`

package/layout/index.ejs

@@ -14,16 +14,20 @@ if (homeCmt && homeCmt !== false && is_home_first_page()) {
 var articleDefaults = stellar_config('article')
 var pinStyle = articleDefaults.listing.pinnedLayout
 var pinFlat = pinStyle === 'flat'
+var postViewModels = new Map()
 
 // 与 pin_slider.ejs 保持一致的置顶判定与排序权重
 function pinValue(post) {
   return postListing(post).priority
 }
 function requirePostViewModel(post) {
+  var key = post.source || post.path || post._id || post
+  if (postViewModels.has(key)) return postViewModels.get(key)
   var viewModel = post_view_model(post)
   if (!['post', 'topic'].includes(viewModel?.collection?.profile) || !viewModel.render?.listing) {
     throw new Error(`Stellar v2: Post ${post?.source || post?.path || '<unknown>'} 缺少列表 ViewModel`)
   }
+  postViewModels.set(key, viewModel)
   return viewModel
 }
 function postListing(post) {

package/layout/layout.ejs

@@ -2,7 +2,7 @@
 var pageConfig = content_config(page)
 var isOrdinaryPost = page.layout === 'post' && pageConfig.collection?.profile !== 'topic'
 var activeViewModel = (isOrdinaryPost || pageConfig.collection?.profile === 'topic')
-  ? post_view_model(page)
+  ? (page.viewModel || post_view_model(page))
   : page.viewModel
 var activeProfile = activeViewModel?.collection?.profile
 if (isOrdinaryPost && (activeProfile !== 'post' || activeViewModel?.render == null)) {
@@ -30,7 +30,7 @@ function siteBackground(enabled) {
 
 function coverSlot(viewModel) {
   var coverBody = viewModel ? partial('_partial/cover/index', {viewModel: viewModel}).trim() : ''
-  return `<div id="site-cover" class="site-cover">${coverBody}</div>`
+  return `<div data-stellar-runtime-region id="site-cover" class="site-cover">${coverBody}</div>`
 }
 
 function regionSlot(slot, state, viewModel) {

package/layout/page.ejs

@@ -2,7 +2,7 @@
 var pageConfig = content_config(page)
 var registeredProfile = pageConfig.collection?.profile
 var postViewModel = page.layout === 'post' && (registeredProfile == null || registeredProfile === 'topic')
-  ? post_view_model(page)
+  ? (page.viewModel || post_view_model(page))
   : null
 var wikiViewModel = page.viewModel?.collection?.profile === 'wiki' ? page.viewModel : null
 var notebookViewModel = page.viewModel?.collection?.profile === 'notebook' ? page.viewModel : null

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hexo-theme-stellar",
-  "version": "2.0.0-rc.2",
+  "version": "2.0.0-rc.4",
   "description": "An all-in-one Hexo theme for blogs, project documentation, knowledge bases, series, and notebooks.",
   "main": "package.json",
   "scripts": {
@@ -46,17 +46,20 @@
   },
   "dependencies": {
     "cheerio": "^1.1.0",
-    "glob": "^10.4.0",
     "hexo-front-matter": "^4.2.1",
+    "hexo-pagination": "^3.0.0",
     "hexo-renderer-ejs": "^2.0.0",
     "hexo-renderer-stylus": "^3.0.1",
-    "hexo-pagination": "^3.0.0",
     "js-yaml": "^4.1.0",
-    "probe-image-size": "^7.2.3"
+    "probe-image-size": "^7.2.3",
+    "sharp": "^0.34.5"
   },
   "homepage": "https://xaoxuu.com/wiki/stellar/",
   "devDependencies": {
+    "@eslint/js": "^9.39.5",
     "eslint": "^9.39.5",
+    "glob": "^10.4.0",
+    "globals": "^14.0.0",
     "hexo-util": "^4.0.0"
   }
 }

package/scripts/commands/stellar.js

@@ -14,13 +14,16 @@ function hexoVersion(ctx) {
 }
 
 hexo.extend.console.register("stellar", "Diagnose and author a Stellar v2 site.", {
-  usage: "<doctor|new note> [options]",
+  usage: "<doctor|new note|images> [options]",
   commands: [
+    { name: "images", desc: "Incrementally prepare persistent image dimensions and colors without changing Markdown." },
     { name: "doctor", desc: "Validate the environment and v2 configuration." },
     { name: "new note", desc: "Create a Note in a known Notebook." }
   ],
   options: [
-    { name: "--dry-run", desc: "Print the new note plan without writing files." },
+    { name: "--dry-run", desc: "Preview note creation or missing image metadata without writing files or downloading images." },
+    { name: "--page <route>", desc: "Limit image discovery to one generated HTML page." },
+    { name: "--refresh <url>", desc: "Refresh one image even when metadata already exists." },
     { name: "--format <text|json>", desc: "Doctor output format; use Hexo global --silent with JSON." },
     { name: "--notebook <id>", desc: "Notebook id for stellar new note." },
     { name: "--title <title>", desc: "Note title and filename for stellar new note." },
@@ -28,6 +31,15 @@ hexo.extend.console.register("stellar", "Diagnose and author a Stellar v2 site."
   ]
 }, async function (args) {
   const subcommand = args._[0];
+  if (subcommand === "images") {
+    this.log?.info?.("Image metadata: rendering pages for image discovery…");
+    await this.load();
+    const report = await require("../lib/image-metadata").prepareImages(this, {
+      dryRun: args.dryRun, page: args.page, refresh: args.refresh
+    });
+    console.log(JSON.stringify(report, null, 2));
+    return report;
+  }
   if (subcommand === "doctor") {
     const format = args.format || "text";
     if (!["text", "json"].includes(format)) throw new Error("--format 必须是 text 或 json");
@@ -51,5 +63,5 @@ hexo.extend.console.register("stellar", "Diagnose and author a Stellar v2 site."
     }
     return plan;
   }
-  throw new Error("Usage: hexo stellar <doctor|new note>");
+  throw new Error("Usage: hexo stellar <doctor|new note|images>");
 });

package/scripts/events/index.js

@@ -4,6 +4,10 @@
 
 require('./lib/config-hot-reload').registerConfigHotReload(hexo);
 
+hexo.on('ready', () => {
+  require('../lib/image-metadata').excludeMetadataFromSource(hexo);
+});
+
 hexo.on('generateBefore', () => {
   // 页面路径归一化：xxx.html → xxx/，必须先于所有读取 page.path 的逻辑
   require('./lib/path_normalize')(hexo);
@@ -47,27 +51,10 @@ hexo.on('ready', () => {
   checkVersion(hexo, { useCache: true });
 });
 
-// 防止重复注册
-let hasRun = false;
-
-hexo.extend.filter.register('before_generate', async () => {
-  const isDev = ['s', 'server', 'serve'].some(arg => process.argv.includes(arg));
-  if (!isDev) {
-    return;
-  }
-
-  if (hasRun) return;
-  hasRun = true;
-  
-  // 读取主题配置开关
-  const enabled = hexo.stellar.config.features.lazyLoading.autoAspectRatio === true;
-
-  const generateImageRatios = require('./lib/get_image_ratios');
-  const fixMarkdownImages = require('./lib/fix_image_tags');
-
-  if (enabled) {
-    // 构建前：生成缓存 + 写回 Markdown
-    await generateImageRatios(hexo);
-    fixMarkdownImages(hexo); // 不用 await，因为是同步的
-  }
+// Complete missing metadata before generate writes routes or server exposes them.
+// The explicit CLI owns its own preprocessing pass and must not recurse here.
+hexo.extend.filter.register('after_generate', async () => {
+  if (!['generate', 'g', 'server', 's', 'serve'].includes(hexo.env?.cmd)) return;
+  if (hexo.stellar?.config?.features?.imageOptimization?.enabled !== true) return;
+  await require('../lib/image-metadata').prepareBuildImages(hexo);
 });

package/scripts/events/lib/authors.js

@@ -13,6 +13,7 @@ module.exports = ctx => {
   // url
   for (let key of Object.keys(authors)) {
     let author = authors[key]
+    author.id = key
     author.path = `${basePath}/${key}/index.html`
   }
   // default author

package/scripts/events/lib/doc_tree.js

@@ -11,16 +11,14 @@ const { getCollectionId } = require("../../lib/content-config");
 const { buildWikiTree } = require("../../lib/doc_tree");
 const { requireLayoutProfiles } = require("../../lib/layout-config");
 const {
+  buildWikiCollectionModel,
   buildWikiListingRender,
   buildWikiPageViewModelBase,
   buildWikiRelated,
   completeWikiPageViewModel
 } = require("../../lib/models");
 const { ensureRuntimeData } = require("../../lib/runtime-data");
-const {
-  setProfileViewModelBase,
-  setProfileViewModelInput
-} = require("../../lib/page-view-model-registry");
+const { pageViewModelsFor } = require("../../lib/page-view-model-registry");
 const { sourcePathForData } = require("../../lib/source-config");
 
 function cloneConfig(value) {
@@ -49,6 +47,7 @@ module.exports = (ctx, pipeline) => {
   const runtimeData = ensureRuntimeData(ctx);
   runtimeData.wiki = wiki;
 
+  const collectionModels = new Map();
   const entries = [];
   const homepageEntries = new Map();
   for (const record of records) {
@@ -66,6 +65,8 @@ module.exports = (ctx, pipeline) => {
       collectionListed: wiki.shelf.includes(collectionId),
       isBackup: process.env.IS_BACKUP === "true"
     };
+    if (!collectionModels.has(collectionId)) collectionModels.set(collectionId, buildWikiCollectionModel(input, collectionId));
+    input.collectionModel = collectionModels.get(collectionId);
     const base = buildWikiPageViewModelBase(input);
     const entry = { page, collectionId, input, base };
     entries.push(entry);
@@ -92,9 +93,9 @@ module.exports = (ctx, pipeline) => {
       related,
       listing: listings.get(entry.collectionId)
     });
-    entry.page.viewModel = completeWikiPageViewModel(completeInput, entry.base);
-    setProfileViewModelInput("wiki", entry.page, completeInput);
-    setProfileViewModelBase("wiki", entry.page, entry.base);
+    pageViewModelsFor(ctx).setPageViewModel(entry.page, completeWikiPageViewModel(completeInput, entry.base));
+    pageViewModelsFor(ctx).setProfileViewModelInput("wiki", entry.page, completeInput);
+    pageViewModelsFor(ctx).setProfileViewModelBase("wiki", entry.page, entry.base);
   }
 
   wiki.index = {