hd-garden 0.5.2 → 0.5.3

package/app/blog/[...path]/page.tsx

@@ -111,7 +111,7 @@ export default async function PostPage({
           <ArticleTags tags={post.tags} />
           {post.cover && (
             <figure className="article-hero article-cover cover-card cover-img">
-              <CoverImage className="u-photo" src={post.cover} image={post.coverImage} alt={`${post.title} 封面`} sizes="(max-width: 920px) calc(100vw - 40px), 880px" priority />
+              <CoverImage className="u-photo" src={post.cover} image={post.coverImage} alt={`${post.title} 封面`} sizes="(max-width: 852px) calc(100vw - 40px), 812px" priority />
             </figure>
           )}
         </header>

package/app/columns/[column]/[...path]/page.tsx

@@ -131,7 +131,7 @@ export default async function ColumnEntryPage({
           <ArticleTags tags={entry.tags} />
           {entry.cover && (
             <figure className="article-hero article-cover cover-img">
-              <CoverImage className="u-photo" src={entry.cover} image={entry.coverImage} alt={`${entry.title} 封面`} sizes="(max-width: 920px) calc(100vw - 40px), 880px" priority />
+              <CoverImage className="u-photo" src={entry.cover} image={entry.coverImage} alt={`${entry.title} 封面`} sizes="(max-width: 852px) calc(100vw - 40px), 812px" priority />
             </figure>
           )}
         </header>

package/app/components/ArticleMeasure.tsx

@@ -101,23 +101,32 @@ export function ArticleMeasure() {
       article.querySelectorAll<HTMLElement>(".fig").forEach((figure) => {
         const image = figure.querySelector("img");
         resetWide(figure);
+        // From here on the browser decides; the build-time breakout CSS steps aside.
+        figure.classList.remove("fig-wide");
         if (!image) return;
-        // Back to CSS sizing: natural size, capped at the column.
-        image.style.removeProperty("width");
-        if (!image.naturalWidth) return;
-        const attrWidth = Number(image.getAttribute("width")) || 0;
+        // Back to the unwidened size: the build-time width when the size is known
+        // (so an image that has not loaded keeps its box), else CSS sizing.
+        const baseWidth = Number(image.dataset.bw) || 0;
+        if (baseWidth) image.style.width = `${baseWidth}px`;
+        else image.style.removeProperty("width");
+        // Sizes read at build time let this run before the file arrives; otherwise wait for load.
+        const known = Number(image.dataset.nw) || 0;
+        const pixels = image.naturalWidth || known;
+        if (!pixels) return;
+        // width="" written by the build is the pixel size, not an author's choice.
+        const attrWidth = known ? Number(image.dataset.aw) || 0 : Number(image.getAttribute("width")) || 0;
         const breakout = figureBreakout({
           viewport,
           articleLeft: articleBox.left,
           articleRight: articleBox.right,
           figureClient: figure.clientWidth,
           imageClient: image.clientWidth,
-          naturalWidth: image.naturalWidth,
+          naturalWidth: pixels,
           attrWidth,
         });
         widen(figure, breakout);
         // Only a widened image, or one with a width attribute, gets an inline width.
-        const width = figureImageWidth({ naturalWidth: image.naturalWidth, attrWidth, widened: breakout.left > 0 });
+        const width = figureImageWidth({ naturalWidth: pixels, attrWidth, widened: breakout.left > 0 });
         if (width) image.style.width = `${width}px`;
       });
       placeToc();

package/app/components/MarkdownArticle.tsx

@@ -20,7 +20,8 @@ import { MarkdownImage } from "./MarkdownImage";
 import { CodeCopy } from "./garden/chrome";
 import { CodeDiff } from "./garden/chrome";
 import { GardenBlock } from "./garden/GardenBlock";
-import { linkAssets } from "@garden/generated-content";
+import { imageSizes, linkAssets } from "@garden/generated-content";
+import { imageDimensions, lookupImageSize } from "../../ui/garden/image-dims.mjs";
 import { siteConfig, siteLinks } from "@garden/site-config";
 import { articleLink, sameSiteMatcher } from "../../ui/garden/same-site.mjs";
 import { LinkCardRefresh } from "./LinkCardRefresh";
@@ -225,7 +226,7 @@ export function MarkdownArticle({ content }: { content: string }) {
   return (
     <div className="markdown-body prose">
       <ReactMarkdown
-        remarkPlugins={[...markdownPlugins, [remarkLinkCard, { sameSite }], remarkA2]}
+        remarkPlugins={[...markdownPlugins, [remarkLinkCard, { sameSite }], [remarkA2, { imageSize: (src: string) => lookupImageSize(imageSizes, src) }]]}
         rehypePlugins={[
           rehypeRaw,
           rehypeKatex,
@@ -260,7 +261,11 @@ export function MarkdownArticle({ content }: { content: string }) {
               </a>
             );
           },
-          img: MarkdownImage,
+          img: (props) => {
+            const size = lookupImageSize(imageSizes, typeof props.src === "string" ? props.src : undefined);
+            const dims = imageDimensions(props, size);
+            return <MarkdownImage {...props} {...dims} style={{ ...props.style, ...dims.style }} />;
+          },
           table: ({ children, ...props }) => (
             <div className="table-wrap" role="region" aria-label="表格，可横向滚动" tabIndex={0}>
               <table {...props}>{children}</table>

package/app/components/MarkdownImage.tsx

@@ -6,7 +6,7 @@ import { useEffect, useState, type ComponentPropsWithoutRef } from "react";
 type MarkdownImageProps = ComponentPropsWithoutRef<"img"> & { node?: unknown };
 
 // eslint-disable-next-line @typescript-eslint/no-unused-vars
-export function MarkdownImage({ alt = "", src, node, ...props }: MarkdownImageProps) {
+export function MarkdownImage({ alt = "", src, node, style, ...props }: MarkdownImageProps) {
   const [open, setOpen] = useState(false);
   const description = alt || "查看原图";
 
@@ -37,7 +37,7 @@ export function MarkdownImage({ alt = "", src, node, ...props }: MarkdownImagePr
       >
         {/* Native images preserve Typora-authored relative paths. */}
         {/* eslint-disable-next-line @next/next/no-img-element */}
-        <img loading="lazy" alt={alt} src={src} {...props} />
+        <img loading="lazy" alt={alt} src={src} {...props} style={style} />
       </button>
 
       {open ? (
@@ -49,8 +49,9 @@ export function MarkdownImage({ alt = "", src, node, ...props }: MarkdownImagePr
           onClick={() => setOpen(false)}
         >
           <div className="markdown-image-lightbox-content" onClick={(event) => event.stopPropagation()}>
+            {/* The preview sizes itself; the article's inline width stays on the article image. */}
             {/* eslint-disable-next-line @next/next/no-img-element */}
-            <img src={src} alt={alt} {...props} />
+            <img src={src} alt={alt} width={props.width} height={props.height} />
             <button
               type="button"
               className="markdown-image-lightbox-close"

package/app/components/SiteHeader.tsx

@@ -12,7 +12,7 @@ import {
 } from "react";
 import type Fuse from "fuse.js";
 import { MagnifyingGlass, X } from "@phosphor-icons/react";
-import { searchFull, searchIndexUrl } from "@garden/site-config";
+import { brand, searchFull, searchIndexUrl } from "@garden/site-config";
 import { createSearch } from "../../ui/garden/search-match.mjs";
 import { createIdbStore, loadFullIndex, saveDataOn, whenIdleAfterLoad } from "../../ui/garden/search-full.mjs";
 import { siteConfig } from "../site.config";
@@ -358,7 +358,11 @@ export function SiteHeader() {
     <>
       <header className="sh-header">
         <div className="sh-bar">
-          <Link href="/" className="sh-word">{siteConfig.name}</Link>
+          <Link href="/" className="sh-word">
+            {/* Build-time SVG from brand.logo, cleaned of scripts and handlers. */}
+            {brand.logo ? <span className="sh-mark" aria-hidden="true" dangerouslySetInnerHTML={{ __html: brand.logo }} /> : null}
+            {siteConfig.name}
+          </Link>
           <nav className="sh-nav" aria-label="站点导航">
             {nav.map((item) => (
               <Link key={item.href} href={item.href} aria-current={current(item.href) ? "page" : undefined}>
@@ -372,7 +376,7 @@ export function SiteHeader() {
                 <circle cx="9" cy="9" r="5.8" />
                 <path d="M13.3 13.3 17 17" />
               </svg>
-              <span className="lbl">搜索文章</span>
+              <span className="lbl">搜索</span>
               <kbd><span className="kbd-mod kbd-mac">⌘</span><span className="kbd-mod kbd-other">Ctrl</span>{" "}K</kbd>
             </button>
             <button className="sh-icon sh-search-m" type="button" onClick={openSearch} onPointerDown={prefetchSearch} aria-label="搜索文章">

package/app/garden-modules.d.ts

@@ -59,6 +59,8 @@ declare module "@garden/generated-content" {
   };
   export type LinkAssets = { favicons: Record<string, string>; cards: Record<string, LinkCardMeta> };
   export const linkAssets: LinkAssets;
+  /** Intrinsic sizes of body images by src, read at build time. */
+  export const imageSizes: Record<string, { width: number; height: number }>;
 }
 
 declare module "@garden/site-config" {
@@ -67,6 +69,8 @@ declare module "@garden/site-config" {
   export const searchFull: { url: string; hash: string };
   /** The site address (site.config.yaml `url`, else SITE_URL) and base path, for spotting links back to the site. */
   export const siteLinks: { address: string; basePath: string };
+  /** Header logo as inline SVG ("" when hidden) and icon URLs, from brand in site.config.yaml. */
+  export const brand: { logo: string; favicon: string; appleTouchIcon: string };
   export const siteConfig: {
     name: string;
     tagline: string;
@@ -77,6 +81,7 @@ declare module "@garden/site-config" {
     footer: string;
     linkPreview?: { worker?: string };
     url?: string;
+    brand?: { logo?: string | false; favicon?: string; appleTouchIcon?: string | false };
   };
   export const githubUrl: string;
 }

package/app/globals.css

@@ -126,15 +126,6 @@ button {
   width: max-content;
 }
 
-.brand-mark {
-  width: 43px;
-  height: 50px;
-  display: grid;
-  place-items: center;
-  color: var(--faint);
-  border-right: 1px solid var(--line-strong);
-}
-
 .brand strong {
   display: block;
   font-size: 20px;
@@ -4115,11 +4106,6 @@ html[data-theme="dark"] .article-references {
     display: none;
   }
 
-  .brand-mark {
-    width: 36px;
-    height: 44px;
-  }
-
   .brand strong {
     font-size: 17px;
   }

package/app/layout.tsx

@@ -11,6 +11,7 @@ import {
   webmentionEndpoint,
 } from "./lib/site";
 import { githubUrl, siteConfig } from "./site.config";
+import { brand } from "@garden/site-config";
 
 export async function generateMetadata(): Promise<Metadata> {
   const siteUrl = await getSiteUrl();
@@ -29,7 +30,8 @@ export async function generateMetadata(): Promise<Metadata> {
       },
     },
     icons: {
-      icon: "/favicon.svg",
+      icon: [{ url: brand.favicon, type: brand.favicon.endsWith(".svg") ? "image/svg+xml" : undefined }],
+      ...(brand.appleTouchIcon ? { apple: [{ url: brand.appleTouchIcon, sizes: "180x180" }] } : {}),
     },
     robots: {
       index: true,

package/app/lib/remark-a2.mjs

@@ -1,3 +1,4 @@
+import { figureLayout } from "../../ui/garden/enhance.mjs";
 import { toString } from "mdast-util-to-string";
 
 const ALERT_TITLE = {
@@ -168,7 +169,7 @@ function figureCaption(image) {
   return "";
 }
 
-function asFigure(node) {
+function asFigure(node, imageSize) {
   if (node?.type !== "paragraph" || node.data?.hName) return null;
   const children = meaningfulChildren(node);
   if (children.length !== 1 || children[0].type !== "image") return null;
@@ -186,23 +187,30 @@ function asFigure(node) {
       children: [{ type: "text", value: caption }],
     }]
     : [card];
+  // A known size decides the breakout now, so the figure does not jump when the image loads.
+  const size = imageSize(image.url);
+  const side = size ? figureLayout({ naturalWidth: size.width }).side : 0;
+  const hProperties = side > 0
+    ? { className: ["fig", "fig-wide"], style: `--wl:${side}px;--wr:${side}px` }
+    : { className: ["fig"] };
   return {
     type: "paragraph",
-    data: { hName: "figure", hProperties: { className: ["fig"] } },
+    data: { hName: "figure", hProperties },
     children: figureChildren,
   };
 }
 
-function walk(node) {
+function walk(node, imageSize) {
   if (!node || typeof node !== "object" || !Array.isArray(node.children)) return;
   if (node.type === "blockquote") rewriteAlert(node);
-  node.children = node.children.map((child) => asFigure(child) ?? child);
-  for (const child of node.children) walk(child);
+  node.children = node.children.map((child) => asFigure(child, imageSize) ?? child);
+  for (const child of node.children) walk(child, imageSize);
 }
 
 /** Demo alert cards and captioned figures. Article rendering only. */
-export function remarkA2() {
+export function remarkA2(options = {}) {
+  const imageSize = typeof options?.imageSize === "function" ? options.imageSize : () => null;
   return (tree) => {
-    walk(tree);
+    walk(tree, imageSize);
   };
 }

package/app/styles/a2.css

@@ -27,7 +27,6 @@ body {
   color: var(--ink);
 }
 
-.brand-mark,
 .brand small {
   display: none;
 }
@@ -244,7 +243,8 @@ body {
 .cover-card.cover-img,
 .article-hero.article-cover {
   width: 100%;
-  max-width: 880px;
+  /* Column plus half a gutter each side: centred, and clear of the TOC rail. */
+  max-width: calc(var(--col) + 72px);
   margin: 48px auto 0;
   aspect-ratio: auto;
   background: none;
@@ -730,6 +730,19 @@ html[data-theme="dark"] .markdown-body .markdown-alert code {
   }
 }
 
+/* A breakout decided at build time from the image's known size. It holds the
+   figure at its final width before the image loads and before the script
+   measures; the script then takes over (and removes .fig-wide). Only where the
+   article column is a full 740px with room on both sides. */
+@media (min-width: 1348px) {
+  .post-reading-page .markdown-body .fig-wide {
+    margin-left: calc(-1 * var(--wl, 0px));
+    margin-right: calc(-1 * var(--wr, 0px));
+    max-width: none;
+    width: auto;
+  }
+}
+
 .toc {
   font-size: var(--fs-small);
   line-height: 1.5;

package/app/styles/shell.css

@@ -37,21 +37,28 @@ img,svg{max-width:100%}
 .sh-header{position:sticky;top:0;z-index:40;background:var(--paper);border-bottom:1px solid transparent;transition:border-color .2s ease}
 .sh-header.is-scrolled{border-bottom-color:var(--rule)}
 .sh-bar{max-width:var(--shell);margin:0 auto;height:var(--hdr);padding:0 32px;display:flex;align-items:center;gap:28px}
-.sh-word{font:600 var(--fs-lead)/1 var(--serif);color:var(--ink);text-decoration:none;white-space:nowrap;padding:8px 0}
+.sh-word{display:inline-flex;align-items:center;gap:10px;font:600 var(--fs-lead)/1 var(--serif);color:var(--ink);text-decoration:none;white-space:nowrap;padding:8px 0}
+.sh-mark{display:inline-flex;flex:none}
+.sh-mark svg{display:block;height:26px;width:auto}
 .sh-nav{display:flex;gap:4px;margin-left:auto}
 .sh-nav a{font-size:15px;color:var(--soft);text-decoration:none;padding:8px 12px;border-radius:var(--r);transition:color .15s ease,background-color .15s ease}
 .sh-nav a:hover{color:var(--ink);background:var(--tint)}
 .sh-nav a[aria-current="page"],.sh-nav a[aria-current="true"]{color:var(--blue);font-weight:600}
 .sh-tools{display:flex;align-items:center;gap:8px}
-.sh-search{display:inline-flex;align-items:center;gap:10px;height:38px;padding:0 8px 0 12px;border:1px solid var(--rule);background:var(--card);color:var(--muted);border-radius:var(--r);font:400 var(--fs-small)/1 var(--sans);cursor:pointer;appearance:none;transition:border-color .15s ease,color .15s ease}
-.sh-search:hover{border-color:var(--rule-strong);color:var(--soft)}
+.sh-search{display:inline-flex;align-items:center;gap:6px;height:38px;padding:8px 12px;border:0;background:transparent;color:var(--soft);border-radius:var(--r);font:400 15px/1 var(--sans);cursor:pointer;appearance:none;transition:color .15s ease,background-color .15s ease}
+.sh-search:hover{color:var(--ink);background:var(--tint)}
+.sh-search:focus-visible{outline:2px solid var(--blue);outline-offset:2px}
 .sh-search svg,.sh-icon svg{width:18px;height:18px;fill:none;stroke:currentColor;stroke-width:1.7;stroke-linecap:round;stroke-linejoin:round;flex:none}
-.sh-search .lbl{min-width:84px;text-align:left}
+.sh-search svg{width:16px;height:16px}
+.sh-search .lbl{text-align:left}
+/* The shortcut hint only where there is a keyboard and a precise pointer. */
+.sh-search kbd{display:none;margin-left:4px;border:0;padding:0;background:none;font:400 12px/1 var(--sans);color:var(--muted);opacity:.7}
+@media (hover:hover) and (pointer:fine){.sh-search kbd{display:inline}}
 kbd{font:500 12px/1 var(--sans);color:var(--muted);border:1px solid var(--rule);border-bottom-width:2px;border-radius:6px;padding:3px 6px;background:var(--paper)}
-.sh-search .kbd-mod{display:inline-block;min-width:2.5em;text-align:end}
+.sh-search .kbd-mod{display:inline}
 .sh-search .kbd-other{display:none}
 html[data-mod="other"] .sh-search .kbd-mac{display:none}
-html[data-mod="other"] .sh-search .kbd-other{display:inline-block}
+html[data-mod="other"] .sh-search .kbd-other{display:inline}
 .sh-search-m{color:var(--soft);opacity:1}
 .sh-search-m svg{opacity:1}
 .sh-icon{display:inline-grid;place-items:center;width:40px;height:40px;border:0;background:transparent;color:var(--soft);border-radius:var(--r);cursor:pointer;transition:background-color .15s ease,color .15s ease}

package/bin/garden.mjs

@@ -77,7 +77,7 @@ function ensureLink(from, to) {
 function ensurePublic() {
   const dest = path.join(siteRoot, "public");
   fs.mkdirSync(dest, { recursive: true });
-  for (const name of ["favicon.svg", "og.png"]) {
+  for (const name of ["favicon.svg", "apple-touch-icon.png", "og.png"]) {
     const from = path.join(gardenPackageRoot, "public", name);
     const to = path.join(dest, name);
     if (fs.existsSync(from) && !fs.existsSync(to)) fs.copyFileSync(from, to);
@@ -355,6 +355,7 @@ function help() {
   garden new              创建文章草稿
   garden embed            拉取外链摘要
   garden links            重新拉取外链图标（build 时会自动做）
+  garden images           读取新的远程图片尺寸，写入 image-sizes.json（build 时会自动做）
   garden init [目录]      创建只含稿和配置的新站点
   garden check <文章.md>  检查一篇博文的硬性结构
   garden ui <子命令>      Intelligent UI：scan、check、apply、prompt、schema、catalog
@@ -382,11 +383,18 @@ switch (command) {
   case "build":
     // Favicons are refetched on every build; failures fall back to link-assets.json.
     if (process.env.GARDEN_OFFLINE !== "1") runNode("scripts/link-assets.mjs");
+    // Remote image sizes: only new images are probed; the rest come from image-sizes.json.
+    if (process.env.GARDEN_OFFLINE !== "1") runNode("scripts/image-sizes.mjs");
     runVinext(["build", ...rest], { copyDist: true });
+    // Pages for old addresses listed under redirects in site.config.yaml (static export only).
+    if (process.env.STATIC_EXPORT === "1") runNode("scripts/redirects.mjs");
     break;
   case "links":
     runNode("scripts/link-assets.mjs");
     break;
+  case "images":
+    runNode("scripts/image-sizes.mjs");
+    break;
   case "start":
     runVinext(["start", ...rest]);
     break;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hd-garden",
-  "version": "0.5.2",
+  "version": "0.5.3",
   "private": false,
   "description": "用 Markdown 写作、用 GitHub Pages 发布的个人博客引擎。",
   "license": "MIT",
@@ -27,6 +27,7 @@
     "bin",
     "build",
     "public/favicon.svg",
+    "public/apple-touch-icon.png",
     "public/og.png",
     "public/images",
     "scripts",
@@ -81,6 +82,7 @@
     "fuse.js": "^7.5.0",
     "github-slugger": "^2.0.0",
     "gray-matter": "^4.0.3",
+    "image-size": "^2.0.4",
     "katex": "^0.16.47",
     "marked": "^16.4.2",
     "mdast-util-from-markdown": "^2.1.0",

package/public/favicon.svg

@@ -1,4 +1 @@
-<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 256 256">
-  <rect width="256" height="256" fill="#f8f8f6"/>
-  <path fill="#202124" d="M216,208H168V184h4a68.07,68.07,0,0,0,68-68,28,28,0,0,0-56,0,12,12,0,0,1-12,12h-4V56a40,40,0,0,0-80,0V88H84A12,12,0,0,1,72,76a28,28,0,0,0-56,0,68.07,68.07,0,0,0,68,68h4v64H40a8,8,0,0,0,0,16H216a8,8,0,0,0,0-16ZM96,128H84A52.06,52.06,0,0,1,32,76a12,12,0,0,1,24,0,28,28,0,0,0,28,28H96a8,8,0,0,0,8-8V56a24,24,0,0,1,48,0v80a8,8,0,0,0,8,8h12a28,28,0,0,0,28-28,12,12,0,0,1,24,0,52.06,52.06,0,0,1-52,52H160a8,8,0,0,0-8,8v32H104V136A8,8,0,0,0,96,128Z"/>
-</svg>
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="1.5 1.25 28 28" fill="none" stroke="#1B1A18" stroke-width="2.75" stroke-linecap="round" stroke-linejoin="round"><style>@media (prefers-color-scheme: dark){svg{stroke:#EEECE7}}</style><path d="M10 27V10"/><path d="M10 10C10 5.5 13.5 3.5 18 3.5C18 7.5 15 10 10 10Z"/><path d="M10 19C10 15.5 12.5 13.5 15.5 13.5S21 15.5 21 19V27"/></svg>

package/scripts/brand.mjs

@@ -0,0 +1,59 @@
+/**
+ * The site's logo and icons, from `brand` in site.config.yaml:
+ *
+ *   brand:
+ *     logo: brand/logo.svg          # SVG file in the site, shown before the name; false hides it
+ *     favicon: /favicon.svg         # URL under public/
+ *     appleTouchIcon: /apple-touch-icon.png
+ *
+ * The logo is inlined so it follows the text colour: draw it with
+ * `stroke="currentColor"` or `fill="currentColor"`.
+ */
+import fs from "node:fs";
+import path from "node:path";
+
+// Garden's own mark: a leaf on an h, cropped to its strokes.
+export const DEFAULT_LOGO = '<svg xmlns="http://www.w3.org/2000/svg" viewBox="6 2 18 27" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M10 27V10"/><path d="M10 10C10 5.5 13.5 3.5 18 3.5C18 7.5 15 10 10 10Z"/><path d="M10 19C10 15.5 12.5 13.5 15.5 13.5S21 15.5 21 19V27"/></svg>';
+
+/** Keep only the `<svg>` element, without scripts, event handlers or external references. */
+export function cleanSvg(markup) {
+  const match = String(markup ?? "").match(/<svg\b[\s\S]*<\/svg>/iu);
+  if (!match) return "";
+  return match[0]
+    .replace(/<!--[\s\S]*?-->/gu, "")
+    .replace(/<(script|foreignObject)\b[\s\S]*?<\/\1>/giu, "")
+    .replace(/\s+on[a-z]+\s*=\s*("[^"]*"|'[^']*'|[^\s>]+)/giu, "")
+    .replace(/\s+(?:xlink:)?href\s*=\s*("[^"#][^"]*"|'[^'#][^']*')/giu, "")
+    // The header sets the size; the file's own width and height would fight it.
+    .replace(/^<svg\b([^>]*)>/iu, (whole, attrs) => `<svg${attrs.replace(/\s(width|height)\s*=\s*("[^"]*"|'[^']*')/giu, "")} aria-hidden="true" focusable="false">`)
+    .replace(/\s*\n\s*/gu, "");
+}
+
+const publicUrl = (value, basePath) => {
+  const url = String(value);
+  if (/^(https?:)?\/\//iu.test(url) || url.startsWith("data:")) return url;
+  return `${basePath}${url.startsWith("/") ? url : `/${url}`}`;
+};
+
+export function resolveBrand(siteRoot, config = {}, basePath = "", warn = () => {}) {
+  const brand = config?.brand ?? {};
+  let logo = "";
+  if (brand.logo !== false && brand.logo !== "none") {
+    let markup = DEFAULT_LOGO;
+    if (typeof brand.logo === "string" && brand.logo.trim()) {
+      const resolved = path.resolve(siteRoot, brand.logo.replace(/^\//u, ""));
+      if (!resolved.startsWith(path.resolve(siteRoot) + path.sep) || !fs.existsSync(resolved)) {
+        warn(`brand.logo 找不到文件 ${brand.logo}，使用默认图标。`);
+      } else {
+        markup = fs.readFileSync(resolved, "utf8");
+      }
+    }
+    logo = cleanSvg(markup);
+    if (!logo) warn(`brand.logo 不是 SVG：${brand.logo}，不显示图标。`);
+  }
+  return {
+    logo,
+    favicon: publicUrl(brand.favicon || "/favicon.svg", basePath),
+    appleTouchIcon: brand.appleTouchIcon === false ? "" : publicUrl(brand.appleTouchIcon || "/apple-touch-icon.png", basePath),
+  };
+}

package/scripts/build-content.mjs

@@ -11,6 +11,8 @@ import { referenceDomain } from "../ui/garden/references.mjs";
 import { linkAssetsForRender } from "./link-assets.mjs";
 import { cardUrls } from "../ui/garden/markdown-links.mjs";
 import { configuredSiteAddress, sameSiteMatcher } from "../ui/garden/same-site.mjs";
+import { resolveBrand } from "./brand.mjs";
+import { imageSources, readImageCache, sizeFromBytes } from "./image-sizes.mjs";
 import { buildFullIndex, buildSearchIndex } from "../ui/garden/search-index.mjs";
 import { coverImageSet, loadSharp } from "./cover-images.mjs";
 
@@ -531,6 +533,40 @@ const thoughts = readMarkdownTree(path.join(contentRoot, "thoughts"), "thought")
   (a, b) => Date.parse(b.date) - Date.parse(a.date),
 );
 
+// Intrinsic image sizes for width/height on <img>: local files are read now,
+// remote ones come from image-sizes.json (written by scripts/image-sizes.mjs).
+function localImageFile(src) {
+  const clean = src.split(/[?#]/u, 1)[0];
+  const copied = assetFiles.get(clean)?.destination;
+  if (copied) return copied;
+  if (!clean.startsWith("/") || clean.startsWith("//")) return null;
+  let pathname;
+  try {
+    pathname = decodeURIComponent(basePath && clean.startsWith(`${basePath}/`) ? clean.slice(basePath.length) : clean);
+  } catch {
+    return null;
+  }
+  const publicDir = path.join(root, "public");
+  const file = path.resolve(publicDir, `.${pathname}`);
+  return file.startsWith(publicDir + path.sep) && fs.existsSync(file) && fs.statSync(file).isFile() ? file : null;
+}
+const remoteImageSizes = readImageCache(root).images;
+const imageSizes = {};
+for (const entry of [...posts, ...columns, ...thoughts]) {
+  for (const src of imageSources(entry.content)) {
+    if (imageSizes[src]) continue;
+    if (/^https?:\/\//iu.test(src)) {
+      const size = remoteImageSizes[src];
+      if (size?.width > 0 && size?.height > 0) imageSizes[src] = { width: size.width, height: size.height };
+      continue;
+    }
+    const file = localImageFile(src);
+    const size = file ? sizeFromBytes(fs.readFileSync(file)) : null;
+    if (size) imageSizes[src] = size;
+    else if (file) console.warn(`警告：读不到图片尺寸，这张图不带宽高：${src}`);
+  }
+}
+
 assertUnique(posts, (item) => item.path, "博文路径");
 assertUnique(columns, (item) => `${item.column}/${item.path}`, "专栏路径");
 assertUnique(
@@ -620,6 +656,7 @@ export const columns = ${JSON.stringify(columns, null, 2)} as ContentEntry[];
 export const thoughts = ${JSON.stringify(thoughts, null, 2)} as ContentEntry[];
 export const a2WordCounts = ${JSON.stringify(a2WordCounts, null, 2)} as Record<string, number>;
 export const linkAssets = ${JSON.stringify(linkAssetsForRender(root, basePath), null, 2)} as LinkAssets;
+export const imageSizes: Record<string, { width: number; height: number }> = ${JSON.stringify(imageSizes)};
 `;
 
 fs.mkdirSync(path.dirname(output), { recursive: true });
@@ -634,6 +671,8 @@ export const githubUrl = ${JSON.stringify(`https://github.com/${siteConfig.autho
 export const searchIndexUrl = ${JSON.stringify(`${basePath}/search-index.json?v=${contentHash}`)};
 // Every body as plain text, fetched in the background after load; the name changes with the text.
 export const searchFull = ${JSON.stringify({ url: `${basePath}/${fullIndex.fileName}`, hash: fullIndex.hash })};
+// Header logo (inlined SVG) and icon URLs, from brand in site.config.yaml.
+export const brand = ${JSON.stringify(resolveBrand(root, siteConfig, basePath, (line) => console.warn(line)))};
 // Full URLs to this address render as internal links.
 export const siteLinks = ${JSON.stringify({ address: siteAddress, basePath })};
 `,

package/scripts/image-sizes.mjs

@@ -0,0 +1,206 @@
+#!/usr/bin/env node
+/**
+ * Intrinsic sizes of the images in post bodies, so every <img> can carry
+ * width and height and the page does not jump as lazy images load.
+ *
+ * - Local images are read at build time with image-size (see build-content).
+ * - Remote images are probed here: only the first bytes are downloaded, never
+ *   the whole file. Results go into `image-sizes.json` (commit it), so later
+ *   builds do not fetch them again. A failed probe is logged and retried next
+ *   time; the image simply renders without a size. The build never fails.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import matter from "gray-matter";
+import { imageSize } from "image-size";
+import { isPublicUrl } from "./link-meta-core.mjs";
+import { assertPublicDns, pool } from "./link-assets.mjs";
+import { mapOutsideCode } from "../ui/garden/markdown-links.mjs";
+
+export const CACHE_FILE = "image-sizes.json";
+const HEAD_BYTES = [64 * 1024, 512 * 1024];
+const TIMEOUT_MS = 8000;
+
+// A destination may hold balanced parentheses, as in `image (9).png` written as `image%20(9).png`.
+const MD_IMAGE = /!\[[^\]]*\]\(\s*(?:<([^>\n]+)>|((?:[^()\s]|\([^()\s]*\))+))(?:\s+(?:"[^"]*"|'[^']*'))?\s*\)/gu;
+const HTML_IMAGE = /<img\b[^>]*?\bsrc\s*=\s*["']([^"']+)["']/giu;
+
+/** Image sources written in a Markdown body, outside code, in order, without repeats. */
+export function imageSources(markdown) {
+  const found = [];
+  mapOutsideCode(markdown, (text) => {
+    for (const match of text.matchAll(MD_IMAGE)) found.push(match[1] ?? match[2]);
+    for (const match of text.matchAll(HTML_IMAGE)) found.push(match[1]);
+    return text;
+  });
+  return [...new Set(found)];
+}
+
+const svgLength = (value) => {
+  const match = /^\s*([\d.]+)\s*(px)?\s*$/iu.exec(value ?? "");
+  return match ? Number(match[1]) : 0;
+};
+
+/**
+ * An SVG's size from its opening tag, even when the tag is cut off: drawing
+ * tools can put a huge attribute (draw.io's `content`) inside it.
+ */
+export function svgSizeFromHead(text) {
+  const tag = /<svg\b[^>]*/iu.exec(text)?.[0];
+  if (!tag) return null;
+  const attr = (name) => new RegExp(`\\s${name}\\s*=\\s*["']([^"']*)["']`, "iu").exec(tag)?.[1];
+  const width = svgLength(attr("width"));
+  const height = svgLength(attr("height"));
+  if (width > 0 && height > 0) return { width: Math.round(width), height: Math.round(height) };
+  const box = (attr("viewBox") ?? "").trim().split(/[\s,]+/u).map(Number);
+  if (box.length === 4 && box[2] > 0 && box[3] > 0) {
+    if (width > 0) return { width: Math.round(width), height: Math.round((width * box[3]) / box[2]) };
+    return { width: Math.round(box[2]), height: Math.round(box[3]) };
+  }
+  return null;
+}
+
+/** `{ width, height }` from the first bytes of an image, or null. */
+export function sizeFromBytes(bytes) {
+  const head = new TextDecoder().decode(bytes.subarray(0, 4096));
+  if (/^\s*(?:<\?xml[^>]*>\s*)?(?:<!--[\s\S]*?-->\s*)*(?:<!DOCTYPE[^>]*>\s*)?<svg\b/iu.test(head)) return svgSizeFromHead(head);
+  try {
+    const result = imageSize(bytes);
+    // EXIF orientation 5–8 turns the picture a quarter: the browser swaps the sides.
+    const turned = result.orientation >= 5 && result.orientation <= 8;
+    const width = turned ? result.height : result.width;
+    const height = turned ? result.width : result.height;
+    return width > 0 && height > 0 ? { width, height } : null;
+  } catch {
+    return null;
+  }
+}
+
+export function readImageCache(siteRoot) {
+  try {
+    const data = JSON.parse(fs.readFileSync(path.join(siteRoot, CACHE_FILE), "utf8"));
+    return { images: data?.images && typeof data.images === "object" ? data.images : {} };
+  } catch {
+    return { images: {} };
+  }
+}
+
+/** Read at most `limit` bytes of the response body, then stop the download. */
+async function readHead(response, limit) {
+  if (!response.body) return new Uint8Array(await response.arrayBuffer()).slice(0, limit);
+  const reader = response.body.getReader();
+  const chunks = [];
+  let total = 0;
+  try {
+    while (total < limit) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      chunks.push(value);
+      total += value.length;
+    }
+  } finally {
+    await reader.cancel().catch(() => {});
+  }
+  const bytes = new Uint8Array(Math.min(total, limit));
+  let offset = 0;
+  for (const chunk of chunks) {
+    const part = chunk.subarray(0, Math.min(chunk.length, bytes.length - offset));
+    bytes.set(part, offset);
+    offset += part.length;
+    if (offset >= bytes.length) break;
+  }
+  return bytes;
+}
+
+/** Fetch the head of an image, following up to 3 redirects to public hosts only. */
+async function fetchHead(url, limit, fetcher, checkHost) {
+  let current = url;
+  for (let hop = 0; hop < 4; hop += 1) {
+    if (!isPublicUrl(current)) throw new Error("not a public URL");
+    await checkHost(new URL(current).hostname);
+    const response = await fetcher(current, {
+      redirect: "manual",
+      headers: { range: `bytes=0-${limit - 1}`, accept: "image/*", "user-agent": "Mozilla/5.0 (compatible; GardenImageSize/1.0)" },
+      signal: AbortSignal.timeout(TIMEOUT_MS),
+    });
+    if (response.status >= 300 && response.status < 400 && response.headers.get("location")) {
+      await response.body?.cancel().catch(() => {});
+      current = new URL(response.headers.get("location"), current).toString();
+      continue;
+    }
+    if (!response.ok) {
+      await response.body?.cancel().catch(() => {});
+      throw new Error(`HTTP ${response.status}`);
+    }
+    return readHead(response, limit);
+  }
+  throw new Error("too many redirects");
+}
+
+export async function probeRemoteSize(url, { fetch: fetcher = globalThis.fetch, checkHost = assertPublicDns } = {}) {
+  let lastError = "unreadable";
+  for (const limit of HEAD_BYTES) {
+    try {
+      const size = sizeFromBytes(await fetchHead(url, limit, fetcher, checkHost));
+      if (size) return size;
+    } catch (error) {
+      lastError = error?.message ?? String(error);
+      break;
+    }
+  }
+  throw new Error(lastError);
+}
+
+function markdownFiles(directory) {
+  if (!fs.existsSync(directory)) return [];
+  return fs.readdirSync(directory, { withFileTypes: true }).flatMap((entry) => {
+    const full = path.join(directory, entry.name);
+    if (entry.isDirectory()) return markdownFiles(full);
+    return /\.mdx?$/iu.test(entry.name) ? [full] : [];
+  });
+}
+
+/** Remote image URLs across every Markdown file under content/. */
+export function collectRemoteImages(siteRoot) {
+  const urls = new Set();
+  for (const file of markdownFiles(path.join(siteRoot, "content"))) {
+    const { content } = matter(fs.readFileSync(file, "utf8"));
+    for (const src of imageSources(content)) if (/^https?:\/\//iu.test(src)) urls.add(src);
+  }
+  return [...urls].sort();
+}
+
+export async function refreshImageSizes({ siteRoot, fetch: fetcher, checkHost, log = () => {}, concurrency = 6 }) {
+  const cache = readImageCache(siteRoot);
+  const urls = collectRemoteImages(siteRoot);
+  const images = {};
+  const missing = [];
+  for (const url of urls) {
+    if (cache.images[url]?.width > 0 && cache.images[url]?.height > 0) images[url] = cache.images[url];
+    else missing.push(url);
+  }
+  let failed = 0;
+  await pool(missing, concurrency, async (url) => {
+    try {
+      images[url] = await probeRemoteSize(url, { fetch: fetcher, checkHost });
+    } catch (error) {
+      failed += 1;
+      log(`警告：读不到图片尺寸，这张图不带宽高：${url}（${error.message}）`);
+    }
+  });
+  const sorted = Object.fromEntries(Object.keys(images).sort().map((url) => [url, images[url]]));
+  const next = `${JSON.stringify({ version: 1, images: sorted }, null, 2)}\n`;
+  const file = path.join(siteRoot, CACHE_FILE);
+  const previous = fs.existsSync(file) ? fs.readFileSync(file, "utf8") : "";
+  if (next !== previous && (urls.length || previous)) fs.writeFileSync(file, next);
+  log(`图片尺寸：${urls.length} 张远程图片，新读取 ${missing.length - failed} 张，失败 ${failed} 张。`);
+  return { images: sorted, probed: missing.length - failed, failed };
+}
+
+if (import.meta.url === pathToFileURL(process.argv[1] ?? "").href) {
+  const siteRoot = process.env.GARDEN_SITE ? path.resolve(process.env.GARDEN_SITE) : process.cwd();
+  await refreshImageSizes({ siteRoot, log: (line) => process.stdout.write(`${line}\n`) }).catch((error) => {
+    process.stdout.write(`警告：图片尺寸没有更新（${error.message}），继续构建。\n`);
+  });
+}

package/scripts/link-assets.mjs

@@ -94,14 +94,14 @@ export async function assertPublicDns(hostname) {
   }
 }
 
-function guardedFetch(fetcher) {
+export function guardedFetch(fetcher) {
   return async (url, init) => {
     await assertPublicDns(new URL(url).hostname);
     return fetcher(url, init);
   };
 }
 
-async function pool(items, size, worker) {
+export async function pool(items, size, worker) {
   const queue = [...items];
   const runners = Array.from({ length: Math.min(size, queue.length) }, async () => {
     while (queue.length) await worker(queue.shift());

package/scripts/redirects.mjs

@@ -0,0 +1,128 @@
+#!/usr/bin/env node
+/**
+ * Pages for old addresses. `redirects` in site.config.yaml maps an old path to
+ * where the page lives now:
+ *
+ *   redirects:
+ *     /2024/01/20/go/go-gpm/: /blog/go/go-gpm/
+ *
+ * A static export (GitHub Pages and the like) has no server to answer with a
+ * 301, so each old path gets a small page that sends the reader on: a meta
+ * refresh, a script that keeps the #anchor, and rel="canonical" for search
+ * engines. Runs after the build, into dist/client.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import { parse as parseYaml } from "yaml";
+import { configuredSiteAddress } from "../ui/garden/same-site.mjs";
+
+const escapeHtml = (value) => String(value).replace(/&/gu, "&amp;").replace(/"/gu, "&quot;").replace(/</gu, "&lt;").replace(/>/gu, "&gt;");
+
+/** Valid `{ from, to }` pairs from the config; anything malformed is reported and skipped. */
+export function readRedirects(config = {}, warn = () => {}) {
+  const map = config?.redirects;
+  if (!map) return [];
+  if (typeof map !== "object" || Array.isArray(map)) {
+    warn("redirects 应写成「旧路径: 新地址」的映射，已忽略。");
+    return [];
+  }
+  const pairs = [];
+  for (const [rawFrom, rawTo] of Object.entries(map)) {
+    let from = String(rawFrom).trim();
+    const to = String(rawTo ?? "").trim();
+    try {
+      from = decodeURI(from);
+    } catch {
+      // keep as written
+    }
+    if (!from.startsWith("/") || from.startsWith("//") || from === "/" || /(^|\/)\.\.?(\/|$)/u.test(from) || /[?#]/u.test(from)) {
+      warn(`redirects：旧路径 ${rawFrom} 必须是站内路径（以 / 开头，不带 ?、# 和 ..），已跳过。`);
+      continue;
+    }
+    if (!(to.startsWith("/") && !to.startsWith("//")) && !/^https?:\/\//iu.test(to)) {
+      warn(`redirects：${rawFrom} 的新地址 ${rawTo} 应以 / 开头或是完整网址，已跳过。`);
+      continue;
+    }
+    pairs.push({ from, to });
+  }
+  return pairs;
+}
+
+/** The file an old path is served from: `/a/b/` and `/a/b` → a/b/index.html, `/a/b.html` → a/b.html. */
+export function redirectFile(from) {
+  const clean = from.replace(/^\/+/u, "");
+  return /\.html?$/iu.test(clean) ? clean : path.posix.join(clean.replace(/\/+$/u, ""), "index.html");
+}
+
+export function redirectPage({ href, canonical }) {
+  return `<!doctype html>
+<html lang="zh-CN">
+<head>
+<meta charset="utf-8">
+<title>页面已移动</title>
+<link rel="canonical" href="${escapeHtml(canonical)}">
+<meta http-equiv="refresh" content="0; url=${escapeHtml(href)}">
+<script>location.replace(${JSON.stringify(href).replace(/</gu, "\\u003c")} + location.hash)</script>
+</head>
+<body>
+<p>页面已移到 <a href="${escapeHtml(href)}">${escapeHtml(canonical)}</a>。</p>
+</body>
+</html>
+`;
+}
+
+/**
+ * Write one page per redirect into `outDir`. A redirect is skipped, with a
+ * warning, when a real page already lives at the old path or when a site path
+ * it points to was not built. Never throws for a bad entry.
+ */
+export function writeRedirects({ outDir, config = {}, env = {}, basePath = "", log = () => {} }) {
+  const base = String(basePath ?? "").replace(/\/+$/u, "");
+  let origin = "";
+  try {
+    const address = configuredSiteAddress(config, env);
+    origin = address ? new URL(address).origin : "";
+  } catch {
+    origin = "";
+  }
+  const written = [];
+  for (const { from, to } of readRedirects(config, log)) {
+    const file = path.join(outDir, redirectFile(from));
+    if (!path.resolve(file).startsWith(path.resolve(outDir) + path.sep)) continue;
+    if (fs.existsSync(file)) {
+      log(`redirects：${from} 已经有页面，没有覆盖。`);
+      continue;
+    }
+    const external = /^https?:\/\//iu.test(to);
+    if (!external) {
+      const target = to.split(/[?#]/u, 1)[0];
+      const built = [path.join(outDir, redirectFile(target)), path.join(outDir, target.replace(/^\/+/u, ""))]
+        .some((candidate) => fs.existsSync(candidate) && fs.statSync(candidate).isFile());
+      if (!built) {
+        log(`redirects：${from} 指向的 ${to} 不存在，已跳过。`);
+        continue;
+      }
+    }
+    const href = external ? to : `${base}${to}`;
+    const canonical = external || !origin ? href : `${origin}${href}`;
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, redirectPage({ href, canonical }));
+    written.push({ from, to: href, file });
+  }
+  return written;
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  const siteRoot = process.env.GARDEN_SITE ? path.resolve(process.env.GARDEN_SITE) : process.cwd();
+  const outDir = path.join(siteRoot, "dist", "client");
+  try {
+    const config = parseYaml(fs.readFileSync(path.join(siteRoot, "site.config.yaml"), "utf8")) ?? {};
+    if (config.redirects && fs.existsSync(outDir)) {
+      const written = writeRedirects({ outDir, config, env: process.env, basePath: process.env.NEXT_PUBLIC_BASE_PATH ?? "", log: (line) => process.stdout.write(`警告：${line}\n`) });
+      process.stdout.write(`旧地址跳转页：${written.length} 个。\n`);
+    }
+  } catch (error) {
+    process.stdout.write(`警告：旧地址跳转页没有生成（${error.message}），继续构建。\n`);
+  }
+}

package/templates/site/site.config.yaml

@@ -4,6 +4,11 @@ description: 文章、随想和专栏。
 locale: zh_CN
 # 站点的公开地址。文章里指向这个地址的完整网址会按站内链接显示。
 # url: https://blog.example.com
+# 站点图标，不写时使用 Garden 自带的图标。
+# brand:
+#   logo: brand/logo.svg
+#   favicon: /favicon.svg
+#   appleTouchIcon: /apple-touch-icon.png
 
 author:
   name: Your Name

package/ui/garden/enhance.mjs

@@ -131,6 +131,36 @@ export function figureBreakout({
   return { left: side, right: side };
 }
 
+/**
+ * The same decision made at build time, when the image's pixel size is known:
+ * a figure in a full-width article column (`column` wide, the image card
+ * `inset` narrower) with room to spare on both sides. Returns how far the
+ * figure steps out on each side (`side`, 0 when it stays in the column) and
+ * the inline width the image gets, so its box is the right size before the
+ * file loads. The browser repeats the calculation after hydration and keeps
+ * it as the fallback for images without a known size.
+ */
+export function figureLayout({ naturalWidth = 0, attrWidth = 0, column = 740, inset = 26, density = 2, maxWidth = 1040 }) {
+  if (!(naturalWidth > 0)) return { side: 0, width: attrWidth > 0 ? attrWidth : 0 };
+  // Before any widening the image shows at its own pixels (or its width attribute), capped at the card.
+  const base = attrWidth > 0 ? Math.min(attrWidth, naturalWidth) : naturalWidth;
+  const viewport = 100000;
+  const articleLeft = (viewport - column) / 2;
+  const { left } = figureBreakout({
+    viewport,
+    articleLeft,
+    articleRight: articleLeft + column,
+    figureClient: column,
+    imageClient: Math.min(base, column - inset),
+    naturalWidth,
+    attrWidth,
+    density,
+    maxWidth,
+  });
+  const widened = figureImageWidth({ naturalWidth, attrWidth, widened: left > 0, density });
+  return { side: left, width: widened || base };
+}
+
 /**
  * Slide the TOC right of a wide element measured against the TOC's original
  * position. Hide it when the shifted TOC would not fit on screen.

package/ui/garden/image-dims.mjs

@@ -0,0 +1,43 @@
+import { figureLayout } from "./enhance.mjs";
+
+const decode = (value) => {
+  try {
+    return decodeURI(value);
+  } catch {
+    return value;
+  }
+};
+
+/** The build-time size for an image src, whether or not the renderer percent-encoded it. */
+export function lookupImageSize(sizes, src) {
+  if (!src || !sizes) return null;
+  const size = sizes[src] ?? sizes[decode(src)] ?? sizes[encodeURI(decode(src))];
+  return size?.width > 0 && size?.height > 0 ? size : null;
+}
+
+/**
+ * Attributes that give an article image its box before the file loads:
+ * width and height (the browser takes the aspect ratio from them; CSS keeps
+ * height:auto so it stays responsive) and an inline width matching what the
+ * image would show once loaded. An author-written width wins and only gains
+ * the matching height. Without a known size nothing is added.
+ */
+export function imageDimensions({ width, height } = {}, size) {
+  if (!size) return {};
+  const authoredWidth = Number(width) > 0 ? Number(width) : 0;
+  const authoredHeight = Number(height) > 0 ? Number(height) : 0;
+  // Author-written sizes are never replaced; only the missing side is filled in from the ratio.
+  if (authoredWidth || authoredHeight) {
+    const w = authoredWidth || Math.round((authoredHeight * size.width) / size.height);
+    const h = authoredHeight || Math.round((authoredWidth * size.height) / size.width);
+    return { width: w, height: h, "data-nw": size.width, "data-aw": w };
+  }
+  const { width: shown } = figureLayout({ naturalWidth: size.width });
+  return {
+    width: size.width,
+    height: size.height,
+    "data-nw": size.width,
+    "data-bw": shown,
+    style: { width: `${shown}px` },
+  };
+}