@hagicode/hagilight-core 0.9.1-dev.98.1.e071fc7 → 0.9.2-dev.102.1.daf22c1

package/Footer.astro

@@ -3,15 +3,18 @@ import Copyright from './Copyright.astro';
 import { siteLinkGaAttributes } from './dist/analytics-events.js';
 import { resolveSiteLinks, type SiteLinksOptions } from './dist/links.js';
 import { resolveRssFooterLinks } from './dist/rss-footer-context.js';
+import { buildInfoFromLocals, buildInfoItems, type BuildInfo } from './dist/build-info.js';
 
 interface Props {
   locale?: string;
   links?: SiteLinksOptions;
+  buildInfo?: BuildInfo;
 }
 
-const { locale: propLocale, links } = Astro.props;
+const { locale: propLocale, links, buildInfo: propBuildInfo } = Astro.props;
 const locale = propLocale ?? Astro.currentLocale ?? 'en-US';
 const footerLinks = resolveRssFooterLinks(Astro.locals, locale, links);
+const buildItems = buildInfoItems(propBuildInfo ?? buildInfoFromLocals(Astro.locals));
 const sitemapOverride = footerLinks.overrides?.sitemap;
 const resolvedLinks = resolveSiteLinks(locale, {
   ...footerLinks,
@@ -96,6 +99,17 @@ const resolvedLinks = resolveSiteLinks(locale, {
         <span class="hagilight-footer__attribution"><slot name="attribution" /></span>
       </>
     )}
+    {buildItems.map((item) => (
+      <>
+        {' | '}
+        <span
+          class="hagilight-footer__build"
+          data-build-field={item.field}
+          title={item.title}
+          data-build-commit={item.title}
+        >{item.label}: {item.datetime ? <time datetime={item.datetime}>{item.text}</time> : item.text}</span>
+      </>
+    ))}
   </p>
 </footer>
 
@@ -168,6 +182,10 @@ const resolvedLinks = resolveSiteLinks(locale, {
     overflow-wrap: anywhere;
   }
 
+  .hagilight-footer__build {
+    overflow-wrap: anywhere;
+  }
+
   @media (max-width: 40rem) {
     .hagilight-footer__sections {
       grid-template-columns: 1fr;

package/PromotoBanner.astro

@@ -98,7 +98,8 @@ const { fallback, locale = Astro.currentLocale ?? 'en' } = Astro.props;
     transition: opacity 0.24s ease, visibility 0s linear;
   }
 
-  .hagilight-promoto[data-state='footer-hidden'] .hagilight-promoto__shell {
+  .hagilight-promoto[data-state='footer-hidden'] .hagilight-promoto__shell,
+  .hagilight-promoto[data-state='top-hidden'] .hagilight-promoto__shell {
     opacity: 0;
     visibility: hidden;
     pointer-events: none;

package/README.md

@@ -35,6 +35,22 @@ import { resolveSiteLinks } from '@hagicode/hagilight-core/links';
 const links = resolveSiteLinks('en-US');
 ```
 
+## Build info
+
+`@hagicode/hagilight-core/build-info` is browser-safe. It exports the `BuildInfo` type, `normalizeBuildInfo`, `shortCommit`, and `buildInfoItems`, which turn a resolved value into the footer's Branch, Commit, and Built items. `@hagicode/hagilight-core/build-info-resolver` is Node-only: `resolveBuildInfo({ root, env, now })` reads the value for one project. Keep Node-only code out of any module that a browser bundle imports.
+
+Each field resolves on its own, in this order:
+
+| Field | Order | Fallback |
+| --- | --- | --- |
+| Branch | `HAGILIGHT_BUILD_BRANCH`, then `git symbolic-ref --short -q HEAD` | `unknown` |
+| Commit | `HAGILIGHT_BUILD_COMMIT`, then `git rev-parse HEAD` | `unknown` |
+| Built | `now`, in UTC, truncated to whole seconds | none; always set |
+
+After trimming, `HAGILIGHT_BUILD_BRANCH` must be nonblank and free of control characters. `HAGILIGHT_BUILD_COMMIT` must be 7 to 64 hexadecimal characters and is stored lowercased. An invalid explicit value falls through to Git. Git runs with a 5-second timeout and its stderr is discarded. A detached HEAD, an unborn branch, a missing `git`, a directory outside any repository, or a timeout yields `unknown` for that field only. The resolver never throws.
+
+The footer shows the commit as its first seven characters, with the full hash in the `title` attribute. The core `Footer` renders this line only when it receives a `buildInfo` prop or the `hagilight()` integration from `@hagicode/hagilight/integration` is registered; otherwise it renders no build text.
+
 ## Content images
 
 `@hagicode/hagilight-core/content-images` normalizes the `<img>` elements in Markdown and MDX body content at build time. A body image gets the marker class `hagilight-content-image`, `loading="lazy"`, and `decoding="async"`. Values the author already set are kept, existing classes are kept, and the marker is added once.
@@ -47,7 +63,7 @@ const links = resolveSiteLinks('en-US');
 
 Images inside a `<picture>` element are skipped. An MDX `class={expression}` gets no marker because its value is not known at build time. Raw HTML `<img>` tags inside a `.md` file are not normalized; use Markdown image syntax or MDX for body images.
 
-Local Markdown (`.md`) body images that Astro resolves are also wrapped in a `<picture>` element, with an AVIF `<source>` and a WebP `<source>` ahead of the `<img>`. Astro generates the source URLs through its image service, so AVIF needs a service that can encode it. The default sharp service does. The passthrough no-op service (`astro/assets/services/noop`) does not, so the Astro integrations skip the wrapper there and log one warning. A plugin added by hand does not check the service, and its sources then point at the original bytes. Site-root, remote, raw HTML, and MDX images are not wrapped. Encoding adds build time, which Astro caches. Each `<source>` also carries `src`, `loading`, `decoding`, `width`, and `height` copied from Astro's output. Browsers ignore these on `source`, but they are not valid HTML there.
+Local body images in `.md` and `.mdx` files that Astro resolves are also wrapped in a `<picture>` element, with an AVIF `<source>` and a WebP `<source>` ahead of the `<img>`. The rule is shared by both file types. An image is wrapped only when all of these hold: it is a relative path (`./` or `../`) that Astro collects as a local file; its extension is not `.svg` or `.gif`, ignoring case, query strings, and fragments; it does not resolve into the project's `public/` directory (`publicDir`), where it keeps its plain `<img>`; the step is enabled; and it is not already inside a `<picture>` or `Picture` the author wrote. A direct import of `rehypeContentImages` or `satteriContentImages` without registration has no `publicDir`, so it skips the `public/` check and wraps every other image that passes. In `.mdx`, the plugin imports Astro's `Picture` component from `astro:assets`, and the inner `<img>` carries the marker class, `loading`, and `decoding`. Site-root, remote, and raw HTML `<img>` images are not wrapped. Astro generates the source URLs through its image service, so AVIF needs a service that can encode it. The default sharp service does. The passthrough no-op service (`astro/assets/services/noop`) does not, so the Astro integrations skip the wrapper there and log one warning. A plugin added by hand does not check the service, and its sources then point at the original bytes. Encoding adds build time, which Astro caches. In `.md`, each `<source>` also carries `src`, `loading`, `decoding`, `width`, and `height` copied from Astro's output; in `.mdx`, `<source>` carries only `srcset` and `type`. Browsers ignore the extra attributes on `source`, but they are not valid HTML there.
 
 `hagilight()` from `@hagicode/hagilight-starlight` and `hagilight()` from `@hagicode/hagilight/integration` register the plugin automatically, for the whole site and regardless of integration order. Each one opts out through its `contentImages` option; see those packages' READMEs.
 
@@ -71,6 +87,8 @@ With the unified processor, pass `rehypeContentImages()` in `rehypePlugins` inst
 
 The shared banner (`PromotoBanner`, `loadActivePromotions`) displays only promotions whose `platforms` array in Index's `/promote.json` includes `web`, in addition to being enabled, inside their activation window, and matched with `/promote_content.json`. This follows the `platforms` flag documented in the Index README. An entry whose `platforms` is missing, empty, or not an array of strings is not displayed, other values such as `hagicode` are ignored, and matching is exact (`Web` does not match). When no promotion remains, the banner shows its site fallback or stays hidden, as before.
 
+The banner stays hidden while the page is at the top during a domain's first 30 visits, and while the Footer is in view. Every page load, refresh, and page-to-page navigation counts as a visit; scrolling and hash changes do not. The per-domain counter is stored in the visitor's browser under `hagilight:promoto-banner:visit-count:<hostname>` and is never sent anywhere.
+
 A promotion's `image` may also carry `sources`, the alternative image files that Index publishes in the order AVIF, WebP, then the original. The banner renders them as a `<picture>` in that order, with the original as its `<img>`, and skips any entry whose `type` is not an `image/*` media type or whose URL is unsafe. Each `src` is resolved against `https://index.hagicode.com` when the promotion documents load. If the browser fails to load a tier, the banner removes it and the next tier is used. A card without `sources` renders the plain `<img>` as before, and `sources` never affect the dismissal signature, so a dismissed banner stays dismissed when only its image chain changes.
 
 ## Google Analytics click events

package/dist/build-info-resolver.d.ts

@@ -0,0 +1,8 @@
+import { type BuildInfo } from './build-info.js';
+export interface ResolveBuildInfoOptions {
+    /** Site project root. Git runs here, so a site inside a larger repository still finds it. */
+    root: string;
+    env?: Readonly<Record<string, string | undefined>>;
+    now?: Date;
+}
+export declare function resolveBuildInfo({ root, env, now }: ResolveBuildInfoOptions): BuildInfo;

package/dist/build-info-resolver.js

@@ -0,0 +1,29 @@
+import { execFileSync } from 'node:child_process';
+import { normalizeBranch, normalizeCommit, UNKNOWN } from './build-info.js';
+const GIT_TIMEOUT_MS = 5000;
+function readGit(root, args) {
+    try {
+        return execFileSync('git', args, {
+            cwd: root,
+            encoding: 'utf8',
+            timeout: GIT_TIMEOUT_MS,
+            stdio: ['ignore', 'pipe', 'ignore'],
+            windowsHide: true,
+        });
+    }
+    catch {
+        return undefined;
+    }
+}
+function formatBuiltAt(now) {
+    return now.toISOString().replace(/\.\d{3}Z$/u, 'Z');
+}
+export function resolveBuildInfo({ root, env = process.env, now = new Date() }) {
+    const branch = normalizeBranch(env.HAGILIGHT_BUILD_BRANCH)
+        ?? normalizeBranch(readGit(root, ['symbolic-ref', '--short', '-q', 'HEAD']))
+        ?? UNKNOWN;
+    const commit = normalizeCommit(env.HAGILIGHT_BUILD_COMMIT)
+        ?? normalizeCommit(readGit(root, ['rev-parse', 'HEAD']))
+        ?? UNKNOWN;
+    return Object.freeze({ branch, commit, builtAt: formatBuiltAt(now) });
+}

package/dist/build-info.d.ts

@@ -0,0 +1,19 @@
+export declare const UNKNOWN = "unknown";
+export interface BuildInfo {
+    readonly branch: string;
+    readonly commit: string;
+    readonly builtAt: string;
+}
+export interface BuildInfoItem {
+    readonly field: 'branch' | 'commit' | 'builtAt';
+    readonly label: string;
+    readonly text: string;
+    readonly title?: string;
+    readonly datetime?: string;
+}
+export declare function normalizeBranch(value: unknown): string | undefined;
+export declare function normalizeCommit(value: unknown): string | undefined;
+export declare function normalizeBuildInfo(input: unknown): BuildInfo;
+export declare function shortCommit(commit: string): string;
+export declare function buildInfoFromLocals(locals: unknown): BuildInfo | undefined;
+export declare function buildInfoItems(info: BuildInfo | null | undefined): readonly BuildInfoItem[];

package/dist/build-info.js

@@ -0,0 +1,60 @@
+export const UNKNOWN = 'unknown';
+const CONTROL_CHARACTERS = /[\u0000-\u001f\u007f]/u;
+const COMMIT_PATTERN = /^[0-9a-f]{7,64}$/iu;
+const BUILT_AT_PATTERN = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}Z$/u;
+function isRecord(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+export function normalizeBranch(value) {
+    if (typeof value !== 'string')
+        return undefined;
+    const branch = value.trim();
+    return branch && !CONTROL_CHARACTERS.test(branch) ? branch : undefined;
+}
+export function normalizeCommit(value) {
+    if (typeof value !== 'string')
+        return undefined;
+    const commit = value.trim();
+    return COMMIT_PATTERN.test(commit) ? commit.toLowerCase() : undefined;
+}
+function normalizeBuiltAt(value) {
+    if (typeof value !== 'string' || !BUILT_AT_PATTERN.test(value))
+        return undefined;
+    return Number.isNaN(Date.parse(value)) ? undefined : value;
+}
+export function normalizeBuildInfo(input) {
+    const record = isRecord(input) ? input : {};
+    return Object.freeze({
+        branch: normalizeBranch(record.branch) ?? UNKNOWN,
+        commit: normalizeCommit(record.commit) ?? UNKNOWN,
+        builtAt: normalizeBuiltAt(record.builtAt) ?? UNKNOWN,
+    });
+}
+export function shortCommit(commit) {
+    return normalizeCommit(commit)?.slice(0, 7) ?? UNKNOWN;
+}
+export function buildInfoFromLocals(locals) {
+    if (!isRecord(locals) || locals.hagilightBuild === undefined)
+        return undefined;
+    return normalizeBuildInfo(locals.hagilightBuild);
+}
+export function buildInfoItems(info) {
+    if (info === undefined || info === null)
+        return [];
+    const { branch, commit, builtAt } = normalizeBuildInfo(info);
+    return [
+        { field: 'branch', label: 'Branch', text: branch },
+        {
+            field: 'commit',
+            label: 'Commit',
+            text: shortCommit(commit),
+            ...(commit === UNKNOWN ? {} : { title: commit }),
+        },
+        {
+            field: 'builtAt',
+            label: 'Built',
+            text: builtAt,
+            ...(builtAt === UNKNOWN ? {} : { datetime: builtAt }),
+        },
+    ];
+}

package/dist/content-images.d.ts

@@ -36,18 +36,35 @@ export interface ContentImageNode {
     properties?: Record<string, unknown>;
     attributes?: MdxAttributeLike[];
     children?: ContentImageNode[];
+    /** Source text of an `mdxjsEsm` node. */
+    value?: string;
+    /** ESTree data of an `mdxjsEsm` node, read by the unified MDX compiler. */
+    data?: unknown;
+}
+/** Per-document state for MDX picture output on the Sätteri processor. */
+export interface MdxPictureScope {
+    /** Decoded `src` to the identifier its asset import binds. */
+    assets: Map<string, string>;
+    /** Whether the `Picture` component import has been queued for this document. */
+    component: boolean;
+    /** Import nodes not yet placed in the document. */
+    pending: ContentImageNode[];
 }
 export interface LocalImageData {
     astro?: {
         localImagePaths?: Set<string> | readonly string[];
     };
+    /** Sätteri's per-document MDX picture state, created on first use. */
+    hagilightContentPicture?: MdxPictureScope;
 }
 export interface SatteriContentImageContext {
     readonly sourceFormat: string;
+    readonly fileURL?: URL | undefined;
     readonly data: LocalImageData;
     parent(node: unknown): unknown;
     setProperty(node: unknown, key: string, value: unknown): void;
     replaceNode(node: unknown, newNode: ContentImageNode): void;
+    prependChild(node: unknown, childNode: ContentImageNode | ContentImageNode[]): void;
 }
 export interface SatteriContentImageVisitor {
     filter: string[];
@@ -61,6 +78,8 @@ export interface SatteriContentImagePlugin {
 }
 export interface PictureStep {
     enabled: boolean;
+    /** Filesystem path of the project's `publicDir`. Images that resolve into it keep their markup. */
+    publicDir?: string;
 }
 export interface ContentImageRegistrationInput {
     config: {
@@ -72,6 +91,7 @@ export interface ContentImageRegistrationInput {
                 entrypoint?: unknown;
             };
         };
+        publicDir?: unknown;
     };
     logger: {
         warn(message: string): void;

package/dist/content-images.js

@@ -1,3 +1,5 @@
+import { dirname, isAbsolute, relative, resolve, sep } from 'node:path';
+import { fileURLToPath } from 'node:url';
 export const CONTENT_IMAGE_CLASS = 'hagilight-content-image';
 function isRecord(value) {
     return value !== null && typeof value === 'object' && !Array.isArray(value);
@@ -70,7 +72,7 @@ function isMdxJsx(node) {
 }
 function isPicture(node) {
     return (node.type === 'element' && node.tagName === 'picture')
-        || (isMdxJsx(node) && node.name === 'picture');
+        || (isMdxJsx(node) && (node.name === 'picture' || node.name === 'Picture'));
 }
 function upsertMdxAttribute(attributes, name, value) {
     const existing = attributes.find((attribute) => attribute.name === name);
@@ -109,19 +111,20 @@ function applyUnifiedTree(node, options, inPicture) {
     for (const child of node.children ?? [])
         applyUnifiedTree(child, options, childrenInPicture);
 }
-function wrapUnifiedPictures(node, inPicture, srcOf, nextIndex) {
+/** Replaces each `img` outside a picture for which `replace` returns a node. */
+function replaceUnifiedImages(node, inPicture, replace) {
     const children = node.children;
     if (!children)
         return;
     children.forEach((child, index) => {
         if (!inPicture && child.type === 'element' && child.tagName === 'img') {
-            const src = srcOf(child);
-            if (src !== undefined) {
-                children[index] = pictureElement(child, src, nextIndex());
+            const replacement = replace(child);
+            if (replacement !== undefined) {
+                children[index] = replacement;
                 return;
             }
         }
-        wrapUnifiedPictures(child, inPicture || isPicture(child), srcOf, nextIndex);
+        replaceUnifiedImages(child, inPicture || isPicture(child), replace);
     });
 }
 /** Unified rehype plugin for sites whose `markdown.processor` is `unified()`. */
@@ -130,10 +133,28 @@ export function rehypeContentImages(options = {}, picture = { enabled: true }) {
     let pictureCount = 0;
     return (tree, file) => {
         applyUnifiedTree(tree, resolved, false);
-        if (!picture.enabled || !String(file?.path ?? '').endsWith('.md'))
+        const format = documentFormat(file?.path);
+        if (!picture.enabled || format === undefined)
             return;
         const astro = file?.data?.astro;
-        wrapUnifiedPictures(tree, false, (img) => localImageSrc(img.properties?.src, astro), () => ++pictureCount);
+        const documentPath = toFilePath(file?.path);
+        const eligibleSrc = (img) => pictureSource(img.properties?.src, astro, picture, documentPath);
+        if (format === 'markdown') {
+            replaceUnifiedImages(tree, false, (img) => {
+                const src = eligibleSrc(img);
+                return src === undefined ? undefined : pictureElement(img, src, ++pictureCount);
+            });
+            return;
+        }
+        const scope = newMdxPictureScope();
+        replaceUnifiedImages(tree, false, (img) => {
+            const src = eligibleSrc(img);
+            if (src === undefined)
+                return undefined;
+            return pictureComponent(pictureProperties(img.properties ?? {}, resolved), assetIdentifier(scope, src, 'estree'), 'estree');
+        });
+        if (scope.pending.length > 0)
+            tree.children?.unshift(...scope.pending);
     };
 }
 function isInsidePicture(node, ctx) {
@@ -144,7 +165,12 @@ function isInsidePicture(node, ctx) {
     return false;
 }
 const PICTURE_FORMATS = ['avif', 'webp'];
+const PICTURE_FALLBACK_FORMAT = 'webp';
+const PICTURE_COMPONENT = 'HagilightContentPicture';
+const PICTURE_COMPONENT_SOURCE = 'astro:assets';
 const NOOP_IMAGE_SERVICE = 'astro/assets/services/noop';
+/** Extensions the picture step leaves alone: SVG is already vector, and a GIF would lose its animation. */
+const VECTOR_OR_ANIMATED = /\.(?:svg|gif)$/iu;
 function localImageSrc(value, astro) {
     const localPaths = astro?.localImagePaths;
     if (typeof value !== 'string' || localPaths === undefined)
@@ -153,6 +179,59 @@ function localImageSrc(value, astro) {
     const isLocal = localPaths instanceof Set ? localPaths.has(src) : localPaths.includes(src);
     return isLocal ? src : undefined;
 }
+/** A file URL or absolute path as a filesystem path; `undefined` for anything else. */
+function toFilePath(value) {
+    const text = value instanceof URL ? value.href : value;
+    if (typeof text !== 'string')
+        return undefined;
+    if (text.startsWith('file:'))
+        return fileURLToPath(text);
+    return isAbsolute(text) ? text : undefined;
+}
+function documentFormat(filePath) {
+    const text = String(filePath ?? '');
+    if (text.endsWith('.mdx'))
+        return 'mdx';
+    if (text.endsWith('.md'))
+        return 'markdown';
+    return undefined;
+}
+function withoutQueryOrFragment(src) {
+    return src.replace(/[?#].*$/u, '');
+}
+/**
+ * The file a relative reference names, resolved against the document's directory.
+ * Site-root, bare and aliased specifiers, and a missing document location, resolve to `undefined`.
+ */
+function resolveLocalFile(src, documentPath) {
+    if (documentPath === undefined)
+        return undefined;
+    const file = withoutQueryOrFragment(src);
+    if (!file.startsWith('./') && !file.startsWith('../'))
+        return undefined;
+    return resolve(dirname(documentPath), file);
+}
+function isInsideDirectory(directory, file) {
+    const offset = relative(directory, file);
+    return offset !== '..' && !offset.startsWith(`..${sep}`) && !isAbsolute(offset);
+}
+/**
+ * The decoded `src` when the picture step may wrap this image, otherwise `undefined`. One rule for
+ * `.md` and `.mdx`: collected by Astro as local, not SVG or GIF, not inside `publicDir`, step enabled.
+ * Without a document location or a `publicDir`, the `public/` check is skipped.
+ */
+function pictureSource(value, astro, picture, documentPath) {
+    if (!picture.enabled)
+        return undefined;
+    const src = localImageSrc(value, astro);
+    if (src === undefined || VECTOR_OR_ANIMATED.test(withoutQueryOrFragment(src)))
+        return undefined;
+    const file = resolveLocalFile(src, documentPath);
+    if (picture.publicDir !== undefined && file !== undefined && isInsideDirectory(picture.publicDir, file)) {
+        return undefined;
+    }
+    return src;
+}
 function pictureElement(img, src, index) {
     const sources = PICTURE_FORMATS.map((format) => ({
         type: 'element',
@@ -170,6 +249,106 @@ function pictureElement(img, src, index) {
     }));
     return { type: 'element', tagName: 'picture', properties: {}, children: [...sources, img] };
 }
+function estreeProgram(body) {
+    return { type: 'Program', sourceType: 'module', comments: [], body };
+}
+function jsxAttributeNode(attribute, flavor) {
+    if ('text' in attribute)
+        return { type: 'mdxJsxAttribute', name: attribute.name, value: attribute.text };
+    const expression = 'identifier' in attribute ? attribute.identifier : JSON.stringify(attribute.list);
+    const value = { type: 'mdxJsxAttributeValueExpression', value: expression };
+    if (flavor === 'estree') {
+        const node = 'identifier' in attribute
+            ? { type: 'Identifier', name: attribute.identifier }
+            : {
+                type: 'ArrayExpression',
+                elements: attribute.list.map((item) => ({ type: 'Literal', value: item, raw: JSON.stringify(item) })),
+            };
+        value.data = { estree: estreeProgram([{ type: 'ExpressionStatement', expression: node }]) };
+    }
+    return { type: 'mdxJsxAttribute', name: attribute.name, value };
+}
+function importNode(flavor, text, declaration) {
+    if (flavor === 'source')
+        return { type: 'mdxjsEsm', value: text };
+    return { type: 'mdxjsEsm', value: '', data: { estree: estreeProgram([declaration]) } };
+}
+function newMdxPictureScope() {
+    return { assets: new Map(), component: false, pending: [] };
+}
+/** The identifier an asset import binds for `src`, queuing the imports the first time each is needed. */
+function assetIdentifier(scope, src, flavor) {
+    const existing = scope.assets.get(src);
+    if (existing !== undefined)
+        return existing;
+    const name = `HagilightContentImage${scope.assets.size}`;
+    if (!scope.component) {
+        scope.component = true;
+        scope.pending.push(importNode(flavor, `import { Picture as ${PICTURE_COMPONENT} } from "${PICTURE_COMPONENT_SOURCE}";`, {
+            type: 'ImportDeclaration',
+            attributes: [],
+            source: { type: 'Literal', value: PICTURE_COMPONENT_SOURCE, raw: JSON.stringify(PICTURE_COMPONENT_SOURCE) },
+            specifiers: [{
+                    type: 'ImportSpecifier',
+                    imported: { type: 'Identifier', name: 'Picture' },
+                    local: { type: 'Identifier', name: PICTURE_COMPONENT },
+                }],
+        }));
+    }
+    scope.pending.push(importNode(flavor, `import ${name} from ${JSON.stringify(src)};`, {
+        type: 'ImportDeclaration',
+        attributes: [],
+        source: { type: 'Literal', value: src, raw: JSON.stringify(src) },
+        specifiers: [{ type: 'ImportDefaultSpecifier', local: { type: 'Identifier', name } }],
+    }));
+    scope.assets.set(src, name);
+    return name;
+}
+/** The image's properties after the baseline patch, with `alt` present, as `Picture` receives them. */
+function pictureProperties(properties, options) {
+    const patch = hastImagePatch(properties, options);
+    const next = { ...properties };
+    if (patch.loading !== undefined)
+        next.loading = patch.loading;
+    if (patch.decoding !== undefined)
+        next.decoding = patch.decoding;
+    if (patch.classNames !== undefined)
+        next.className = patch.classNames;
+    if (next.alt === undefined || next.alt === null)
+        next.alt = '';
+    return next;
+}
+/** The `Picture` element an author would write by hand (D2), with the image's own attributes. */
+function pictureComponent(properties, identifier, flavor) {
+    const attributes = [
+        { name: 'src', identifier },
+        { name: 'formats', list: [...PICTURE_FORMATS] },
+        { name: 'fallbackFormat', text: PICTURE_FALLBACK_FORMAT },
+    ];
+    for (const [key, value] of Object.entries(properties)) {
+        if (key === 'src' || value === undefined || value === null || value === false)
+            continue;
+        const name = key === 'className' ? 'class' : key === 'htmlFor' ? 'for' : key;
+        attributes.push({ name, text: Array.isArray(value) ? value.map(String).join(' ') : String(value) });
+    }
+    return {
+        type: 'mdxJsxFlowElement',
+        name: PICTURE_COMPONENT,
+        attributes: attributes.map((attribute) => jsxAttributeNode(attribute, flavor)),
+        children: [],
+    };
+}
+/** The root of the document, which holds the ESM imports a `Picture` needs. */
+function documentRoot(node, ctx) {
+    let current = node;
+    for (let parent = ctx.parent(current); parent; parent = ctx.parent(current))
+        current = parent;
+    return current;
+}
+function mdxScope(data) {
+    data.hagilightContentPicture ??= newMdxPictureScope();
+    return data.hagilightContentPicture;
+}
 /** Sätteri hast plugin: Astro's default Markdown processor, through `hastPlugins`. */
 export function satteriContentImages(options = {}, picture = { enabled: true }) {
     const resolved = resolveContentImageOptions(options);
@@ -195,6 +374,19 @@ export function satteriContentImages(options = {}, picture = { enabled: true })
             visit(node, ctx) {
                 if (isInsidePicture(node, ctx))
                     return;
+                const isDocument = ctx.sourceFormat === 'markdown' || ctx.sourceFormat === 'mdx';
+                const src = isDocument
+                    ? pictureSource(node.properties?.src, ctx.data.astro, picture, toFilePath(ctx.fileURL))
+                    : undefined;
+                if (src !== undefined && ctx.sourceFormat === 'mdx') {
+                    const root = documentRoot(node, ctx);
+                    const scope = mdxScope(ctx.data);
+                    const identifier = assetIdentifier(scope, src, 'source');
+                    ctx.replaceNode(node, pictureComponent(pictureProperties(node.properties ?? {}, resolved), identifier, 'source'));
+                    if (scope.pending.length > 0)
+                        ctx.prependChild(root, scope.pending.splice(0));
+                    return;
+                }
                 const patch = hastImagePatch(node.properties ?? {}, resolved);
                 if (patch.loading !== undefined)
                     ctx.setProperty(node, 'loading', patch.loading);
@@ -202,10 +394,8 @@ export function satteriContentImages(options = {}, picture = { enabled: true })
                     ctx.setProperty(node, 'decoding', patch.decoding);
                 if (patch.classNames !== undefined)
                     ctx.setProperty(node, 'className', patch.classNames);
-                if (picture.enabled && ctx.sourceFormat === 'markdown') {
-                    const src = localImageSrc(node.properties?.src, ctx.data.astro);
-                    if (src !== undefined)
-                        ctx.replaceNode(node, pictureElement(node, src, ++pictureCount));
+                if (src !== undefined && ctx.sourceFormat === 'markdown') {
+                    ctx.replaceNode(node, pictureElement(node, src, ++pictureCount));
                 }
             },
         },
@@ -268,6 +458,9 @@ export function registerContentImages({ config, logger, enabled }) {
         return;
     }
     const picture = { enabled: true };
+    const publicDir = toFilePath(config.publicDir);
+    if (publicDir !== undefined)
+        picture.publicDir = publicDir;
     const plugin = processor.name === 'satteri'
         ? satteriContentImages({}, picture)
         : (options) => rehypeContentImages(options, picture);

package/dist/promoto-banner.d.ts

@@ -1,9 +1,14 @@
 import { type PromotionCard, type PromotionImage, type PromotionImageSource } from './promotions.js';
-export type PromotionVisibility = 'dismissed' | 'footer-hidden' | 'hidden' | 'ready';
+export type PromotionVisibility = 'dismissed' | 'footer-hidden' | 'hidden' | 'ready' | 'top-hidden';
 export declare function selectPromotionCards(remote: PromotionCard[], fallback?: PromotionCard | null): PromotionCard[];
 export declare function getPromotionImageSources(image: PromotionImage | undefined): PromotionImageSource[];
 export declare function getPromotionSetSignature(cards: PromotionCard[]): string | null;
-export declare function getPromotionVisibility(cards: PromotionCard[], signature: string | null, dismissedSignature: string | null, footerVisible: boolean): PromotionVisibility;
+export declare function isScrolledToTop(scrollY: number): boolean;
+export declare function isPageTopRuleActive(visitCount: number): boolean;
+export declare function getVisitCountKey(hostname: string): string;
+export declare function parseVisitCount(raw: string | null): number;
+export declare function getPromotionVisibility(cards: PromotionCard[], signature: string | null, dismissedSignature: string | null, footerVisible: boolean, atPageTop?: boolean): PromotionVisibility;
 export declare function getNextPromotionIndex(index: number, count: number, direction: -1 | 1): number;
 export declare function shouldAutoRotate(count: number, paused: boolean, reducedMotion: boolean, documentVisible: boolean, visibility: PromotionVisibility): boolean;
+export declare function recordSiteVisit(): number;
 export declare function definePromotoBannerElement(): void;

package/dist/promoto-banner.js

@@ -2,8 +2,13 @@ import { gaEventAttributes } from './analytics-events.js';
 import { loadActivePromotions, } from './promotions.js';
 const ELEMENT_NAME = 'hagilight-promoto-banner';
 const DISMISSED_SIGNATURE_KEY = 'hagilight:promoto-banner:dismissed-signature';
+const VISIT_COUNT_KEY_PREFIX = 'hagilight:promoto-banner:visit-count:';
+const VISIT_EVENT = 'hagilight:promoto-visit';
+const PAGE_TOP_VISIT_LIMIT = 30;
 const ROTATION_INTERVAL_MS = 8000;
 const REFRESH_INTERVAL_MS = 5 * 60 * 1000;
+let lastCountedPage = null;
+let siteVisitCount = 0;
 function isRecord(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
@@ -67,12 +72,29 @@ export function getPromotionSetSignature(cards) {
         image?.variant ?? '', image?.width ?? 0, image?.height ?? 0,
     ]));
 }
-export function getPromotionVisibility(cards, signature, dismissedSignature, footerVisible) {
+export function isScrolledToTop(scrollY) {
+    return scrollY <= 1;
+}
+export function isPageTopRuleActive(visitCount) {
+    return visitCount <= PAGE_TOP_VISIT_LIMIT;
+}
+export function getVisitCountKey(hostname) {
+    return `${VISIT_COUNT_KEY_PREFIX}${hostname}`;
+}
+export function parseVisitCount(raw) {
+    if (raw === null || !/^\d+$/u.test(raw))
+        return 0;
+    const count = Number(raw);
+    return Number.isSafeInteger(count) ? count : 0;
+}
+export function getPromotionVisibility(cards, signature, dismissedSignature, footerVisible, atPageTop = false) {
     if (!cards.length)
         return 'hidden';
     if (signature && signature === dismissedSignature)
         return 'dismissed';
-    return footerVisible ? 'footer-hidden' : 'ready';
+    if (footerVisible)
+        return 'footer-hidden';
+    return atPageTop ? 'top-hidden' : 'ready';
 }
 export function getNextPromotionIndex(index, count, direction) {
     return count > 0 ? (index + direction + count) % count : 0;
@@ -96,6 +118,48 @@ function saveDismissedSignature(signature) {
         console.warn('Unable to save the dismissed promotion preference.', error);
     }
 }
+function getLocalStorage() {
+    try {
+        return window.localStorage || null;
+    }
+    catch {
+        return null;
+    }
+}
+function countVisit(storage, key) {
+    let count;
+    try {
+        count = parseVisitCount(storage.getItem(key));
+    }
+    catch {
+        return 0;
+    }
+    if (!isPageTopRuleActive(count))
+        return count;
+    try {
+        storage.setItem(key, String(count + 1));
+        return count + 1;
+    }
+    catch {
+        return count;
+    }
+}
+export function recordSiteVisit() {
+    if (typeof window === 'undefined' || !window.location)
+        return siteVisitCount;
+    const page = `${window.location.pathname}${window.location.search}`;
+    if (page === lastCountedPage)
+        return siteVisitCount;
+    const storage = getLocalStorage();
+    if (!storage)
+        return siteVisitCount;
+    lastCountedPage = page;
+    siteVisitCount = countVisit(storage, getVisitCountKey(window.location.hostname));
+    if (typeof document !== 'undefined' && typeof document.dispatchEvent === 'function') {
+        document.dispatchEvent(new Event(VISIT_EVENT));
+    }
+    return siteVisitCount;
+}
 export function definePromotoBannerElement() {
     if (typeof customElements === 'undefined' || typeof HTMLElement === 'undefined'
         || customElements.get(ELEMENT_NAME))
@@ -152,6 +216,7 @@ export function definePromotoBannerElement() {
             this.syncRotation();
         };
         onPageLoad = () => {
+            recordSiteVisit();
             // Re-fetch in the current page locale after a Starlight view-transition
             // navigation. The element may persist across a soft language switch, so
             // its previously loaded locale can differ from the new page's data-locale.
@@ -159,6 +224,7 @@ export function definePromotoBannerElement() {
                 void this.reload();
         };
         connectedCallback() {
+            recordSiteVisit();
             this.footer = document.querySelector('footer');
             this.motionQuery = window.matchMedia?.('(prefers-reduced-motion: reduce)');
             this.reducedMotion = this.motionQuery?.matches ?? false;
@@ -171,6 +237,7 @@ export function definePromotoBannerElement() {
             document.addEventListener('visibilitychange', this.onVisibilityChange);
             this.motionQuery?.addEventListener('change', this.onMotionChange);
             document.addEventListener('astro:page-load', this.onPageLoad);
+            document.addEventListener(VISIT_EVENT, this.onLayoutChange);
             if (typeof ResizeObserver !== 'undefined') {
                 this.resizeObserver = new ResizeObserver(this.onLayoutChange);
                 if (this.footer)
@@ -192,6 +259,7 @@ export function definePromotoBannerElement() {
             document.removeEventListener('visibilitychange', this.onVisibilityChange);
             this.motionQuery?.removeEventListener('change', this.onMotionChange);
             document.removeEventListener('astro:page-load', this.onPageLoad);
+            document.removeEventListener(VISIT_EVENT, this.onLayoutChange);
             this.resizeObserver?.disconnect();
             this.stopRotation();
             this.stopRefresh();
@@ -341,13 +409,15 @@ export function definePromotoBannerElement() {
         }
         updateVisibility() {
             const signature = getPromotionSetSignature(this.cards);
-            const state = getPromotionVisibility(this.cards, signature, this.dismissedSignature, this.isFooterVisible());
+            const atPageTop = isScrolledToTop(window.scrollY ?? document.documentElement.scrollTop)
+                && isPageTopRuleActive(siteVisitCount);
+            const state = getPromotionVisibility(this.cards, signature, this.dismissedSignature, this.isFooterVisible(), atPageTop);
             const hidden = state === 'hidden' || state === 'dismissed';
             const shell = this.querySelector('[data-promoto-shell]');
             this.hidden = hidden;
             if (shell) {
                 shell.hidden = hidden;
-                shell.inert = hidden || state === 'footer-hidden';
+                shell.inert = state !== 'ready';
             }
             this.dataset.state = state;
         }
@@ -360,7 +430,7 @@ export function definePromotoBannerElement() {
         syncRotation() {
             this.stopRotation();
             const state = this.dataset.state;
-            if (state !== 'ready' && state !== 'footer-hidden' && state !== 'hidden' && state !== 'dismissed')
+            if (state !== 'ready' && state !== 'footer-hidden' && state !== 'top-hidden' && state !== 'hidden' && state !== 'dismissed')
                 return;
             if (!shouldAutoRotate(this.cards.length, this.paused, this.reducedMotion, document.visibilityState !== 'hidden', state))
                 return;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hagicode/hagilight-core",
-  "version": "0.9.1-dev.98.1.e071fc7",
+  "version": "0.9.2-dev.102.1.daf22c1",
   "type": "module",
   "description": "Shared TypeScript utilities, components, and assets for HagiCode Astro and Starlight sites",
   "repository": {
@@ -58,6 +58,14 @@
       "types": "./dist/content-images.d.ts",
       "default": "./dist/content-images.js"
     },
+    "./build-info": {
+      "types": "./dist/build-info.d.ts",
+      "default": "./dist/build-info.js"
+    },
+    "./build-info-resolver": {
+      "types": "./dist/build-info-resolver.d.ts",
+      "default": "./dist/build-info-resolver.js"
+    },
     "./Copyright": "./Copyright.astro",
     "./PromotoBanner": "./PromotoBanner.astro",
     "./GoogleAnalytics": "./GoogleAnalytics.astro",