@hagicode/hagilight-core 0.8.1-dev.86.1.25db025 → 0.8.1-dev.88.1.80b3713

package/PromotoBanner.astro

@@ -196,6 +196,10 @@ const { fallback, locale = Astro.currentLocale ?? 'en' } = Astro.props;
     object-fit: cover;
   }
 
+  .hagilight-promoto__media picture {
+    display: contents;
+  }
+
   .hagilight-promoto__cta {
     grid-area: cta;
     display: inline-flex;

package/README.md

@@ -35,10 +35,42 @@ import { resolveSiteLinks } from '@hagicode/hagilight-core/links';
 const links = resolveSiteLinks('en-US');
 ```
 
+## 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.
+
+| Option | Default | Accepted values |
+| --- | --- | --- |
+| `loading` | `lazy` | `lazy` or `eager`, applied only when the image has no `loading` |
+| `decoding` | `async` | `async`, `sync`, or `auto`, applied only when the image has no `decoding` |
+| `className` | `hagilight-content-image` | A class name without whitespace |
+
+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.
+
+`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.
+
+To use the plugin without a feature package, add it to the Markdown processor. With the default Sätteri processor:
+
+```js
+import { defineConfig } from 'astro/config';
+import { satteri } from '@astrojs/markdown-satteri';
+import { satteriContentImages } from '@hagicode/hagilight-core/content-images';
+
+export default defineConfig({
+  markdown: {
+    processor: satteri({ hastPlugins: [satteriContentImages()] }),
+  },
+});
+```
+
+With the unified processor, pass `rehypeContentImages()` in `rehypePlugins` instead, from `@astrojs/markdown-remark`'s `unified()`. Integrations that wrap Astro can call `registerContentImages({ config, logger, enabled })` in `astro:config:setup` and `checkContentImageRegistration({ config, logger, enabled })` in `astro:config:done`, both exported from the same entry point.
+
 ## Promotion platforms
 
 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.
 
+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
 
 `GoogleAnalytics` also reports clicks on the key links and download buttons that the shared components render. There is nothing to configure: events follow the same rules as page views, so they are sent only on production pages where Google Analytics is enabled, never on the Starlight 404 page, and silently skipped when `gtag` is missing (development builds, blocked scripts).

package/dist/content-images.d.ts

@@ -0,0 +1,86 @@
+export declare const CONTENT_IMAGE_CLASS = "hagilight-content-image";
+export type ContentImageLoading = 'lazy' | 'eager';
+export type ContentImageDecoding = 'async' | 'sync' | 'auto';
+export interface ContentImageOptions {
+    /** Loading value for body images whose author set none. Defaults to `lazy`. */
+    loading?: ContentImageLoading;
+    /** Decoding value for body images whose author set none. Defaults to `async`. */
+    decoding?: ContentImageDecoding;
+    /** Marker class added once to every body image. Defaults to `hagilight-content-image`. */
+    className?: string;
+}
+export interface ResolvedContentImageOptions {
+    loading: ContentImageLoading;
+    decoding: ContentImageDecoding;
+    className: string;
+}
+export interface ContentImageAuthorValues {
+    hasLoading: boolean;
+    hasDecoding: boolean;
+    classNames: readonly string[];
+}
+export interface ContentImagePatch {
+    loading?: ContentImageLoading;
+    decoding?: ContentImageDecoding;
+    classNames?: string[];
+}
+export interface MdxAttributeLike {
+    type?: string;
+    name?: string;
+    value?: unknown;
+}
+export interface ContentImageNode {
+    type: string;
+    tagName?: string;
+    name?: string | null;
+    properties?: Record<string, unknown>;
+    attributes?: MdxAttributeLike[];
+    children?: ContentImageNode[];
+}
+export interface SatteriContentImageContext {
+    parent(node: unknown): unknown;
+    setProperty(node: unknown, key: string, value: unknown): void;
+}
+export interface SatteriContentImageVisitor {
+    filter: string[];
+    visit(node: ContentImageNode, ctx: SatteriContentImageContext): void;
+}
+export interface SatteriContentImagePlugin {
+    name: string;
+    element: SatteriContentImageVisitor;
+    mdxJsxFlowElement: SatteriContentImageVisitor;
+    mdxJsxTextElement: SatteriContentImageVisitor;
+}
+export interface ContentImageRegistrationInput {
+    config: {
+        markdown?: {
+            processor?: unknown;
+        };
+    };
+    logger: {
+        warn(message: string): void;
+    };
+    enabled: boolean;
+}
+export declare function resolveContentImageOptions(options?: ContentImageOptions): ResolvedContentImageOptions;
+export declare function contentImagePatch(author: ContentImageAuthorValues, options: ResolvedContentImageOptions): ContentImagePatch;
+export declare function hastImagePatch(properties: Record<string, unknown>, options: ResolvedContentImageOptions): ContentImagePatch;
+export interface MdxImagePatch {
+    loading?: ContentImageLoading;
+    decoding?: ContentImageDecoding;
+    className?: string;
+}
+/** A class written as an expression cannot be merged statically, so its marker is left out. */
+export declare function mdxImagePatch(attributes: readonly MdxAttributeLike[], options: ResolvedContentImageOptions): MdxImagePatch;
+/** Unified rehype plugin: `unified` processors and Astro 6 `markdown.rehypePlugins`. */
+export declare function rehypeContentImages(options?: ContentImageOptions): (tree: ContentImageNode) => void;
+/** Sätteri hast plugin: Astro's default Markdown processor, through `hastPlugins`. */
+export declare function satteriContentImages(options?: ContentImageOptions): SatteriContentImagePlugin;
+/**
+ * Register the content-image plugin on the active Markdown processor. The first enabled
+ * call appends one adapter; an `enabled: false` call opts the whole site out and removes
+ * only the adapter it did not append, so the result does not depend on hook order.
+ */
+export declare function registerContentImages({ config, logger, enabled }: ContentImageRegistrationInput): void;
+/** `astro:config:done` re-check: warns once if an enabled site's adapter is missing from the final processor. */
+export declare function checkContentImageRegistration({ config, logger, enabled }: ContentImageRegistrationInput): void;

package/dist/content-images.js

@@ -0,0 +1,234 @@
+export const CONTENT_IMAGE_CLASS = 'hagilight-content-image';
+function isRecord(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+export function resolveContentImageOptions(options = {}) {
+    if (!isRecord(options))
+        throw new TypeError('Hagilight content image options must be an object.');
+    const { loading = 'lazy', decoding = 'async', className = CONTENT_IMAGE_CLASS } = options;
+    if (loading !== 'lazy' && loading !== 'eager') {
+        throw new TypeError('Hagilight content image loading option must be "lazy" or "eager".');
+    }
+    if (decoding !== 'async' && decoding !== 'sync' && decoding !== 'auto') {
+        throw new TypeError('Hagilight content image decoding option must be "async", "sync", or "auto".');
+    }
+    if (typeof className !== 'string' || className === '' || /\s/u.test(className)) {
+        throw new TypeError('Hagilight content image className option must be a non-empty class name without whitespace.');
+    }
+    return { loading, decoding, className };
+}
+export function contentImagePatch(author, options) {
+    const patch = {};
+    if (!author.hasLoading)
+        patch.loading = options.loading;
+    if (!author.hasDecoding)
+        patch.decoding = options.decoding;
+    if (!author.classNames.includes(options.className)) {
+        patch.classNames = [...author.classNames, options.className];
+    }
+    return patch;
+}
+function splitClassNames(value) {
+    return value.split(/\s+/u).filter(Boolean);
+}
+function classNamesOf(value) {
+    if (typeof value === 'string')
+        return splitClassNames(value);
+    if (Array.isArray(value)) {
+        return value.filter((item) => typeof item === 'string').flatMap(splitClassNames);
+    }
+    return [];
+}
+function mdxClassNames(attribute) {
+    if (attribute === undefined || attribute.value === undefined || attribute.value === null)
+        return [];
+    return typeof attribute.value === 'string' ? splitClassNames(attribute.value) : undefined;
+}
+export function hastImagePatch(properties, options) {
+    return contentImagePatch({
+        hasLoading: properties.loading !== undefined,
+        hasDecoding: properties.decoding !== undefined,
+        classNames: classNamesOf(properties.className),
+    }, options);
+}
+/** A class written as an expression cannot be merged statically, so its marker is left out. */
+export function mdxImagePatch(attributes, options) {
+    const classNames = mdxClassNames(attributes.find((attribute) => attribute.name === 'class'));
+    const patch = contentImagePatch({
+        hasLoading: attributes.some((attribute) => attribute.name === 'loading'),
+        hasDecoding: attributes.some((attribute) => attribute.name === 'decoding'),
+        classNames: classNames ?? [options.className],
+    }, options);
+    return {
+        loading: patch.loading,
+        decoding: patch.decoding,
+        className: patch.classNames?.join(' '),
+    };
+}
+function isMdxJsx(node) {
+    return node.type === 'mdxJsxFlowElement' || node.type === 'mdxJsxTextElement';
+}
+function isPicture(node) {
+    return (node.type === 'element' && node.tagName === 'picture')
+        || (isMdxJsx(node) && node.name === 'picture');
+}
+function upsertMdxAttribute(attributes, name, value) {
+    const existing = attributes.find((attribute) => attribute.name === name);
+    if (existing)
+        existing.value = value;
+    else
+        attributes.push({ type: 'mdxJsxAttribute', name, value });
+}
+function applyUnifiedNode(node, options) {
+    if (node.type === 'element' && node.tagName === 'img') {
+        const properties = (node.properties ??= {});
+        const patch = hastImagePatch(properties, options);
+        if (patch.loading !== undefined)
+            properties.loading = patch.loading;
+        if (patch.decoding !== undefined)
+            properties.decoding = patch.decoding;
+        if (patch.classNames !== undefined)
+            properties.className = patch.classNames;
+        return;
+    }
+    if (isMdxJsx(node) && node.name === 'img') {
+        const attributes = (node.attributes ??= []);
+        const patch = mdxImagePatch(attributes, options);
+        if (patch.loading !== undefined)
+            upsertMdxAttribute(attributes, 'loading', patch.loading);
+        if (patch.decoding !== undefined)
+            upsertMdxAttribute(attributes, 'decoding', patch.decoding);
+        if (patch.className !== undefined)
+            upsertMdxAttribute(attributes, 'class', patch.className);
+    }
+}
+function applyUnifiedTree(node, options, inPicture) {
+    if (!inPicture)
+        applyUnifiedNode(node, options);
+    const childrenInPicture = inPicture || isPicture(node);
+    for (const child of node.children ?? [])
+        applyUnifiedTree(child, options, childrenInPicture);
+}
+/** Unified rehype plugin: `unified` processors and Astro 6 `markdown.rehypePlugins`. */
+export function rehypeContentImages(options = {}) {
+    const resolved = resolveContentImageOptions(options);
+    return (tree) => {
+        applyUnifiedTree(tree, resolved, false);
+    };
+}
+function isInsidePicture(node, ctx) {
+    for (let parent = ctx.parent(node); parent; parent = ctx.parent(parent)) {
+        if (isPicture(parent))
+            return true;
+    }
+    return false;
+}
+/** Sätteri hast plugin: Astro's default Markdown processor, through `hastPlugins`. */
+export function satteriContentImages(options = {}) {
+    const resolved = resolveContentImageOptions(options);
+    const mdxVisitor = {
+        filter: ['img'],
+        visit(node, ctx) {
+            if (isInsidePicture(node, ctx))
+                return;
+            const patch = mdxImagePatch(node.attributes ?? [], resolved);
+            if (patch.loading !== undefined)
+                ctx.setProperty(node, 'loading', patch.loading);
+            if (patch.decoding !== undefined)
+                ctx.setProperty(node, 'decoding', patch.decoding);
+            if (patch.className !== undefined)
+                ctx.setProperty(node, 'class', patch.className);
+        },
+    };
+    return {
+        name: 'hagilight:content-images',
+        element: {
+            filter: ['img'],
+            visit(node, ctx) {
+                if (isInsidePicture(node, ctx))
+                    return;
+                const patch = hastImagePatch(node.properties ?? {}, resolved);
+                if (patch.loading !== undefined)
+                    ctx.setProperty(node, 'loading', patch.loading);
+                if (patch.decoding !== undefined)
+                    ctx.setProperty(node, 'decoding', patch.decoding);
+                if (patch.classNames !== undefined)
+                    ctx.setProperty(node, 'className', patch.classNames);
+            },
+        },
+        mdxJsxFlowElement: mdxVisitor,
+        mdxJsxTextElement: mdxVisitor,
+    };
+}
+const RECORD_KEY = Symbol.for('hagilight.content-images');
+function recordOf(processor) {
+    const holder = processor;
+    holder[RECORD_KEY] ??= { optedOut: false, warned: new Set() };
+    return holder[RECORD_KEY];
+}
+function pluginListOf(processor) {
+    const hastPlugins = processor.options?.hastPlugins;
+    const rehypePlugins = processor.options?.rehypePlugins;
+    if (processor.name === 'satteri' && Array.isArray(hastPlugins))
+        return hastPlugins;
+    if (processor.name === 'unified' && Array.isArray(rehypePlugins))
+        return rehypePlugins;
+    return undefined;
+}
+function warnOnce(record, key, logger, message) {
+    if (record.warned.has(key))
+        return;
+    record.warned.add(key);
+    logger.warn(message);
+}
+/**
+ * Register the content-image plugin on the active Markdown processor. The first enabled
+ * call appends one adapter; an `enabled: false` call opts the whole site out and removes
+ * only the adapter it did not append, so the result does not depend on hook order.
+ */
+export function registerContentImages({ config, logger, enabled }) {
+    const processor = config.markdown?.processor;
+    if (!processor) {
+        if (enabled) {
+            logger.warn('Hagilight content images need a Markdown processor, but the Astro config has none. Body images are left unchanged.');
+        }
+        return;
+    }
+    const record = recordOf(processor);
+    if (!enabled) {
+        record.optedOut = true;
+        if (record.list && record.entry !== undefined) {
+            const index = record.list.indexOf(record.entry);
+            if (index !== -1)
+                record.list.splice(index, 1);
+        }
+        record.entry = undefined;
+        record.list = undefined;
+        return;
+    }
+    if (record.optedOut || record.entry !== undefined)
+        return;
+    const list = pluginListOf(processor);
+    if (!list) {
+        warnOnce(record, 'unsupported', logger, `Hagilight content images cannot run on the "${String(processor.name)}" Markdown processor. Body images are left unchanged.`);
+        return;
+    }
+    const plugin = processor.name === 'satteri' ? satteriContentImages() : rehypeContentImages;
+    list.push(plugin);
+    record.entry = plugin;
+    record.list = list;
+}
+/** `astro:config:done` re-check: warns once if an enabled site's adapter is missing from the final processor. */
+export function checkContentImageRegistration({ config, logger, enabled }) {
+    if (!enabled)
+        return;
+    const processor = config.markdown?.processor;
+    if (!processor)
+        return;
+    const record = recordOf(processor);
+    if (record.optedOut || record.warned.has('unsupported'))
+        return;
+    if (record.entry !== undefined && pluginListOf(processor)?.includes(record.entry))
+        return;
+    warnOnce(record, 'lost', logger, `Hagilight content images were not found in the final "${String(processor.name)}" Markdown processor. Body images are left unchanged.`);
+}

package/dist/promotions.d.ts

@@ -1,10 +1,15 @@
 type FetchLike = typeof fetch;
+export interface PromotionImageSource {
+    type: string;
+    src: string;
+}
 export interface PromotionImage {
     src: string;
     alt: string;
     variant?: string;
     width?: number;
     height?: number;
+    sources?: PromotionImageSource[];
 }
 export interface PromotionCard {
     id: string;

package/dist/promotions.js

@@ -15,6 +15,26 @@ function parseLocalizedMap(value) {
     const entries = Object.entries(value).filter((entry) => nonEmptyString(entry[0]) && nonEmptyString(entry[1]));
     return entries.length ? Object.fromEntries(entries.map(([key, text]) => [key.trim(), text.trim()])) : null;
 }
+function parseImageSources(value) {
+    if (!Array.isArray(value))
+        return [];
+    return value.flatMap((item) => {
+        if (!isRecord(item) || !nonEmptyString(item.type) || !nonEmptyString(item.src))
+            return [];
+        const type = item.type.trim().toLowerCase();
+        if (!type.startsWith('image/'))
+            return [];
+        try {
+            const url = new URL(item.src.trim(), INDEX_ORIGIN);
+            if (!['http:', 'https:'].includes(url.protocol))
+                return [];
+            return [{ type, src: url.toString() }];
+        }
+        catch {
+            return [];
+        }
+    });
+}
 function parseImage(value, record) {
     const image = isRecord(value) ? value : {};
     const src = nonEmptyString(value)
@@ -46,6 +66,7 @@ function parseImage(value, record) {
     catch {
         return undefined;
     }
+    const sources = parseImageSources(image.sources);
     return {
         src: normalizedSrc,
         alt: nonEmptyString(image.alt)
@@ -56,6 +77,7 @@ function parseImage(value, record) {
         variant: nonEmptyString(image.variant) ? image.variant.trim() : undefined,
         width,
         height,
+        ...(sources.length ? { sources } : {}),
     };
 }
 function isSafeLink(value) {

package/dist/promoto-banner.d.ts

@@ -1,6 +1,7 @@
-import { type PromotionCard } from './promotions.js';
+import { type PromotionCard, type PromotionImage, type PromotionImageSource } from './promotions.js';
 export type PromotionVisibility = 'dismissed' | 'footer-hidden' | 'hidden' | 'ready';
 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 getNextPromotionIndex(index: number, count: number, direction: -1 | 1): number;

package/dist/promoto-banner.js

@@ -1,5 +1,5 @@
 import { gaEventAttributes } from './analytics-events.js';
-import { loadActivePromotions } from './promotions.js';
+import { loadActivePromotions, } from './promotions.js';
 const ELEMENT_NAME = 'hagilight-promoto-banner';
 const DISMISSED_SIGNATURE_KEY = 'hagilight:promoto-banner:dismissed-signature';
 const ROTATION_INTERVAL_MS = 8000;
@@ -37,6 +37,28 @@ export function selectPromotionCards(remote, fallback) {
         return eligibleRemote;
     return fallback && isUsableCard(fallback) ? [fallback] : [];
 }
+export function getPromotionImageSources(image) {
+    if (!image || !Array.isArray(image.sources))
+        return [];
+    return image.sources.filter((source) => source.type.toLowerCase().startsWith('image/')
+        && isSafeUrl(source.src)
+        && source.src !== image.src);
+}
+function sourceUrl(source) {
+    return new URL(source.srcset, document.baseURI).href;
+}
+function advancePromotionImageSource(image) {
+    const picture = image.parentElement;
+    if (!(picture instanceof HTMLPictureElement))
+        return;
+    const failed = Array.from(picture.querySelectorAll('source'))
+        .find((source) => sourceUrl(source) === image.currentSrc);
+    if (!failed)
+        return;
+    failed.remove();
+    // Re-assigning src makes the browser re-run source selection over the remaining tiers.
+    image.src = image.src;
+}
 export function getPromotionSetSignature(cards) {
     if (!cards.length)
         return null;
@@ -241,7 +263,6 @@ export function definePromotoBannerElement() {
                     media.className = 'hagilight-promoto__media';
                     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';
@@ -249,7 +270,24 @@ export function definePromotoBannerElement() {
                         image.width = card.image.width;
                     if (card.image.height)
                         image.height = card.image.height;
-                    media.append(image);
+                    const sources = getPromotionImageSources(card.image);
+                    if (sources.length) {
+                        const picture = document.createElement('picture');
+                        picture.className = 'hagilight-promoto__picture';
+                        for (const source of sources) {
+                            const element = document.createElement('source');
+                            element.type = source.type;
+                            element.srcset = source.src;
+                            picture.append(element);
+                        }
+                        picture.append(image);
+                        image.addEventListener('error', () => advancePromotionImageSource(image));
+                        media.append(picture);
+                    }
+                    else {
+                        media.append(image);
+                    }
+                    image.src = card.image.src;
                     slide.append(media);
                 }
                 slide.append(link);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hagicode/hagilight-core",
-  "version": "0.8.1-dev.86.1.25db025",
+  "version": "0.8.1-dev.88.1.80b3713",
   "type": "module",
   "description": "Shared TypeScript utilities, components, and assets for HagiCode Astro and Starlight sites",
   "repository": {
@@ -50,6 +50,10 @@
       "types": "./dist/analytics-events.d.ts",
       "default": "./dist/analytics-events.js"
     },
+    "./content-images": {
+      "types": "./dist/content-images.d.ts",
+      "default": "./dist/content-images.js"
+    },
     "./Copyright": "./Copyright.astro",
     "./PromotoBanner": "./PromotoBanner.astro",
     "./GoogleAnalytics": "./GoogleAnalytics.astro",