@hagicode/hagilight-core 0.8.1-dev.97.1.97beddb → 0.9.1-dev.100.1.8af2d7a

package/README.md

@@ -47,7 +47,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.
 

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hagicode/hagilight-core",
-  "version": "0.8.1-dev.97.1.97beddb",
+  "version": "0.9.1-dev.100.1.8af2d7a",
   "type": "module",
   "description": "Shared TypeScript utilities, components, and assets for HagiCode Astro and Starlight sites",
   "repository": {