Enum ImageContext 

pub enum ImageContext<'a> {
    MarkdownStandalone {
        caption: Option<&'a str>,
        width: Option<&'a str>,
        align: Option<&'a str>,
        class_names: &'a [String],
        extra_attrs: &'a BTreeMap<String, String>,
    },
    MarkdownInline,
    Hero,
    FolderCardCover,
    LinkPreview,
    Favicon,
    SiteLogo,
    TrackingPixel,
    EmailBody {
        width: Option<u32>,
        height: Option<u32>,
    },
    GalleryThumb,
    HeroBare,
}

Where the image lives in the document, which determines the wrapper element and attribute set.

Step-1 implementation supports only MarkdownInline (the default emission shape from pulldown-cmark’s serializer plus the legacy regex pair’s added attributes). Other variants are scaffolded so the call sites in Steps 3-6 can pass them without breaking the byte-shape contract; the synthesizer produces the same output for all variants until the wrapper-change step.

Step 8 (2026-05-17) made these contexts diverge structurally:

• MarkdownStandalone { caption } → <figure class="moss-image">…[<figcaption>]…</figure> wrapper
• MarkdownInline → bare <img> (or <picture><img></picture>)
• Hero → bare <img> (the hero shortcode wraps with <header>)
• FolderCardCover → bare <img> (.moss-card-cover > wraps)
• LinkPreview → bare <img> (link-preview anchor wraps)
• Favicon → bare 16×16 <img> with no <picture>, no LQIP

Not Copy (the embedded &str caption would force a lifetime on every consumer); cloning is cheap (borrow) and the call sites pass by value through the synthesizer.

Variants

MarkdownStandalone

Image-only paragraph in markdown — emits <figure class="moss-image"> around the synthesized <picture>/<img> output. Used by transform_events’s three caption-pattern branches:

• image+emphasis: ![alt](src) *caption* — caption = Some(emphasis_text)
• separate-emphasis: image-only paragraph followed by emphasis- only paragraph — caption = Some(emphasis_text)
• implicit figure: image-only paragraph with non-empty alt and [site].implicit_figure = true — caption = Some(alt_text)

caption = None means “figure wrap but no <figcaption>” (reserved for future callers that want the wrapper structurally without prose).

width = Some("body|wide|page|screen") emits data-width="..." on the outer <figure> element per spec § P9. None omits the attribute entirely so themes can target the absence via :not([data-width]). full aliases to screen upstream — values reaching this struct are already in canonical value-space.

Fields

caption: Option<&'a str>

width: Option<&'a str>

align: Option<&'a str>

Editorial runaround alignment, surfaced as a CSS class on the outer <figure>. Phase 1 C1 (2026-05-25): Stage 2 dispatcher passes Some("moss-align-left") / Some("moss-align-right") when the markdown image’s title carries moss:align=left|right. None omits the class.

class_names: &'a [String]

Arbitrary CSS class names from moss:classes="foo bar" title params (Phase 1 C1). Each entry is appended to the figure’s class="moss-image …" attribute, space-separated. Empty slice leaves the class list at its default (moss-image).

extra_attrs: &'a BTreeMap<String, String>

Arbitrary key="value" HTML attributes from leftover moss: title params (Phase 1 C1). The dispatcher passes every param that isn’t a known field (kind/width/align/classes) through here so future params propagate without code changes. Keys are emitted in BTreeMap order for stable byte shape. Empty map emits no extra attributes.

MarkdownInline

Image inside prose, a list, a table cell, or a callout body. Always emits bare <img> or <picture><img></picture>.

Hero

:::hero shortcode body image. The hero wrapper handles layout.

FolderCardCover

Folder-card cover or child-summary cover image.

LinkPreview

External-link preview thumbnail image.

Favicon

Favicon for a link-preview card. Bare 16×16 <img>, no <picture>, no LQIP, no responsive variants.

SiteLogo

Phase 2 scaffold (filled by Phase 2B agent): site-header / nav logo. Bare <img> with class="site-logo", no LQIP, no <picture>, no loading="lazy" (logo is above-the-fold). CSS handles sizing (.site-logo { height: 1.8em }).

TrackingPixel

Phase 2 scaffold (filled by Phase 2C agent): RSS read-tracking pixel. 1×1 invisible <img>. No loading="lazy" (the pixel must fire on read for tracking). No LQIP, no <picture>.

EmailBody

Phase 2 scaffold (filled by Phase 2D agent): newsletter email body image. Email-client-safe HTML subset: no <picture>, no data-*, inline style="display:block;max-width:100%;height:auto" for responsive email layouts. Explicit dims when known (callers pass Option<u32> for width/height; missing → omit per email-client tolerance).

Fields

width: Option<u32>

height: Option<u32>

GalleryThumb

Phase 2E v5 PR3 (2026-05-26): :::gallery body image. Below-the- fold thumbnail (loading="lazy"); same <picture>/dims/LQIP byte shape as MarkdownInline. The outer .moss-gallery-item wrapper is owned by the gallery shortcode’s DefaultHooks impl in crates/moss-core/src/ast/hooks.rs; this variant emits just the inner <picture><img></picture> / <img> shape so the wrapper can sit around it.

Distinct from MarkdownInline so the gallery’s per-item style passthrough (object-position from MediaAttrs) has a typed home to evolve into; today both contexts produce the same inner byte shape via synthesize_inner.

HeroBare

Phase 2E PR2 (2026-05-26): bare <img> emission with no <picture> wrap, no <source>, no LQIP, no width/height, no loading attr. Used by the hero typed-renderer fallback path (typed_renderers.rs::render_hero_html_typed) when no manifest (MediaDimensionLookup) is in scope — i.e. test / fragment-render paths where AssetRegistry::set_pending has NOT been called for the source’s .webp companion.

The asset-publish invariant (see .claude/CLAUDE.md § “Asset publish invariant”) requires us to NEVER emit a <source srcset="*.webp"> for an unregistered variant — the preview server cannot return placeholder bytes for an URL that AssetRegistry doesn’t know about, and <picture> does not recover from a chosen-source 404. HeroBare is the explicit opt-out for code paths that run before set_pending.

The byte shape mirrors the pre-Phase-2E fallback exactly: <img src="X" alt="Y"[ STYLE] /> where STYLE is the inline style fragment (already escaped) threaded through ImageRenderOptions::extra_attrs by the caller. The class and eager options are ignored — the hero <header> wraps and CSS handles loading priority.

Trait Implementations

impl<'a> Clone for ImageContext<'a>

fn clone(&self) -> ImageContext<'a>

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<'a> Debug for ImageContext<'a>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'a> Eq for ImageContext<'a>

impl<'a> PartialEq for ImageContext<'a>

fn eq(&self, other: &ImageContext<'a>) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl<'a> StructuralPartialEq for ImageContext<'a>