@hagicode/hagilight-core 0.9.1 → 0.9.2

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.
@@ -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/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",
+  "version": "0.9.2",
   "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",