@hagicode/hagilight-core 0.8.1-dev.93.1.d28d470 → 0.8.1-dev.95.1.7e01c25

package/README.md

@@ -47,6 +47,8 @@ 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.
+
 `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:

package/dist/content-images.d.ts

@@ -37,9 +37,17 @@ export interface ContentImageNode {
     attributes?: MdxAttributeLike[];
     children?: ContentImageNode[];
 }
+export interface LocalImageData {
+    astro?: {
+        localImagePaths?: Set<string> | readonly string[];
+    };
+}
 export interface SatteriContentImageContext {
+    readonly sourceFormat: string;
+    readonly data: LocalImageData;
     parent(node: unknown): unknown;
     setProperty(node: unknown, key: string, value: unknown): void;
+    replaceNode(node: unknown, newNode: ContentImageNode): void;
 }
 export interface SatteriContentImageVisitor {
     filter: string[];
@@ -51,11 +59,19 @@ export interface SatteriContentImagePlugin {
     mdxJsxFlowElement: SatteriContentImageVisitor;
     mdxJsxTextElement: SatteriContentImageVisitor;
 }
+export interface PictureStep {
+    enabled: boolean;
+}
 export interface ContentImageRegistrationInput {
     config: {
         markdown?: {
             processor?: unknown;
         };
+        image?: {
+            service?: {
+                entrypoint?: unknown;
+            };
+        };
     };
     logger: {
         warn(message: string): void;
@@ -72,10 +88,14 @@ export interface MdxImagePatch {
 }
 /** 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;
+export interface UnifiedFileLike {
+    path?: unknown;
+    data?: LocalImageData;
+}
 /** Unified rehype plugin: `unified` processors and Astro 6 `markdown.rehypePlugins`. */
-export declare function rehypeContentImages(options?: ContentImageOptions): (tree: ContentImageNode) => void;
+export declare function rehypeContentImages(options?: ContentImageOptions, picture?: PictureStep): (tree: ContentImageNode, file?: UnifiedFileLike) => void;
 /** Sätteri hast plugin: Astro's default Markdown processor, through `hastPlugins`. */
-export declare function satteriContentImages(options?: ContentImageOptions): SatteriContentImagePlugin;
+export declare function satteriContentImages(options?: ContentImageOptions, picture?: PictureStep): 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

package/dist/content-images.js

@@ -109,11 +109,31 @@ function applyUnifiedTree(node, options, inPicture) {
     for (const child of node.children ?? [])
         applyUnifiedTree(child, options, childrenInPicture);
 }
+function wrapUnifiedPictures(node, inPicture, srcOf, nextIndex) {
+    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());
+                return;
+            }
+        }
+        wrapUnifiedPictures(child, inPicture || isPicture(child), srcOf, nextIndex);
+    });
+}
 /** Unified rehype plugin: `unified` processors and Astro 6 `markdown.rehypePlugins`. */
-export function rehypeContentImages(options = {}) {
+export function rehypeContentImages(options = {}, picture = { enabled: true }) {
     const resolved = resolveContentImageOptions(options);
-    return (tree) => {
+    let pictureCount = 0;
+    return (tree, file) => {
         applyUnifiedTree(tree, resolved, false);
+        if (!picture.enabled || !String(file?.path ?? '').endsWith('.md'))
+            return;
+        const astro = file?.data?.astro;
+        wrapUnifiedPictures(tree, false, (img) => localImageSrc(img.properties?.src, astro), () => ++pictureCount);
     };
 }
 function isInsidePicture(node, ctx) {
@@ -123,9 +143,37 @@ function isInsidePicture(node, ctx) {
     }
     return false;
 }
+const PICTURE_FORMATS = ['avif', 'webp'];
+const NOOP_IMAGE_SERVICE = 'astro/assets/services/noop';
+function localImageSrc(value, astro) {
+    const localPaths = astro?.localImagePaths;
+    if (typeof value !== 'string' || localPaths === undefined)
+        return undefined;
+    const src = decodeURI(value);
+    const isLocal = localPaths instanceof Set ? localPaths.has(src) : localPaths.includes(src);
+    return isLocal ? src : undefined;
+}
+function pictureElement(img, src, index) {
+    const sources = PICTURE_FORMATS.map((format) => ({
+        type: 'element',
+        tagName: 'source',
+        properties: {
+            __ASTRO_IMAGE_: JSON.stringify({
+                src,
+                format,
+                type: `image/${format}`,
+                densities: [1],
+                index: `picture-${format}-${index}`,
+            }),
+        },
+        children: [],
+    }));
+    return { type: 'element', tagName: 'picture', properties: {}, children: [...sources, img] };
+}
 /** Sätteri hast plugin: Astro's default Markdown processor, through `hastPlugins`. */
-export function satteriContentImages(options = {}) {
+export function satteriContentImages(options = {}, picture = { enabled: true }) {
     const resolved = resolveContentImageOptions(options);
+    let pictureCount = 0;
     const mdxVisitor = {
         filter: ['img'],
         visit(node, ctx) {
@@ -154,6 +202,11 @@ export function satteriContentImages(options = {}) {
                     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));
+                }
             },
         },
         mdxJsxFlowElement: mdxVisitor,
@@ -204,6 +257,7 @@ export function registerContentImages({ config, logger, enabled }) {
         }
         record.entry = undefined;
         record.list = undefined;
+        record.picture = undefined;
         return;
     }
     if (record.optedOut || record.entry !== undefined)
@@ -213,10 +267,14 @@ export function registerContentImages({ config, logger, enabled }) {
         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;
+    const picture = { enabled: true };
+    const plugin = processor.name === 'satteri'
+        ? satteriContentImages({}, picture)
+        : (options) => rehypeContentImages(options, picture);
     list.push(plugin);
     record.entry = plugin;
     record.list = list;
+    record.picture = picture;
 }
 /** `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 }) {
@@ -228,7 +286,12 @@ export function checkContentImageRegistration({ config, logger, enabled }) {
     const record = recordOf(processor);
     if (record.optedOut || record.warned.has('unsupported'))
         return;
-    if (record.entry !== undefined && pluginListOf(processor)?.includes(record.entry))
+    if (record.entry === undefined || !pluginListOf(processor)?.includes(record.entry)) {
+        warnOnce(record, 'lost', logger, `Hagilight content images were not found in the final "${String(processor.name)}" Markdown processor. Body images are left unchanged.`);
         return;
-    warnOnce(record, 'lost', logger, `Hagilight content images were not found in the final "${String(processor.name)}" Markdown processor. Body images are left unchanged.`);
+    }
+    if (record.picture?.enabled && config.image?.service?.entrypoint === NOOP_IMAGE_SERVICE) {
+        record.picture.enabled = false;
+        warnOnce(record, 'picture', logger, 'Hagilight content images skip the <picture> wrapper because the Astro image service is the passthrough no-op, which cannot encode AVIF. Body images keep the baseline output. Use the default sharp service to get AVIF and WebP sources.');
+    }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hagicode/hagilight-core",
-  "version": "0.8.1-dev.93.1.d28d470",
+  "version": "0.8.1-dev.95.1.7e01c25",
   "type": "module",
   "description": "Shared TypeScript utilities, components, and assets for HagiCode Astro and Starlight sites",
   "repository": {
@@ -75,7 +75,7 @@
     "favicon.ico"
   ],
   "peerDependencies": {
-    "astro": "^6.0.7 || ^7.3.5"
+    "astro": ">=7"
   },
   "peerDependenciesMeta": {
     "astro": {