@hagicode/hagilight 0.1.2-dev.3.1.1c174fd → 0.1.2-dev.4.1.974ccd5

package/PromotoBanner.astro

@@ -0,0 +1,281 @@
+---
+import type { PromotionCard } from './promotions';
+
+interface Props {
+  fallback?: PromotionCard;
+  locale?: string;
+}
+
+const { fallback, locale = Astro.currentLocale ?? 'en' } = Astro.props;
+---
+
+<hagilight-promoto-banner
+  class="hagilight-promoto"
+  data-locale={locale}
+  data-fallback={fallback ? JSON.stringify(fallback) : undefined}
+  hidden
+>
+  <section class="hagilight-promoto__shell" data-promoto-shell hidden aria-label="Featured promotion">
+    <button
+      type="button"
+      class="hagilight-promoto__dismiss"
+      data-promoto-dismiss
+      aria-label="Dismiss promotion"
+    >&times;</button>
+    <div class="hagilight-promoto__viewport">
+      <div class="hagilight-promoto__track" data-promoto-track></div>
+    </div>
+    <nav class="hagilight-promoto__controls" data-promoto-controls aria-label="Promotion controls" hidden>
+      <button type="button" class="hagilight-promoto__control" data-promoto-previous aria-label="Previous promotion">‹</button>
+      <span class="hagilight-promoto__count" data-promoto-count aria-label="Promotion progress"></span>
+      <button type="button" class="hagilight-promoto__control" data-promoto-next aria-label="Next promotion">›</button>
+      <button type="button" class="hagilight-promoto__control" data-promoto-pause aria-pressed="false">Pause</button>
+    </nav>
+    <span class="hagilight-promoto__status" data-promoto-status aria-live="polite"></span>
+  </section>
+</hagilight-promoto-banner>
+
+<script>
+  import { definePromotoBannerElement } from './promoto-banner';
+
+  definePromotoBannerElement();
+</script>
+
+<style is:global>
+  .hagilight-promoto {
+    display: block;
+  }
+
+  .hagilight-promoto[hidden],
+  .hagilight-promoto__shell[hidden],
+  .hagilight-promoto__controls[hidden] {
+    display: none !important;
+  }
+
+  .hagilight-promoto__shell {
+    position: fixed;
+    z-index: 40;
+    inset-inline: 0;
+    bottom: max(1rem, env(safe-area-inset-bottom));
+    width: min(72rem, calc(100vw - 1rem));
+    margin-inline: auto;
+    overflow: hidden;
+    border: 1px solid color-mix(in srgb, var(--sl-color-accent, #2563eb) 24%, var(--sl-color-gray-5, #cbd5e1));
+    border-radius: 1.25rem;
+    background: color-mix(in srgb, var(--sl-color-bg, #fff) 96%, var(--sl-color-accent-low, #dbeafe) 4%);
+    box-shadow: 0 18px 48px color-mix(in srgb, var(--sl-color-black, #000) 16%, transparent);
+    color: var(--sl-color-text, #1f2937);
+    opacity: 1;
+    visibility: visible;
+    transition: opacity 0.24s ease, visibility 0s linear;
+  }
+
+  .hagilight-promoto[data-state='footer-hidden'] .hagilight-promoto__shell {
+    opacity: 0;
+    visibility: hidden;
+    pointer-events: none;
+    transition: opacity 0.24s ease, visibility 0s linear 0.24s;
+  }
+
+  .hagilight-promoto__viewport {
+    overflow: hidden;
+  }
+
+  .hagilight-promoto__track {
+    display: flex;
+    align-items: stretch;
+    width: 100%;
+    transition: transform 0.34s ease;
+  }
+
+  .hagilight-promoto__slide {
+    display: grid;
+    grid-template-columns: minmax(0, 1fr) auto auto;
+    align-items: center;
+    gap: 1.25rem;
+    width: 100%;
+    min-width: 100%;
+    padding: 1.25rem 4rem 1.25rem 1.25rem;
+  }
+
+  .hagilight-promoto__slide[aria-hidden='true'] {
+    pointer-events: none;
+  }
+
+  .hagilight-promoto__copy {
+    display: grid;
+    grid-template-columns: minmax(12rem, 0.8fr) minmax(16rem, 1.2fr);
+    align-items: center;
+    gap: 1rem;
+    min-width: 0;
+  }
+
+  .hagilight-promoto__title,
+  .hagilight-promoto__description {
+    margin: 0;
+    color: var(--sl-color-text-high, #111827);
+    font-size: var(--sl-text-sm);
+    font-weight: 600;
+    line-height: 1.35;
+  }
+
+  .hagilight-promoto__description {
+    color: var(--sl-color-text, #1f2937);
+  }
+
+  .hagilight-promoto__image {
+    display: block;
+    width: clamp(4.5rem, 8vw, 6.25rem);
+    aspect-ratio: 1;
+    border-radius: 0.8rem;
+    object-fit: cover;
+  }
+
+  .hagilight-promoto__cta {
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    min-width: 7.5rem;
+    min-height: 2.6rem;
+    border: 1px solid color-mix(in srgb, var(--sl-color-accent-high, #1d4ed8) 30%, transparent);
+    border-radius: 999px;
+    background: var(--sl-color-accent, #2563eb);
+    color: #fff;
+    font-size: var(--sl-text-xs);
+    font-weight: 700;
+    padding-inline: 1rem;
+    text-align: center;
+    text-decoration: none;
+  }
+
+  .hagilight-promoto__cta:hover,
+  .hagilight-promoto__cta:focus-visible {
+    background: var(--sl-color-accent-high, #1d4ed8);
+  }
+
+  .hagilight-promoto__dismiss,
+  .hagilight-promoto__control {
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    min-width: 2.5rem;
+    min-height: 2.5rem;
+    border: 1px solid color-mix(in srgb, var(--sl-color-accent-high, #1d4ed8) 20%, var(--sl-color-gray-5, #cbd5e1));
+    border-radius: 999px;
+    background: var(--sl-color-bg-nav, #f8fafc);
+    color: var(--sl-color-text-high, #111827);
+    cursor: pointer;
+  }
+
+  .hagilight-promoto__dismiss {
+    position: absolute;
+    z-index: 1;
+    inset-block-start: 0.6rem;
+    inset-inline-end: 0.6rem;
+  }
+
+  .hagilight-promoto__controls {
+    display: flex;
+    align-items: center;
+    justify-content: flex-end;
+    gap: 0.5rem;
+    padding: 0 1.25rem 1rem;
+  }
+
+  .hagilight-promoto__count {
+    min-width: 3.5rem;
+    text-align: center;
+    font-size: var(--sl-text-xs);
+    font-variant-numeric: tabular-nums;
+  }
+
+  .hagilight-promoto__control:disabled {
+    cursor: default;
+    opacity: 0.6;
+  }
+
+  .hagilight-promoto__status {
+    position: absolute;
+    width: 1px;
+    height: 1px;
+    overflow: hidden;
+    clip: rect(0, 0, 0, 0);
+    white-space: nowrap;
+  }
+
+  .hagilight-promoto__dismiss:focus-visible,
+  .hagilight-promoto__control:focus-visible,
+  .hagilight-promoto__cta:focus-visible {
+    outline: 3px solid var(--sl-color-accent-high, #1d4ed8);
+    outline-offset: 3px;
+  }
+
+  @media (max-width: 960px) {
+    .hagilight-promoto__slide {
+      grid-template-columns: minmax(0, 1fr) auto;
+      gap: 0.75rem;
+    }
+
+    .hagilight-promoto__copy {
+      grid-template-columns: 1fr;
+      gap: 0.45rem;
+    }
+  }
+
+  @media (max-width: 720px) {
+    .hagilight-promoto__shell {
+      bottom: calc(env(safe-area-inset-bottom) + 0.5rem);
+      width: min(calc(100vw - 1rem), 28rem);
+      border-radius: 1rem;
+    }
+
+    .hagilight-promoto__slide {
+      grid-template-columns: minmax(0, 1fr) 4rem;
+      gap: 0.7rem;
+      padding: 0.85rem 3.5rem 0.85rem 0.85rem;
+    }
+
+    .hagilight-promoto__copy {
+      grid-column: 1 / -1;
+    }
+
+    .hagilight-promoto__title {
+      font-size: var(--sl-text-xs);
+    }
+
+    .hagilight-promoto__description {
+      display: -webkit-box;
+      overflow: hidden;
+      font-size: var(--sl-text-xs);
+      font-weight: 500;
+      -webkit-box-orient: vertical;
+      -webkit-line-clamp: 2;
+    }
+
+    .hagilight-promoto__image {
+      grid-column: 2;
+      grid-row: 1;
+      width: 4rem;
+    }
+
+    .hagilight-promoto__cta {
+      grid-column: 1 / -1;
+      width: 100%;
+      min-height: 2.3rem;
+    }
+
+    .hagilight-promoto__controls {
+      justify-content: flex-start;
+      flex-wrap: wrap;
+      gap: 0.35rem;
+      padding: 0 0.85rem 0.85rem;
+    }
+  }
+
+  @media (prefers-reduced-motion: reduce) {
+    .hagilight-promoto__shell,
+    .hagilight-promoto__track {
+      transition: none;
+    }
+  }
+</style>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hagicode/hagilight",
-  "version": "0.1.2-dev.3.1.1c174fd",
+  "version": "0.1.2-dev.4.1.974ccd5",
   "type": "module",
   "description": "Shared Astro components for HagiCode sites",
   "repository": {
@@ -13,10 +13,12 @@
     "provenance": true
   },
   "exports": {
-    "./Copyright": "./Copyright.astro"
+    "./Copyright": "./Copyright.astro",
+    "./PromotoBanner": "./PromotoBanner.astro"
   },
   "files": [
-    "*.astro"
+    "*.astro",
+    "*.ts"
   ],
   "peerDependencies": {
     "astro": "^7.3.5"

package/promotions.ts

@@ -0,0 +1,263 @@
+const INDEX_ORIGIN = 'https://index.hagicode.com';
+const CATALOG_URL = `${INDEX_ORIGIN}/index-catalog.json`;
+const FLAGS_URL = `${INDEX_ORIGIN}/promote.json`;
+const CONTENT_URL = `${INDEX_ORIGIN}/promote_content.json`;
+
+type JsonRecord = Record<string, unknown>;
+type FetchLike = typeof fetch;
+
+export interface PromotionImage {
+  src: string;
+  alt: string;
+  variant?: string;
+  width?: number;
+  height?: number;
+}
+
+export interface PromotionCard {
+  id: string;
+  title: string;
+  description: string;
+  ctaLabel: string;
+  link: string;
+  image?: PromotionImage;
+}
+
+interface PromotionFlag {
+  id: string;
+  on: boolean;
+  startTime?: string;
+  endTime?: string;
+}
+
+interface PromotionContent {
+  id: string;
+  title: Record<string, string>;
+  description: Record<string, string>;
+  cta?: Record<string, string>;
+  link: string;
+  image?: PromotionImage;
+}
+
+function isRecord(value: unknown): value is JsonRecord {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function nonEmptyString(value: unknown): value is string {
+  return typeof value === 'string' && value.trim().length > 0;
+}
+
+function parseLocalizedMap(value: unknown): Record<string, string> | null {
+  if (!isRecord(value)) return null;
+  const entries = Object.entries(value).filter(
+    (entry): entry is [string, string] => nonEmptyString(entry[0]) && nonEmptyString(entry[1]),
+  );
+  return entries.length ? Object.fromEntries(entries.map(([key, text]) => [key.trim(), text.trim()])) : null;
+}
+
+function parseImage(value: unknown, record: JsonRecord): PromotionImage | undefined {
+  const image = isRecord(value) ? value : {};
+  const src = nonEmptyString(value)
+    ? value.trim()
+    : nonEmptyString(image.src)
+      ? image.src.trim()
+      : nonEmptyString(image.url)
+        ? image.url.trim()
+        : nonEmptyString(record.imageUrl)
+          ? record.imageUrl.trim()
+          : nonEmptyString(record.imageURL)
+            ? record.imageURL.trim()
+            : '';
+  if (!src) return undefined;
+
+  const width = typeof image.width === 'number' && Number.isFinite(image.width) && image.width > 0
+    ? Math.round(image.width)
+    : undefined;
+  const height = typeof image.height === 'number' && Number.isFinite(image.height) && image.height > 0
+    ? Math.round(image.height)
+    : undefined;
+
+  let normalizedSrc: string;
+  try {
+    const url = new URL(src, INDEX_ORIGIN);
+    if (!['http:', 'https:'].includes(url.protocol)) return undefined;
+    normalizedSrc = url.toString();
+  } catch {
+    return undefined;
+  }
+
+  return {
+    src: normalizedSrc,
+    alt: nonEmptyString(image.alt)
+      ? image.alt.trim()
+      : nonEmptyString(record.imageAlt)
+        ? record.imageAlt.trim()
+        : '',
+    variant: nonEmptyString(image.variant) ? image.variant.trim() : undefined,
+    width,
+    height,
+  };
+}
+
+function isSafeLink(value: string): boolean {
+  try {
+    return ['http:', 'https:'].includes(new URL(value, INDEX_ORIGIN).protocol);
+  } catch {
+    return false;
+  }
+}
+
+export function parsePromotionFlags(payload: unknown): PromotionFlag[] {
+  if (!isRecord(payload) || !Array.isArray(payload.promotes)) return [];
+  return payload.promotes.flatMap((item): PromotionFlag[] => {
+    if (!isRecord(item) || !nonEmptyString(item.id) || typeof item.on !== 'boolean') return [];
+    return [{
+      id: item.id.trim(),
+      on: item.on,
+      startTime: nonEmptyString(item.startTime) ? item.startTime.trim() : undefined,
+      endTime: nonEmptyString(item.endTime) ? item.endTime.trim() : undefined,
+    }];
+  });
+}
+
+export function parsePromotionContent(payload: unknown): PromotionContent[] {
+  if (!isRecord(payload) || !Array.isArray(payload.contents)) return [];
+  return payload.contents.flatMap((item): PromotionContent[] => {
+    if (!isRecord(item) || !nonEmptyString(item.id) || !nonEmptyString(item.link) || !isSafeLink(item.link)) {
+      return [];
+    }
+    const title = parseLocalizedMap(item.title);
+    const description = parseLocalizedMap(item.description);
+    if (!title || !description) return [];
+    const cta = parseLocalizedMap(item.cta);
+    const image = parseImage(item.image, item);
+    return [{
+      id: item.id.trim(),
+      title,
+      description,
+      cta: cta ?? undefined,
+      link: item.link.trim(),
+      image,
+    }];
+  });
+}
+
+function localeCandidates(locale: string | null | undefined): string[] {
+  let canonical = 'en-US';
+  if (locale?.trim()) {
+    try {
+      canonical = Intl.getCanonicalLocales(locale.trim().replace(/_/g, '-'))[0] ?? 'en-US';
+    } catch {
+      canonical = 'en-US';
+    }
+  }
+  const normalized = canonical.toLowerCase();
+  const candidates = [normalized, normalized.split('-')[0] ?? normalized];
+  if (normalized.startsWith('zh-hant') || ['zh-tw', 'zh-hk', 'zh-mo'].includes(normalized)) {
+    candidates.push('zh-hant', 'zh');
+  } else if (normalized.startsWith('zh')) {
+    candidates.push('zh-cn', 'zh');
+  }
+  candidates.push('en-us', 'en');
+  return [...new Set(candidates)];
+}
+
+function localized(value: Record<string, string>, locale: string | null | undefined): string | null {
+  const values = new Map(Object.entries(value).map(([key, text]) => [key.toLowerCase(), text]));
+  for (const candidate of localeCandidates(locale)) {
+    const result = values.get(candidate);
+    if (result) return result;
+  }
+  return Object.values(value)[0] ?? null;
+}
+
+function isActive(flag: PromotionFlag, now: number): boolean {
+  if (!flag.on) return false;
+  const start = flag.startTime ? Date.parse(flag.startTime) : null;
+  const end = flag.endTime ? Date.parse(flag.endTime) : null;
+  if ((start !== null && !Number.isFinite(start)) || (end !== null && !Number.isFinite(end))) return false;
+  if (start !== null && end !== null && start >= end) return false;
+  return (start === null || now >= start) && (end === null || now < end);
+}
+
+export function normalizeActivePromotions(
+  flags: PromotionFlag[],
+  content: PromotionContent[],
+  locale?: string | null,
+  now = Date.now(),
+): PromotionCard[] {
+  const contentById = new Map(content.map((item) => [item.id, item]));
+  return flags.flatMap((flag): PromotionCard[] => {
+    const item = contentById.get(flag.id);
+    if (!isActive(flag, now) || !item) return [];
+    const title = localized(item.title, locale);
+    const description = localized(item.description, locale);
+    if (!title || !description) return [];
+    return [{
+      id: item.id,
+      title,
+      description,
+      ctaLabel: (item.cta && localized(item.cta, locale)) || 'Learn more',
+      link: item.link,
+      image: item.image ? { ...item.image, alt: item.image.alt || title } : undefined,
+    }];
+  });
+}
+
+async function readJson(fetchImpl: FetchLike, url: string): Promise<unknown> {
+  const response = await fetchImpl(url, { headers: { accept: 'application/json' }, cache: 'no-store' });
+  if (!response.ok) throw new Error(`Failed to load promotion data (${response.status})`);
+  const contentType = response.headers.get('content-type')?.toLowerCase() ?? '';
+  if (!contentType.includes('json')) throw new Error(`Expected JSON promotion data, received ${contentType || 'no content type'}`);
+  return response.json();
+}
+
+export async function resolvePromotionDocumentUrls(fetchImpl: FetchLike = fetch): Promise<{
+  flagsUrl: string;
+  contentUrl: string;
+  source: 'catalog' | 'fallback';
+}> {
+  try {
+    const catalog = await readJson(fetchImpl, CATALOG_URL);
+    if (isRecord(catalog) && Array.isArray(catalog.entries)) {
+      const entries = catalog.entries.filter(isRecord);
+      const flags = entries.find((entry) => entry.id === 'promotion-flags' && nonEmptyString(entry.path));
+      const content = entries.find((entry) => entry.id === 'promotion-content' && nonEmptyString(entry.path));
+      const flagsPath = flags?.path;
+      const contentPath = content?.path;
+      if (nonEmptyString(flagsPath) && nonEmptyString(contentPath)) {
+        const flagsUrl = new URL(flagsPath, INDEX_ORIGIN);
+        const contentUrl = new URL(contentPath, INDEX_ORIGIN);
+        if (flagsUrl.origin !== INDEX_ORIGIN || contentUrl.origin !== INDEX_ORIGIN) {
+          return { flagsUrl: FLAGS_URL, contentUrl: CONTENT_URL, source: 'fallback' };
+        }
+        return {
+          flagsUrl: flagsUrl.toString(),
+          contentUrl: contentUrl.toString(),
+          source: 'catalog',
+        };
+      }
+    }
+  } catch {
+    // The stable canonical endpoints remain available when catalog discovery fails.
+  }
+  return { flagsUrl: FLAGS_URL, contentUrl: CONTENT_URL, source: 'fallback' };
+}
+
+export async function loadActivePromotions(options: {
+  locale?: string | null;
+  fetchImpl?: FetchLike;
+  now?: number;
+} = {}): Promise<PromotionCard[]> {
+  const { locale, fetchImpl = fetch, now = Date.now() } = options;
+  try {
+    const urls = await resolvePromotionDocumentUrls(fetchImpl);
+    const [flags, content] = await Promise.all([
+      readJson(fetchImpl, urls.flagsUrl),
+      readJson(fetchImpl, urls.contentUrl),
+    ]);
+    return normalizeActivePromotions(parsePromotionFlags(flags), parsePromotionContent(content), locale, now);
+  } catch {
+    return [];
+  }
+}

package/promoto-banner.ts

@@ -0,0 +1,354 @@
+import { loadActivePromotions, type PromotionCard } from './promotions.ts';
+
+const ELEMENT_NAME = 'hagilight-promoto-banner';
+const DISMISSED_SIGNATURE_KEY = 'hagilight:promoto-banner:dismissed-signature';
+const ROTATION_INTERVAL_MS = 8000;
+const REFRESH_INTERVAL_MS = 5 * 60 * 1000;
+
+export type PromotionVisibility = 'dismissed' | 'footer-hidden' | 'hidden' | 'ready';
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function isSafeUrl(value: string): boolean {
+  try {
+    return ['http:', 'https:'].includes(new URL(value, 'https://hagilight.invalid/').protocol);
+  } catch {
+    return false;
+  }
+}
+
+function isUsableCard(value: unknown): value is PromotionCard {
+  if (!isRecord(value)) return false;
+  const image = value.image;
+  const imageIsValid = image === undefined || (
+    isRecord(image) && typeof image.src === 'string' && isSafeUrl(image.src)
+    && typeof image.alt === 'string'
+    && (image.variant === undefined || typeof image.variant === 'string')
+    && (image.width === undefined || (typeof image.width === 'number' && Number.isFinite(image.width) && image.width > 0))
+    && (image.height === undefined || (typeof image.height === 'number' && Number.isFinite(image.height) && image.height > 0))
+  );
+  return typeof value.id === 'string' && value.id.trim().length > 0
+    && typeof value.title === 'string' && value.title.trim().length > 0
+    && typeof value.description === 'string' && value.description.trim().length > 0
+    && typeof value.ctaLabel === 'string' && value.ctaLabel.trim().length > 0
+    && typeof value.link === 'string' && value.link.trim().length > 0 && isSafeUrl(value.link)
+    && imageIsValid;
+}
+
+export function selectPromotionCards(
+  remote: PromotionCard[],
+  fallback?: PromotionCard | null,
+): PromotionCard[] {
+  const eligibleRemote = remote.filter(isUsableCard);
+  if (eligibleRemote.length) return eligibleRemote;
+  return fallback && isUsableCard(fallback) ? [fallback] : [];
+}
+
+export function getPromotionSetSignature(cards: PromotionCard[]): string | null {
+  if (!cards.length) return null;
+  return JSON.stringify(cards.map(({ id, title, description, ctaLabel, link, image }) => [
+    id, title, description, ctaLabel, link, image?.src ?? '', image?.alt ?? '',
+    image?.variant ?? '', image?.width ?? 0, image?.height ?? 0,
+  ]));
+}
+
+export function getPromotionVisibility(
+  cards: PromotionCard[],
+  signature: string | null,
+  dismissedSignature: string | null,
+  footerVisible: boolean,
+): PromotionVisibility {
+  if (!cards.length) return 'hidden';
+  if (signature && signature === dismissedSignature) return 'dismissed';
+  return footerVisible ? 'footer-hidden' : 'ready';
+}
+
+export function getNextPromotionIndex(index: number, count: number, direction: -1 | 1): number {
+  return count > 0 ? (index + direction + count) % count : 0;
+}
+
+export function shouldAutoRotate(
+  count: number,
+  paused: boolean,
+  reducedMotion: boolean,
+  documentVisible: boolean,
+  visibility: PromotionVisibility,
+): boolean {
+  return count > 1 && !paused && !reducedMotion && documentVisible && visibility === 'ready';
+}
+
+function readDismissedSignature(): string | null {
+  try {
+    return window.localStorage.getItem(DISMISSED_SIGNATURE_KEY);
+  } catch {
+    return null;
+  }
+}
+
+function saveDismissedSignature(signature: string): void {
+  try {
+    window.localStorage.setItem(DISMISSED_SIGNATURE_KEY, signature);
+  } catch (error) {
+    console.warn('Unable to save the dismissed promotion preference.', error);
+  }
+}
+
+export function definePromotoBannerElement(): void {
+  if (typeof customElements === 'undefined' || typeof HTMLElement === 'undefined'
+    || customElements.get(ELEMENT_NAME)) return;
+
+  class PromotoBannerElement extends HTMLElement {
+    private cards: PromotionCard[] = [];
+    private currentIndex = 0;
+    private dismissedSignature = readDismissedSignature();
+    private paused = false;
+    private reducedMotion = false;
+    private rotationTimer: number | undefined;
+    private refreshTimer: number | undefined;
+    private motionQuery: MediaQueryList | undefined;
+    private resizeObserver: ResizeObserver | undefined;
+    private footer: HTMLElement | null = null;
+
+    private readonly onPrevious = () => this.move(-1);
+    private readonly onNext = () => this.move(1);
+    private readonly onPause = () => {
+      if (this.reducedMotion) return;
+      this.paused = !this.paused;
+      this.updateControls();
+      this.syncRotation();
+    };
+    private readonly onDismiss = () => {
+      const signature = getPromotionSetSignature(this.cards);
+      if (!signature) return;
+      this.dismissedSignature = signature;
+      saveDismissedSignature(signature);
+      this.updateVisibility();
+      this.stopRotation();
+    };
+    private readonly onLayoutChange = () => {
+      const previousState = this.dataset.state;
+      this.updateVisibility();
+      if (previousState !== this.dataset.state) this.syncRotation();
+    };
+    private readonly onVisibilityChange = () => {
+      if (document.visibilityState === 'hidden') {
+        this.stopRotation();
+        this.stopRefresh();
+      } else {
+        this.syncRotation();
+        this.startRefresh();
+      }
+    };
+    private readonly onMotionChange = () => {
+      this.reducedMotion = this.motionQuery?.matches ?? false;
+      this.updateControls();
+      this.syncRotation();
+    };
+
+    connectedCallback(): void {
+      this.footer = document.querySelector('footer');
+      this.motionQuery = window.matchMedia?.('(prefers-reduced-motion: reduce)');
+      this.reducedMotion = this.motionQuery?.matches ?? false;
+      this.querySelector('[data-promoto-previous]')?.addEventListener('click', this.onPrevious);
+      this.querySelector('[data-promoto-next]')?.addEventListener('click', this.onNext);
+      this.querySelector('[data-promoto-pause]')?.addEventListener('click', this.onPause);
+      this.querySelector('[data-promoto-dismiss]')?.addEventListener('click', this.onDismiss);
+      window.addEventListener('scroll', this.onLayoutChange, { passive: true });
+      window.addEventListener('resize', this.onLayoutChange);
+      document.addEventListener('visibilitychange', this.onVisibilityChange);
+      this.motionQuery?.addEventListener('change', this.onMotionChange);
+      if (typeof ResizeObserver !== 'undefined') {
+        this.resizeObserver = new ResizeObserver(this.onLayoutChange);
+        if (this.footer) this.resizeObserver.observe(this.footer);
+        const shell = this.querySelector('[data-promoto-shell]');
+        if (shell) this.resizeObserver.observe(shell);
+      }
+      void this.reload();
+      this.startRefresh();
+    }
+
+    disconnectedCallback(): void {
+      this.querySelector('[data-promoto-previous]')?.removeEventListener('click', this.onPrevious);
+      this.querySelector('[data-promoto-next]')?.removeEventListener('click', this.onNext);
+      this.querySelector('[data-promoto-pause]')?.removeEventListener('click', this.onPause);
+      this.querySelector('[data-promoto-dismiss]')?.removeEventListener('click', this.onDismiss);
+      window.removeEventListener('scroll', this.onLayoutChange);
+      window.removeEventListener('resize', this.onLayoutChange);
+      document.removeEventListener('visibilitychange', this.onVisibilityChange);
+      this.motionQuery?.removeEventListener('change', this.onMotionChange);
+      this.resizeObserver?.disconnect();
+      this.stopRotation();
+      this.stopRefresh();
+    }
+
+    private async reload(): Promise<void> {
+      const previousId = this.cards[this.currentIndex]?.id;
+      const remote = await loadActivePromotions({ locale: this.dataset.locale });
+      if (!this.isConnected) return;
+      const fallback = this.readFallback();
+      this.cards = selectPromotionCards(remote, fallback);
+      const previousIndex = previousId ? this.cards.findIndex((card) => card.id === previousId) : -1;
+      this.currentIndex = previousIndex >= 0 ? previousIndex : 0;
+      this.renderCards();
+      this.updateVisibility();
+      this.updateControls();
+      this.syncRotation();
+    }
+
+    private readFallback(): PromotionCard | null {
+      const serialized = this.dataset.fallback;
+      if (!serialized) return null;
+      try {
+        const value: unknown = JSON.parse(serialized);
+        return isUsableCard(value) ? value : null;
+      } catch (error) {
+        console.warn('Unable to parse the site-provided promotion fallback.', error);
+        return null;
+      }
+    }
+
+    private renderCards(): void {
+      const track = this.querySelector<HTMLElement>('[data-promoto-track]');
+      if (!track) return;
+      const fragment = document.createDocumentFragment();
+      this.cards.forEach((card, index) => {
+        const slide = document.createElement('article');
+        slide.className = 'hagilight-promoto__slide';
+        slide.setAttribute('aria-hidden', index === this.currentIndex ? 'false' : 'true');
+        if (index !== this.currentIndex) slide.setAttribute('inert', '');
+
+        const copy = document.createElement('div');
+        copy.className = 'hagilight-promoto__copy';
+        const title = document.createElement('h2');
+        title.className = 'hagilight-promoto__title';
+        title.textContent = card.title;
+        const description = document.createElement('p');
+        description.className = 'hagilight-promoto__description';
+        description.textContent = card.description;
+        copy.append(title, description);
+
+        const link = document.createElement('a');
+        link.className = 'hagilight-promoto__cta';
+        link.href = card.link;
+        link.target = '_blank';
+        link.rel = 'noopener noreferrer';
+        link.textContent = card.ctaLabel;
+        slide.append(copy);
+
+        if (card.image) {
+          const image = document.createElement('img');
+          image.className = 'hagilight-promoto__image';
+          image.src = card.image.src;
+          image.alt = card.image.alt || card.title;
+          image.loading = index === this.currentIndex ? 'eager' : 'lazy';
+          image.decoding = 'async';
+          if (card.image.width) image.width = card.image.width;
+          if (card.image.height) image.height = card.image.height;
+          slide.append(image);
+        }
+        slide.append(link);
+        fragment.append(slide);
+      });
+      track.replaceChildren(fragment);
+      this.updateSlides();
+    }
+
+    private updateSlides(): void {
+      const track = this.querySelector<HTMLElement>('[data-promoto-track]');
+      if (!track) return;
+      Array.from(track.children).forEach((slide, index) => {
+        const active = index === this.currentIndex;
+        slide.setAttribute('aria-hidden', String(!active));
+        if (active) slide.removeAttribute('inert');
+        else slide.setAttribute('inert', '');
+      });
+      track.style.transform = `translateX(-${this.currentIndex * 100}%)`;
+      const current = this.cards[this.currentIndex];
+      const status = this.querySelector<HTMLElement>('[data-promoto-status]');
+      if (status) status.textContent = current?.title ?? '';
+      const count = this.querySelector<HTMLElement>('[data-promoto-count]');
+      if (count) count.textContent = `${this.currentIndex + 1} / ${this.cards.length}`;
+    }
+
+    private updateControls(): void {
+      const multiple = this.cards.length > 1;
+      const controls = this.querySelector<HTMLElement>('[data-promoto-controls]');
+      if (controls) controls.hidden = !multiple;
+      const pause = this.querySelector<HTMLButtonElement>('[data-promoto-pause]');
+      if (pause) {
+        const paused = this.paused || this.reducedMotion;
+        pause.disabled = this.reducedMotion;
+        pause.setAttribute('aria-pressed', String(paused));
+        pause.setAttribute('aria-label', paused ? 'Resume automatic promotion rotation' : 'Pause automatic promotion rotation');
+        pause.textContent = paused ? 'Resume' : 'Pause';
+      }
+      this.updateSlides();
+    }
+
+    private move(direction: -1 | 1): void {
+      if (this.cards.length < 2) return;
+      this.currentIndex = getNextPromotionIndex(this.currentIndex, this.cards.length, direction);
+      this.updateSlides();
+      this.syncRotation();
+    }
+
+    private updateVisibility(): void {
+      const signature = getPromotionSetSignature(this.cards);
+      const state = getPromotionVisibility(
+        this.cards,
+        signature,
+        this.dismissedSignature,
+        this.isFooterVisible(),
+      );
+      const hidden = state === 'hidden' || state === 'dismissed';
+      const shell = this.querySelector<HTMLElement>('[data-promoto-shell]');
+      this.hidden = hidden;
+      if (shell) {
+        shell.hidden = hidden;
+        shell.inert = hidden || state === 'footer-hidden';
+      }
+      this.dataset.state = state;
+    }
+
+    private isFooterVisible(): boolean {
+      if (!this.footer) return false;
+      const bounds = this.footer.getBoundingClientRect();
+      return bounds.top < window.innerHeight && bounds.bottom > 0;
+    }
+
+    private syncRotation(): void {
+      this.stopRotation();
+      const state = this.dataset.state;
+      if (state !== 'ready' && state !== 'footer-hidden' && state !== 'hidden' && state !== 'dismissed') return;
+      if (!shouldAutoRotate(
+        this.cards.length,
+        this.paused,
+        this.reducedMotion,
+        document.visibilityState !== 'hidden',
+        state,
+      )) return;
+      this.rotationTimer = window.setInterval(() => this.move(1), ROTATION_INTERVAL_MS);
+    }
+
+    private stopRotation(): void {
+      if (this.rotationTimer !== undefined) window.clearInterval(this.rotationTimer);
+      this.rotationTimer = undefined;
+    }
+
+    private startRefresh(): void {
+      this.stopRefresh();
+      if (document.visibilityState !== 'hidden') {
+        this.refreshTimer = window.setInterval(() => void this.reload(), REFRESH_INTERVAL_MS);
+      }
+    }
+
+    private stopRefresh(): void {
+      if (this.refreshTimer !== undefined) window.clearInterval(this.refreshTimer);
+      this.refreshTimer = undefined;
+    }
+  }
+
+  customElements.define(ELEMENT_NAME, PromotoBannerElement);
+}