@hagicode/hagilight-starlight 0.14.1-dev.144.1.bcc5ef8 → 0.14.1-dev.149.1.1dadf5c

package/ArticlePromotion.astro

@@ -3,18 +3,29 @@ import { Picture } from 'astro:assets';
 import { gaEventAttributes } from '@hagicode/hagilight-core/analytics-events';
 import { resolveSiteLinks } from '@hagicode/hagilight-core/links';
 import { getArticlePromotionCopy } from './dist/article-promotion.js';
+import { randomPoolAttribute, randomPoolFromManifest } from '@hagicode/hagilight-core/random-image';
 import {
   resolveMicrosoftStoreBadgeLanguage,
   resolveMicrosoftStoreProductId,
 } from './dist/windows-download.js';
+import catHead from './assets/showcase/cat-head.webp';
 import heroes from './assets/showcase/heroes.webp';
 import pillarEfficient from './assets/showcase/pillar-efficient.svg';
 import pillarFun from './assets/showcase/pillar-fun.svg';
 import pillarSmart from './assets/showcase/pillar-smart.svg';
 import proposalWorkflow from './assets/showcase/proposal-workflow.webp';
 import workbench from './assets/showcase/workbench.webp';
+import showcaseManifest from './assets/showcase/manifest.json';
+import ArticlePromotionPicker from './ArticlePromotionPicker.astro';
 
-const { lang } = Astro.props;
+interface Props {
+  lang?: string;
+  /** Swap the illustration for one random pool entry per page view. Defaults to `true`. */
+  randomAvatar?: boolean;
+}
+
+const { lang, randomAvatar = true } = Astro.props;
+if (typeof randomAvatar !== 'boolean') throw new TypeError('Hagilight hagicodePromotion randomAvatar option must be a boolean.');
 const copy = getArticlePromotionCopy(lang);
 const siteLinks = resolveSiteLinks(lang);
 const linkHref = (id: string, fallback: string) =>
@@ -33,7 +44,12 @@ const galleryImages: Record<string, ImageMetadata> = {
   workbench,
   'proposal-workflow': proposalWorkflow,
   heroes,
+  'cat-head': catHead,
 };
+// The illustration slot is the only gallery image that may change; its pool lives in the showcase manifest.
+const ILLUSTRATION_ID = 'cat-head';
+const avatarEntry = showcaseManifest.assets.find(({ id }) => id === ILLUSTRATION_ID);
+const avatarPool = randomAvatar && avatarEntry && 'pool' in avatarEntry ? randomPoolFromManifest(avatarEntry.pool) : undefined;
 const pillarIcons: Record<string, ImageMetadata> = {
   smart: pillarSmart,
   efficient: pillarEfficient,
@@ -90,7 +106,7 @@ const gallery = copy.gallery.flatMap((item) => {
     <ul class="hagilight-article-promotion__gallery" aria-labelledby="hagilight-article-promotion-gallery-title">
       {gallery.map((item) => (
         <li>
-          <figure>
+          <figure data-random-pool={item.id === ILLUSTRATION_ID && avatarPool ? randomPoolAttribute(avatarPool) : undefined}>
             <Picture
               src={item.image}
               alt={item.alt}
@@ -111,6 +127,8 @@ const gallery = copy.gallery.flatMap((item) => {
     </ul>
   </div>
 
+  {avatarPool && <ArticlePromotionPicker />}
+
   <div class="hagilight-article-promotion__closing">
     <div class="hagilight-article-promotion__windows">
       <h3 id="hagilight-article-promotion-windows-title" class="hagilight-article-promotion__windows-label">{copy.windowsLabel}</h3>
@@ -419,6 +437,11 @@ const gallery = copy.gallery.flatMap((item) => {
     line-height: 1.5;
   }
 
+  /* The illustration is a small square with its caption beside it, so it reads as an avatar, not a screenshot. */
+  .hagilight-article-promotion__gallery li:nth-child(4) picture {
+    max-width: 12rem;
+  }
+
   /* Closing: a full-bleed band, the heaviest surface, so "get it" is where the eye lands last. */
   .hagilight-article-promotion__closing {
     display: grid;
@@ -519,6 +542,15 @@ const gallery = copy.gallery.flatMap((item) => {
       grid-template-columns: repeat(2, minmax(0, 1fr));
       gap: 2rem;
     }
+
+    .hagilight-article-promotion__gallery li:nth-child(4) {
+      grid-column: 1 / -1;
+    }
+
+    .hagilight-article-promotion__gallery li:nth-child(4) figure {
+      grid-template-columns: minmax(0, 12rem) minmax(0, 1fr);
+      align-items: end;
+    }
   }
 
   /* Wide: the pitch takes the left column and the pillars stack beside it. */
@@ -575,6 +607,10 @@ const gallery = copy.gallery.flatMap((item) => {
       .hagilight-article-promotion__gallery li:nth-child(3) {
         animation-range: entry 19% entry 59%;
       }
+
+      .hagilight-article-promotion__gallery li:nth-child(4) {
+        animation-range: entry 26% entry 66%;
+      }
     }
   }
 

package/ArticlePromotionPicker.astro

@@ -0,0 +1,9 @@
+---
+// Rendered only when the showcase's random option is on, so a site that turns it off ships no picker script.
+---
+
+<script>
+  import { mountRandomImages } from '@hagicode/hagilight-core/random-image';
+
+  void mountRandomImages(document);
+</script>

package/Footer.astro

@@ -13,6 +13,8 @@ interface Props {
   rssFeedUrl?: string;
   rssLocaleFeedUrls?: Readonly<Record<string, string>>;
   buildInfo?: BuildInfo;
+  avatar?: boolean;
+  randomAvatar?: boolean;
 }
 
 const {
@@ -21,6 +23,8 @@ const {
   rssFeedUrl,
   rssLocaleFeedUrls,
   buildInfo,
+  avatar,
+  randomAvatar,
 } = Astro.props;
 const buildItems = buildInfoItems(buildInfo);
 if (typeof manifest.version !== 'string' || manifest.version.trim().length === 0) {
@@ -46,7 +50,7 @@ const resolvedLinks = resolveSiteLinks(currentLanguage ?? locale, {
 
 <DefaultFooter />
 <div class="hagilight-brand-host">
-  <FooterBrand locale={resolvedLinks.locale} links={resolvedLinks.quick} />
+  <FooterBrand locale={resolvedLinks.locale} links={resolvedLinks.quick} avatar={avatar} randomAvatar={randomAvatar} />
 </div>
 <div class="hagilight-site-links">
   {resolvedLinks.relatedSites.length > 0 && (

package/MarkdownContent.astro

@@ -13,6 +13,7 @@ import { resolveArticlePromotion } from './dist/article-promotion.js';
 const {
   aiDisclosures = { isAITranslation: false, isAIAuthor: false, sourceLocale: 'root' },
   hagicodePromotionEnabled = true,
+  hagicodePromotionRandomAvatar = true,
 } = Astro.props;
 const route = Astro.locals.starlightRoute;
 const isDocsEntry = route.entry.id !== '404' && !route.entry.id.endsWith('/404');
@@ -41,4 +42,4 @@ if (showTranslation) {
 {flags.isAIAuthor && <AIDisclosureNotice kind="author" lang={route.lang} />}
 <DefaultMarkdownContent><slot /></DefaultMarkdownContent>
 {showTranslation && <AIDisclosureNotice kind="translation" lang={route.lang} sourceHref={sourceHref} />}
-{showHagicodePromotion && <ArticlePromotion lang={route.lang} />}
+{showHagicodePromotion && <ArticlePromotion lang={route.lang} randomAvatar={hagicodePromotionRandomAvatar} />}

package/README.md

@@ -105,7 +105,7 @@ hagilight({ contentImages: { enabled: false } })
 
 ### HagiCode showcase
 
-After the body (and any translation notice) of every documentation article, the plugin renders a static HagiCode showcase: a headline, lead, and tagline with calls to action to the website and the documentation, three pillars (Smart, Efficient, Fun), a three-image gallery with captions, and a closing row with the Windows download button beside a selectable, copy-ready share sentence. The layout follows the showcase's own width: one column when narrow, a three-up pillar row, a gallery mosaic, and a two-column closing row from 36rem, and the pillars beside the pitch from 56rem (for example in the wide content mode). All text is localized for the ten published locales (`en-US`, `zh-CN`, `zh-Hant`, `ja-JP`, `ko-KR`, `de-DE`, `fr-FR`, `es-ES`, `pt-BR`, `ru-RU`) and falls back to English for any other language. Links come from the same locale-aware catalog as the footer.
+After the body (and any translation notice) of every documentation article, the plugin renders a static HagiCode showcase: a headline, lead, and tagline with calls to action to the website and the documentation, three pillars (Smart, Efficient, Fun), a gallery with captions (three audited screenshots and one cat-head illustration), and a closing row with the Windows download button beside a selectable, copy-ready share sentence. The layout follows the showcase's own width: one column when narrow, a three-up pillar row, a gallery mosaic, and a two-column closing row from 36rem, and the pillars beside the pitch from 56rem (for example in the wide content mode). All text is localized for the ten published locales (`en-US`, `zh-CN`, `zh-Hant`, `ja-JP`, `ko-KR`, `de-DE`, `fr-FR`, `es-ES`, `pt-BR`, `ru-RU`) and falls back to English for any other language. Links come from the same locale-aware catalog as the footer.
 
 Turn it off for the whole site, or override it per article:
 
@@ -143,7 +143,7 @@ This is the only script the showcase loads: `https://get.microsoft.com/badge/ms-
 
 #### Assets and image traffic
 
-The gallery images and pillar icons live in `assets/showcase/`, with a provenance record in `assets/showcase/manifest.json`. Each entry states its kind (`sourced` from the HagiCode web app or documentation, a hand-authored `svg`, or a `generated` illustration), its source path or generation record (tool, prompt, parameters, date), the crop and conversion applied, its size, and the audit verdict. Nothing is fetched from the product sites at build or read time.
+The gallery images and pillar icons live in `assets/showcase/`. The illustration `cat-head.webp` is the R2 object `cat-head-gallery/g067-pixar-style-3d-02.avif` (1024 px) upscaled to the 1200 px minimum; its manifest entry records the source and this transform, with a provenance record in `assets/showcase/manifest.json`. Each entry states its kind (`sourced` from the HagiCode web app or documentation, a hand-authored `svg`, or a `generated` illustration), its source path or generation record (tool, prompt, parameters, date), the crop and conversion applied, its size, and the audit verdict. Nothing is fetched from the product sites at build or read time.
 
 Every asset passes the same audit before it is committed: the current `HagiCode` brand, no Steam or other retired-channel content, no third-party promotion, no credentials, private repository names, or personal data, and rasters at least 1200 px wide. A removable offending region may be cropped out, and the crop is recorded. Pick images in this order to keep traffic low: an audited existing image converted to WebP, then a hand-authored SVG, then a newly generated raster only when neither fits. Generated art is an illustration, never a replica of the product UI, contains no text or logos, is captioned as an illustration, is reviewed by a person, and records its prompt and parameters (never credentials). Generation is an authoring step; the package never calls a generator.
 
@@ -166,7 +166,9 @@ To check a deployed site, run `curl -sI https://<site>/_astro/<file>.avif` with
 The copy and assets mirror `repos/web` and `repos/docs` in the HagiCode monorepo, which this package never edits.
 
 - **Copy:** edit `src/article-promotion-copy/<locale>.ts` (every locale must keep the same fields, feature ids, and gallery ids). Terminology is pinned in `GLOSSARY` in `src/article-promotion-copy/index.ts`, seeded from the product locale files in `repos/web/src/locales/<locale>/`. `HagiCode`, `OpenSpec`, `Hero Scenario`, `Microsoft Store`, and `Windows` are never translated.
-- **Images:** audit the candidate, crop and convert it to WebP (the AVIF and JPEG tiers are derived at build time, so an opaque image needs no extra file), add or update its `manifest.json` entry, register it in the `galleryImages` map in `ArticlePromotion.astro`, and add a caption and text alternative in every locale. The gallery mosaic places the first, second, and third catalog entries as the left top, left bottom, and right tall slot, so keep the gallery at three images or revisit the placement in the component's `@container (min-width: 36rem)` block. `npm test` checks that the manifest, the files, the component registry, and the copy agree.
+- **Images:** audit the candidate, crop and convert it to WebP (the AVIF and JPEG tiers are derived at build time, so an opaque image needs no extra file), add or update its `manifest.json` entry, register it in the `galleryImages` map in `ArticlePromotion.astro`, and add a caption and text alternative in every locale. The gallery mosaic places the first, second, and third catalog entries as the left top, left bottom, and right tall slot, so keep the three screenshots first. The illustration is the fourth entry: from 36rem it takes a full-width row with a 12 rem square and its caption, and it is the only gallery image that may change. To add a screenshot, revisit the placement in the component's `@container (min-width: 36rem)` block. `npm test` checks that the manifest, the files, the component registry, and the copy agree.
+- **Random illustration (R2 pool):** the `cat-head` entry in `assets/showcase/manifest.json` carries `source` (`repo: img-gen`, `album`, `objectKey`), its audit, and `pool` (`album`, `maxBytes` 200 KiB, `entries` with `key` and `bytes`). `ArticlePromotion.astro` builds the pool attribute at build time and renders `ArticlePromotionPicker.astro` only when the option is on. Refresh: take keys from the `cat-head-gallery` album `index.json`, keep 12 to 200 unique keys each within `maxBytes`, audit them text-free and current, update `pool.entries`, and keep the footer pool in `repos/hagilight/packages/core/assets/footer/manifest.json` in step. To rebuild the WebP, resize the source to 1200 px (lanczos3) and encode at quality 88. `npm test` (`test/showcase-assets.test.mjs`) checks the entry, the pool, the byte caps and the budgets.
+- **Options:** `hagicodePromotion: { randomAvatar: false }` keeps the default illustration and loads no picker; `footer: { avatar: false }` removes the footer avatar, and `footer: { randomAvatar: false }` keeps its default. A site whose `img-src` policy blocks `https://img-gen.hagicode.com` keeps the defaults.
 - **Badge:** the product id is parsed from the Store URL and the badge language map lives in `src/windows-download.ts`. Re-check both against `repos/docs/src/components/MicrosoftStoreBadge.tsx` and the official site when the Store listing or the supported languages change.
 
 The plugin footer and direct `/Footer` and `/PromotoFooter` components append

package/assets/showcase/manifest.json

@@ -72,6 +72,237 @@
         "notes": "Current HagiCode UI, English panel text with two Chinese hero names. Hero portraits are the product's own art; no third-party brand, no private data, no Steam content in the kept region."
       }
     },
+    {
+      "id": "cat-head",
+      "kind": "sourced",
+      "file": "cat-head.webp",
+      "width": 1200,
+      "height": 1200,
+      "bytes": 80780,
+      "source": {
+        "repo": "img-gen",
+        "album": "cat-head-gallery",
+        "objectKey": "cat-head-gallery/g067-pixar-style-3d-02.avif",
+        "width": 1024,
+        "height": 1024,
+        "bytes": 31093
+      },
+      "transforms": [
+        "upscale 1024x1024 to 1200x1200 (lanczos3); the R2 source is 1024 px and the showcase minimum is 1200 px",
+        "webp quality 88"
+      ],
+      "audit": {
+        "verdict": "pass",
+        "checkedOn": "2026-10-22",
+        "notes": "Pixar-style 3D cat head, text-free, from cat-head-gallery (style pixar-style-3d). Captioned and labeled as an illustration, not a product screenshot. No visible text, third-party marks, real faces, retired channel or personal data seen. The pool is the same 50 keys as the footer pool; neither default is in it, so the illustration always changes when it swaps."
+      },
+      "pool": {
+        "album": "cat-head-gallery",
+        "maxBytes": 204800,
+        "entries": [
+          {
+            "key": "g002-ukiyo-e-01",
+            "bytes": 25795
+          },
+          {
+            "key": "g003-watercolor-wash-02",
+            "bytes": 30932
+          },
+          {
+            "key": "g004-pixel-art-03",
+            "bytes": 24154
+          },
+          {
+            "key": "g005-oil-impasto-06",
+            "bytes": 37209
+          },
+          {
+            "key": "g006-paper-cut-layers-07",
+            "bytes": 15837
+          },
+          {
+            "key": "g008-low-poly-07",
+            "bytes": 17251
+          },
+          {
+            "key": "g009-claymation-07",
+            "bytes": 16599
+          },
+          {
+            "key": "g010-neon-line-07",
+            "bytes": 21312
+          },
+          {
+            "key": "g016-bauhaus-geometry-06",
+            "bytes": 13663
+          },
+          {
+            "key": "g017-cyanotype-06",
+            "bytes": 18762
+          },
+          {
+            "key": "g020-origami-03",
+            "bytes": 26060
+          },
+          {
+            "key": "g022-blueprint-03",
+            "bytes": 23845
+          },
+          {
+            "key": "g023-chalk-pastel-10",
+            "bytes": 29427
+          },
+          {
+            "key": "g025-voxel-03",
+            "bytes": 8242
+          },
+          {
+            "key": "g031-illuminated-manuscript-04",
+            "bytes": 32530
+          },
+          {
+            "key": "g034-vaporwave-04",
+            "bytes": 36264
+          },
+          {
+            "key": "g035-synthwave-chrome-09",
+            "bytes": 18415
+          },
+          {
+            "key": "g038-frosted-glass-02",
+            "bytes": 28185
+          },
+          {
+            "key": "g039-needle-felt-09",
+            "bytes": 33696
+          },
+          {
+            "key": "g041-glossy-balloon-05",
+            "bytes": 14623
+          },
+          {
+            "key": "g042-blue-white-porcelain-05",
+            "bytes": 31257
+          },
+          {
+            "key": "g043-glazed-ceramic-06",
+            "bytes": 11086
+          },
+          {
+            "key": "g045-impressionist-08",
+            "bytes": 32479
+          },
+          {
+            "key": "g047-fauvist-09",
+            "bytes": 18358
+          },
+          {
+            "key": "g048-cubist-10",
+            "bytes": 31586
+          },
+          {
+            "key": "g051-naive-folk-art-07",
+            "bytes": 19613
+          },
+          {
+            "key": "g056-wax-print-fabric-07",
+            "bytes": 16978
+          },
+          {
+            "key": "g058-red-paper-cut-10",
+            "bytes": 20948
+          },
+          {
+            "key": "g060-kawaii-pastel-01",
+            "bytes": 12179
+          },
+          {
+            "key": "g061-retro-90s-anime-01",
+            "bytes": 29377
+          },
+          {
+            "key": "g062-shoujo-sparkle-08",
+            "bytes": 27048
+          },
+          {
+            "key": "g065-saturday-cartoon-09",
+            "bytes": 19421
+          },
+          {
+            "key": "g067-pixar-style-3d-03",
+            "bytes": 16925
+          },
+          {
+            "key": "g068-toon-shaded-3d-04",
+            "bytes": 14116
+          },
+          {
+            "key": "g069-ps1-lowpoly-06",
+            "bytes": 18227
+          },
+          {
+            "key": "g070-matte-clay-render-07",
+            "bytes": 12775
+          },
+          {
+            "key": "g071-y2k-chrome-08",
+            "bytes": 24059
+          },
+          {
+            "key": "g072-glossy-3d-icon-08",
+            "bytes": 13376
+          },
+          {
+            "key": "g073-marble-bust-08",
+            "bytes": 17446
+          },
+          {
+            "key": "g075-wood-carving-10",
+            "bytes": 38433
+          },
+          {
+            "key": "g076-carved-jade-10",
+            "bytes": 14512
+          },
+          {
+            "key": "g078-toy-brick-02",
+            "bytes": 11910
+          },
+          {
+            "key": "g079-designer-vinyl-toy-02",
+            "bytes": 10594
+          },
+          {
+            "key": "g081-patchwork-quilt-03",
+            "bytes": 25601
+          },
+          {
+            "key": "g083-warhol-silkscreen-04",
+            "bytes": 14747
+          },
+          {
+            "key": "g088-vintage-lithograph-02",
+            "bytes": 27832
+          },
+          {
+            "key": "g090-alcohol-marker-09",
+            "bytes": 34894
+          },
+          {
+            "key": "g091-painterly-concept-art-09",
+            "bytes": 18574
+          },
+          {
+            "key": "g092-gradient-minimal-09",
+            "bytes": 14823
+          },
+          {
+            "key": "g095-constellation-map-09",
+            "bytes": 25940
+          }
+        ]
+      }
+    },
     {
       "id": "pillar-smart",
       "kind": "svg",

package/dist/article-promotion-copy/de-DE.js

@@ -28,6 +28,11 @@ export default {
             caption: 'Hero Scenario: Helden erledigen die Arbeit, Sie behalten Fortschritt, Level und Geschichte im Blick.',
             alt: 'Bereich Hero Scenario von HagiCode namens Ember Keep mit drei laufenden Helden samt Level, Fortschritt und Geschichtstext.',
         },
+        {
+            id: 'cat-head',
+            caption: 'Illustration: ein Katzenkopf-Porträt aus dem HagiCode-Illustrationsset, das bei jedem Besuch wechselt.',
+            alt: 'Stilisierte Katzenkopf-Illustration aus dem HagiCode-Illustrationsset.',
+        },
     ],
     windowsLabel: 'Für Windows herunterladen',
     windowsStoreLabel: 'Im Microsoft Store erhalten',

package/dist/article-promotion-copy/en-US.js

@@ -28,6 +28,11 @@ export default {
             caption: 'Hero Scenario: heroes run the work while you follow progress, levels, and story.',
             alt: 'HagiCode Hero Scenario panel named Ember Keep, listing three running heroes with their level, progress, and story text.',
         },
+        {
+            id: 'cat-head',
+            caption: 'Illustration: a cat-head portrait from the HagiCode illustration set, one of many that change between visits.',
+            alt: 'Stylized cat-head illustration from the HagiCode illustration set.',
+        },
     ],
     windowsLabel: 'Download for Windows',
     windowsStoreLabel: 'Get it from Microsoft Store',

package/dist/article-promotion-copy/es-ES.js

@@ -28,6 +28,11 @@ export default {
             caption: 'Hero Scenario: los héroes sacan adelante el trabajo mientras sigues el progreso, los niveles y la historia.',
             alt: 'Panel Hero Scenario de HagiCode llamado Ember Keep, con tres héroes en ejecución y su nivel, progreso y texto de la historia.',
         },
+        {
+            id: 'cat-head',
+            caption: 'Ilustración: un retrato de cabeza de gato del conjunto de ilustraciones de HagiCode, que cambia en cada visita.',
+            alt: 'Ilustración estilizada de una cabeza de gato del conjunto de ilustraciones de HagiCode.',
+        },
     ],
     windowsLabel: 'Descargar para Windows',
     windowsStoreLabel: 'Obtenerlo en Microsoft Store',

package/dist/article-promotion-copy/fr-FR.js

@@ -28,6 +28,11 @@ export default {
             caption: 'Hero Scenario : les héros avancent le travail pendant que vous suivez progression, niveaux et récit.',
             alt: 'Panneau Hero Scenario de HagiCode nommé Ember Keep, listant trois héros en cours avec leur niveau, leur progression et le texte du récit.',
         },
+        {
+            id: 'cat-head',
+            caption: 'Illustration : un portrait de tête de chat tiré de l’ensemble d’illustrations HagiCode, qui change à chaque visite.',
+            alt: 'Illustration stylisée d’une tête de chat tirée de l’ensemble d’illustrations HagiCode.',
+        },
     ],
     windowsLabel: 'Télécharger pour Windows',
     windowsStoreLabel: 'Obtenir sur le Microsoft Store',

package/dist/article-promotion-copy/index.d.ts

@@ -8,6 +8,8 @@ export interface ShowcaseGlossaryEntry {
     workflow: string;
     /** Approved word for "documentation". */
     documentation: string;
+    /** Approved word for the decorative avatar caption ("illustration"). */
+    illustration: string;
     /** Approved labels for the Smart, Efficient, and Interesting pillars. */
     pillars: {
         smart: string;

package/dist/article-promotion-copy/index.js

@@ -17,16 +17,16 @@ import zhHant from './zh-Hant.js';
  * Internal to the catalog: it is not part of the package's public entry points.
  */
 export const GLOSSARY = {
-    'zh-CN': { agent: 'Agent', multiAgent: '多 Agent', workflow: '工作流', documentation: '文档', pillars: { smart: '智能', efficient: '高效', fun: '有趣' }, avoid: ['智能体', '代理'] },
-    'en-US': { agent: 'agent', multiAgent: 'multi-agent', workflow: 'workflow', documentation: 'documentation', pillars: { smart: 'Smart', efficient: 'Efficient', fun: 'Interesting' }, avoid: ['multiagent'] },
-    'zh-Hant': { agent: 'Agent', multiAgent: '多 Agent', workflow: '工作流程', documentation: '文件', pillars: { smart: '智慧', efficient: '高效', fun: '有趣' }, avoid: ['代理程式', '代理商', '智慧代理'] },
-    'ja-JP': { agent: 'エージェント', multiAgent: 'マルチエージェント', workflow: 'ワークフロー', documentation: 'ドキュメント', pillars: { smart: 'スマート', efficient: '効率的', fun: '興味深い' }, avoid: ['エージェンシー', 'ドキュメンテーション'] },
-    'ko-KR': { agent: '에이전트', multiAgent: '다중 에이전트', workflow: '워크플로', documentation: '문서', pillars: { smart: '스마트', efficient: '효율적', fun: '흥미로운' }, avoid: ['대리인', '멀티 에이전트'] },
-    'de-DE': { agent: 'Agent', multiAgent: 'Multi-Agent', workflow: 'Workflow', documentation: 'Dokumentation', pillars: { smart: 'Intelligent', efficient: 'Effizient', fun: 'Interessant' }, avoid: ['Multiagent', 'Arbeitsablauf'] },
-    'fr-FR': { agent: 'agent', multiAgent: 'multi-agent', workflow: 'workflow', documentation: 'documentation', pillars: { smart: 'Intelligent', efficient: 'Efficace', fun: 'Intéressant' }, avoid: ['multiagent', 'flux de travail'] },
-    'es-ES': { agent: 'agente', multiAgent: 'multiagente', workflow: 'flujos de trabajo', documentation: 'documentación', pillars: { smart: 'Inteligente', efficient: 'Eficiente', fun: 'Interesante' }, avoid: ['multi-agente', 'workflow'] },
-    'pt-BR': { agent: 'agente', multiAgent: 'multiagente', workflow: 'fluxos de trabalho', documentation: 'documentação', pillars: { smart: 'Inteligente', efficient: 'Eficiente', fun: 'Interessante' }, avoid: ['multi-agente', 'workflow'] },
-    'ru-RU': { agent: 'агент', multiAgent: 'мультиагент', workflow: 'рабочие процессы', documentation: 'документаци', pillars: { smart: 'Умный', efficient: 'Эффективный', fun: 'Интересный' }, avoid: ['мульти-агент'] },
+    'zh-CN': { agent: 'Agent', multiAgent: '多 Agent', workflow: '工作流', documentation: '文档', pillars: { smart: '智能', efficient: '高效', fun: '有趣' }, illustration: '插图', avoid: ['智能体', '代理'] },
+    'en-US': { agent: 'agent', multiAgent: 'multi-agent', workflow: 'workflow', documentation: 'documentation', pillars: { smart: 'Smart', efficient: 'Efficient', fun: 'Interesting' }, illustration: 'illustration', avoid: ['multiagent'] },
+    'zh-Hant': { agent: 'Agent', multiAgent: '多 Agent', workflow: '工作流程', documentation: '文件', pillars: { smart: '智慧', efficient: '高效', fun: '有趣' }, illustration: '插圖', avoid: ['代理程式', '代理商', '智慧代理'] },
+    'ja-JP': { agent: 'エージェント', multiAgent: 'マルチエージェント', workflow: 'ワークフロー', documentation: 'ドキュメント', pillars: { smart: 'スマート', efficient: '効率的', fun: '興味深い' }, illustration: 'イラスト', avoid: ['エージェンシー', 'ドキュメンテーション'] },
+    'ko-KR': { agent: '에이전트', multiAgent: '다중 에이전트', workflow: '워크플로', documentation: '문서', pillars: { smart: '스마트', efficient: '효율적', fun: '흥미로운' }, illustration: '일러스트', avoid: ['대리인', '멀티 에이전트'] },
+    'de-DE': { agent: 'Agent', multiAgent: 'Multi-Agent', workflow: 'Workflow', documentation: 'Dokumentation', pillars: { smart: 'Intelligent', efficient: 'Effizient', fun: 'Interessant' }, illustration: 'Illustration', avoid: ['Multiagent', 'Arbeitsablauf'] },
+    'fr-FR': { agent: 'agent', multiAgent: 'multi-agent', workflow: 'workflow', documentation: 'documentation', pillars: { smart: 'Intelligent', efficient: 'Efficace', fun: 'Intéressant' }, illustration: 'illustration', avoid: ['multiagent', 'flux de travail'] },
+    'es-ES': { agent: 'agente', multiAgent: 'multiagente', workflow: 'flujos de trabajo', documentation: 'documentación', pillars: { smart: 'Inteligente', efficient: 'Eficiente', fun: 'Interesante' }, illustration: 'ilustración', avoid: ['multi-agente', 'workflow'] },
+    'pt-BR': { agent: 'agente', multiAgent: 'multiagente', workflow: 'fluxos de trabalho', documentation: 'documentação', pillars: { smart: 'Inteligente', efficient: 'Eficiente', fun: 'Interessante' }, illustration: 'ilustração', avoid: ['multi-agente', 'workflow'] },
+    'ru-RU': { agent: 'агент', multiAgent: 'мультиагент', workflow: 'рабочие процессы', documentation: 'документаци', pillars: { smart: 'Умный', efficient: 'Эффективный', fun: 'Интересный' }, illustration: 'иллюстрация', avoid: ['мульти-агент'] },
 };
 function deepFreeze(value) {
     for (const child of Object.values(value)) {

package/dist/article-promotion-copy/ja-JP.js

@@ -28,6 +28,11 @@ export default {
             caption: 'Hero Scenario：ヒーローが作業を進め、進行状況・レベル・物語を見守れます。',
             alt: 'HagiCode の Hero Scenario パネル「Ember Keep」。実行中の 3 人のヒーローのレベル、進行状況、物語のテキストが並ぶ。',
         },
+        {
+            id: 'cat-head',
+            caption: 'イラスト：HagiCode のイラスト集にある猫の頭部の肖像。訪問するたびに入れ替わります。',
+            alt: 'HagiCode のイラスト集から。様式化された猫の頭部のイラストです。',
+        },
     ],
     windowsLabel: 'Windows 版をダウンロード',
     windowsStoreLabel: 'Microsoft Store で入手',

package/dist/article-promotion-copy/ko-KR.js

@@ -28,6 +28,11 @@ export default {
             caption: 'Hero Scenario: 영웅이 작업을 진행하고, 당신은 진행 상황과 레벨, 이야기를 지켜봅니다.',
             alt: 'Ember Keep이라는 이름의 HagiCode Hero Scenario 패널. 실행 중인 영웅 세 명의 레벨, 진행률, 이야기 문구가 표시됩니다.',
         },
+        {
+            id: 'cat-head',
+            caption: '일러스트: HagiCode 일러스트 세트의 고양이 머리 초상. 방문할 때마다 바뀝니다.',
+            alt: 'HagiCode 일러스트 세트의 양식화된 고양이 머리 일러스트.',
+        },
     ],
     windowsLabel: 'Windows용 다운로드',
     windowsStoreLabel: 'Microsoft Store에서 받기',

package/dist/article-promotion-copy/pt-BR.js

@@ -28,6 +28,11 @@ export default {
             caption: 'Hero Scenario: os heróis tocam o trabalho enquanto você acompanha progresso, níveis e história.',
             alt: 'Painel Hero Scenario do HagiCode chamado Ember Keep, com três heróis em execução e seu nível, progresso e texto da história.',
         },
+        {
+            id: 'cat-head',
+            caption: 'Ilustração: um retrato de cabeça de gato do conjunto de ilustrações do HagiCode, que muda a cada visita.',
+            alt: 'Ilustração estilizada de uma cabeça de gato do conjunto de ilustrações do HagiCode.',
+        },
     ],
     windowsLabel: 'Baixar para Windows',
     windowsStoreLabel: 'Obter na Microsoft Store',

package/dist/article-promotion-copy/ru-RU.js

@@ -28,6 +28,11 @@ export default {
             caption: 'Hero Scenario: герои ведут работу, а вы следите за прогрессом, уровнями и сюжетом.',
             alt: 'Панель Hero Scenario в HagiCode под названием Ember Keep: три работающих героя с уровнем, прогрессом и текстом сюжета.',
         },
+        {
+            id: 'cat-head',
+            caption: 'Иллюстрация: портрет головы кота из набора иллюстраций HagiCode, который меняется при каждом визите.',
+            alt: 'Стилизованная иллюстрация головы кота из набора иллюстраций HagiCode.',
+        },
     ],
     windowsLabel: 'Скачать для Windows',
     windowsStoreLabel: 'Получить в Microsoft Store',

package/dist/article-promotion-copy/zh-CN.js

@@ -28,6 +28,11 @@ export default {
             caption: 'Hero Scenario：英雄推进工作，你随时查看进度、等级与剧情。',
             alt: 'HagiCode Hero Scenario 面板截图，名为 Ember Keep，列出三位运行中的英雄及其等级、进度与剧情文字。',
         },
+        {
+            id: 'cat-head',
+            caption: '插图：HagiCode 插画集中的一幅猫头像，每次访问会换一幅。',
+            alt: '风格化的猫头插图，来自 HagiCode 插画集。',
+        },
     ],
     windowsLabel: '下载 Windows 版',
     windowsStoreLabel: '从 Microsoft Store 获取',

package/dist/article-promotion-copy/zh-Hant.js

@@ -28,6 +28,11 @@ export default {
             caption: 'Hero Scenario：英雄推進工作，你隨時查看進度、等級與劇情。',
             alt: 'HagiCode Hero Scenario 面板畫面，名為 Ember Keep，列出三位執行中的英雄及其等級、進度與劇情文字。',
         },
+        {
+            id: 'cat-head',
+            caption: '插圖：HagiCode 插畫集中的一幅貓頭像，每次造訪會換一幅。',
+            alt: '風格化的貓頭插圖，來自 HagiCode 插畫集。',
+        },
     ],
     windowsLabel: '下載 Windows 版',
     windowsStoreLabel: '從 Microsoft Store 取得',

package/dist/index.d.ts

@@ -6,6 +6,16 @@ import { type SeoOrganization } from './seo-utils.js';
 export interface HagilightToggleOptions {
     enabled?: boolean;
 }
+export interface HagilightPromotionOptions extends HagilightToggleOptions {
+    /** Swap the showcase illustration for one random pool entry per page view. Defaults to `true`. */
+    randomAvatar?: boolean;
+}
+export interface HagilightFooterOptions {
+    /** Show the decorative avatar in the footer brand block. Defaults to `true`. */
+    avatar?: boolean;
+    /** Swap the footer avatar for one random pool entry per page view. Defaults to `true`. */
+    randomAvatar?: boolean;
+}
 export interface HagilightGoogleAnalyticsOptions {
     /** Defaults to `true` when the provider options are omitted, otherwise to whether `measurementId` is set. */
     enabled?: boolean;
@@ -80,8 +90,10 @@ export interface HagilightStarlightOptions {
     aiDisclosures?: HagilightAIDisclosureOptions;
     /** Theme picker with three extra light/dark themes and a Forest first-visit default. */
     themes?: HagilightThemesOptions;
+    /** Footer brand block options: the decorative avatar and its random pool. */
+    footer?: HagilightFooterOptions;
     /** End-of-article HagiCode introduction. */
-    hagicodePromotion?: HagilightToggleOptions;
+    hagicodePromotion?: HagilightPromotionOptions;
     /** Floating promotion banner rendered after the footer. */
     promoto?: HagilightToggleOptions;
     /** Body-image baseline (`loading`, `decoding`, marker class) for Markdown and MDX. Defaults to enabled. */

package/dist/index.js

@@ -2,6 +2,7 @@ import { randomUUID } from 'node:crypto';
 import { fileURLToPath } from 'node:url';
 import { resolveFaviconHeadEntry } from '@hagicode/hagilight-core/favicon';
 import { resolveBuildInfo } from '@hagicode/hagilight-core/build-info-resolver';
+import { resolveFooterAvatarOptions } from '@hagicode/hagilight-core/footer-avatar';
 import { checkContentImageRegistration, registerContentImages } from '@hagicode/hagilight-core/content-images';
 import { DEFAULT_POSTHOG_API_KEY, POSTHOG_API_KEY_PATTERN } from '@hagicode/hagilight-core/posthog';
 import { resolveRssLocales } from '@hagicode/hagilight-core/rss';
@@ -105,6 +106,14 @@ function resolveHagicodePromotion(config) {
     }
     return config.enabled ?? true;
 }
+function resolveHagicodePromotionRandomAvatar(config) {
+    if (config === undefined || !isRecord(config))
+        return true;
+    if (config.randomAvatar !== undefined && typeof config.randomAvatar !== 'boolean') {
+        throw new TypeError('Hagilight hagicodePromotion randomAvatar option must be a boolean.');
+    }
+    return config.randomAvatar ?? true;
+}
 function getRssFeedUrl(config) {
     if (!Array.isArray(config.head))
         return undefined;
@@ -247,6 +256,8 @@ import options from '${optionsId}';
   rssFeedUrl={options.rssFeedUrl}
   rssLocaleFeedUrls={options.rssLocaleFeedUrls}
   buildInfo={options.buildInfo}
+  avatar={options.footerAvatar.avatar}
+  randomAvatar={options.footerAvatar.randomAvatar}
 />
 ${promotionRender}
 ${analyticsRender}
@@ -265,6 +276,7 @@ import options from '${optionsId}';
 <MarkdownContent
   aiDisclosures={options.aiDisclosures}
   hagicodePromotionEnabled={options.hagicodePromotionEnabled}
+  hagicodePromotionRandomAvatar={options.hagicodePromotionRandomAvatar}
 ><slot /></MarkdownContent>
 `;
     const headSource = `---
@@ -373,6 +385,12 @@ export default function hagilight(options = {}) {
     const markdownContentEnabled = optionalBoolean(contentComponents, 'markdownContent', 'contentComponents markdownContent') !== false;
     const aiDisclosures = resolveAIDisclosures(input.aiDisclosures);
     const hagicodePromotionEnabled = resolveHagicodePromotion(input.hagicodePromotion);
+    const hagicodePromotionRandomAvatar = resolveHagicodePromotionRandomAvatar(input.hagicodePromotion);
+    const footerOptions = optionalRecord(input.footer, 'footer');
+    const footerAvatar = resolveFooterAvatarOptions({
+        avatar: optionalBoolean(footerOptions, 'avatar', 'footer avatar'),
+        randomAvatar: optionalBoolean(footerOptions, 'randomAvatar', 'footer randomAvatar'),
+    });
     const googleAnalyticsMeasurementId = resolveProvider(analytics.googleAnalytics, {
         name: 'Google Analytics',
         idKey: 'measurementId',
@@ -418,6 +436,8 @@ export default function hagilight(options = {}) {
     const serializedOptions = {
         promotoEnabled,
         hagicodePromotionEnabled,
+        hagicodePromotionRandomAvatar,
+        footerAvatar,
         links: options.links ?? {},
         googleAnalyticsMeasurementId,
         fiftyOneLaId,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hagicode/hagilight-starlight",
-  "version": "0.14.1-dev.144.1.bcc5ef8",
+  "version": "0.14.1-dev.149.1.1dadf5c",
   "type": "module",
   "description": "Starlight plugin and components for HagiCode documentation",
   "repository": {
@@ -53,7 +53,7 @@
     "assets/showcase/*"
   ],
   "dependencies": {
-    "@hagicode/hagilight-core": "0.14.1-dev.144.1.bcc5ef8"
+    "@hagicode/hagilight-core": "0.14.1-dev.149.1.1dadf5c"
   },
   "peerDependencies": {
     "@astrojs/starlight": "^0.42.4",