@openpawlabs/diy-guides-ui 1.8.0 → 1.9.0

package/README.md

@@ -126,6 +126,28 @@ export function BatteryGuide() {
 }
 ```
 
+## Responsive images CLI
+
+Publishers can generate AVIF size variants for every raster referenced by
+`guide.mdx` without changing the authored MDX. Requires the optional peer
+`sharp` in the project that runs the CLI (it is **not** part of the browser
+bundle):
+
+```bash
+pnpm add -D sharp
+pnpm exec diy-guide-images ./path/to/guide   # or a tree of guides
+# Writes images/thumbnails/foo.w240.avif … and images/thumbnails/variants.json
+# Existing files are skipped — delete images/thumbnails/ to regenerate
+```
+
+Wrap the rendered guide in `GuideImageVariantsProvider` with that manifest so
+`MediaFigure`, thumbnails, heroes, and tool list images emit `<picture>` + AVIF
+`srcset`. Without a manifest, components fall back to the single canonical `src`.
+Lightbox always loads the full canonical file, and only while open.
+
+See `bin/diy-guide-images.mjs` and the openpaw-docs / diy-guide-example deploy
+pipelines for the full pattern.
+
 ## License
 
 AGPL-3.0 — see [LICENSE](./LICENSE).

package/bin/diy-guide-images.mjs

@@ -0,0 +1,317 @@
+#!/usr/bin/env node
+/**
+ * diy-guide-images — generate AVIF size variants for guide rasters.
+ *
+ * Usage:
+ *   diy-guide-images <path> [--dry-run] [--quality 50]
+ *
+ * `<path>` may be a single guide folder (containing guide.mdx) or a tree of
+ * guides. Writes `{stem}.w{width}.avif` under `images/thumbnails/` for each
+ * referenced raster and an `images/thumbnails/variants.json` manifest so
+ * @openpawlabs/diy-guides-ui can emit srcset without 404s.
+ *
+ * Existing variant files are skipped (delete `images/thumbnails/` to regenerate).
+ *
+ * Requires the optional peer dependency `sharp` (not shipped in the UI bundle).
+ */
+
+import { existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { basename, dirname, extname, join, resolve } from "node:path";
+
+const VARIANT_WIDTHS = [240, 480, 800, 1600];
+const VARIANT_FORMAT = "avif";
+const THUMBNAILS_DIR = "thumbnails";
+const MANIFEST_NAME = "variants.json";
+const RASTER_EXTENSIONS = new Set([".png", ".jpg", ".jpeg", ".webp", ".avif"]);
+const IMAGE_REF_RE = /['"]((?:\.\/)?images\/[^'"]+)['"]/g;
+
+async function loadSharp() {
+  try {
+    return (await import("sharp")).default;
+  } catch {
+    console.error(`error: sharp is required to run diy-guide-images.
+
+Install it in the project that runs this CLI (it is an optional peer of
+@openpawlabs/diy-guides-ui so browser consumers do not download native binaries):
+
+  pnpm add -D sharp
+  # or: npm install --save-dev sharp
+`);
+    process.exit(1);
+  }
+}
+
+function printHelp() {
+  console.log(`Usage: diy-guide-images <path> [--dry-run] [--quality <0-100>]
+
+Generate AVIF width variants for rasters referenced by guide.mdx files.
+
+Writes under images/thumbnails/ (skipped when files already exist).
+Delete that folder to force a full regenerate.
+
+Options:
+  --dry-run       Show planned work without writing files
+  --quality <n>   AVIF quality 0-100 (default: 75)
+  -h, --help      Show this help
+
+Requires optional peer dependency: sharp
+`);
+}
+
+function normalizeImageRef(ref) {
+  if (ref.startsWith("./images/")) return ref;
+  if (ref.startsWith("images/")) return `./${ref}`;
+  return ref;
+}
+
+function findGuideMdx(root) {
+  const guides = [];
+  function walk(dir) {
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+      const full = join(dir, entry.name);
+      if (entry.isDirectory()) {
+        if (entry.name === "node_modules" || entry.name === ".git") continue;
+        walk(full);
+      } else if (entry.name === "guide.mdx") {
+        guides.push(full);
+      }
+    }
+  }
+  walk(root);
+  return guides.sort();
+}
+
+function collectRefs(guidePath) {
+  const text = readFileSync(guidePath, "utf8");
+  const refs = new Map();
+  for (const match of text.matchAll(IMAGE_REF_RE)) {
+    const raw = match[1];
+    const ref = normalizeImageRef(raw);
+    const ext = extname(ref).toLowerCase();
+    if (!RASTER_EXTENSIONS.has(ext)) continue;
+    // Ignore accidental refs into the thumbnails output dir
+    if (ref.includes("/thumbnails/")) continue;
+    const sourcePath = resolve(dirname(guidePath), ref);
+    refs.set(sourcePath, ref);
+  }
+  return refs;
+}
+
+function thumbnailsDirFor(sourcePath) {
+  return join(dirname(sourcePath), THUMBNAILS_DIR);
+}
+
+function variantPath(sourcePath, width) {
+  const stem = basename(sourcePath, extname(sourcePath));
+  return join(thumbnailsDirFor(sourcePath), `${stem}.w${width}.${VARIANT_FORMAT}`);
+}
+
+function loadExistingManifest(imagesDir) {
+  const manifestPath = join(imagesDir, THUMBNAILS_DIR, MANIFEST_NAME);
+  if (!existsSync(manifestPath)) return null;
+  try {
+    return JSON.parse(readFileSync(manifestPath, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+function isFreshVariant(sourcePath, destPath) {
+  if (!existsSync(destPath)) return false;
+  try {
+    return statSync(destPath).mtimeMs >= statSync(sourcePath).mtimeMs;
+  } catch {
+    return false;
+  }
+}
+
+async function processSource(
+  sourcePath,
+  { dryRun, quality, manifestImages, existingManifest, getSharp },
+) {
+  const name = basename(sourcePath);
+  if (!existsSync(sourcePath)) {
+    console.log(`  SKIP missing: ${name}`);
+    return { generated: 0, skipped: 1 };
+  }
+
+  if (/\.w\d+\.avif$/i.test(name)) {
+    return { generated: 0, skipped: 1 };
+  }
+
+  const prior = existingManifest?.images?.[name];
+  // Fast path: no sharp when every listed variant exists and is newer than source
+  if (prior?.variants?.length && prior.width > 0) {
+    const priorWidths = prior.variants;
+    if (priorWidths.every((width) => isFreshVariant(sourcePath, variantPath(sourcePath, width)))) {
+      manifestImages[name] = {
+        width: prior.width,
+        height: prior.height,
+        variants: priorWidths,
+      };
+      return { generated: 0, skipped: priorWidths.length };
+    }
+  }
+
+  const sharp = await getSharp();
+  const meta = await sharp(sourcePath).metadata();
+  const sourceWidth = meta.width ?? 0;
+  const sourceHeight = meta.height ?? 0;
+  if (sourceWidth <= 0) {
+    console.log(`  SKIP no width: ${name}`);
+    return { generated: 0, skipped: 1 };
+  }
+
+  const widths = VARIANT_WIDTHS.filter((w) => w < sourceWidth);
+  manifestImages[name] = {
+    width: sourceWidth,
+    height: sourceHeight,
+    variants: widths,
+  };
+
+  if (widths.length === 0) {
+    return { generated: 0, skipped: 0 };
+  }
+
+  const outDir = thumbnailsDirFor(sourcePath);
+  if (!dryRun && !existsSync(outDir)) {
+    mkdirSync(outDir, { recursive: true });
+  }
+
+  let generated = 0;
+  let skipped = 0;
+  for (const width of widths) {
+    const dest = variantPath(sourcePath, width);
+    if (isFreshVariant(sourcePath, dest)) {
+      skipped += 1;
+      continue;
+    }
+    if (dryRun) {
+      console.log(`  WOULD WRITE ${THUMBNAILS_DIR}/${basename(dest)} (${width}w)`);
+      generated += 1;
+      continue;
+    }
+    await sharp(sourcePath)
+      .resize({ width, withoutEnlargement: true })
+      .avif({ quality })
+      .toFile(dest);
+    console.log(`  WRITE ${THUMBNAILS_DIR}/${basename(dest)}`);
+    generated += 1;
+  }
+  return { generated, skipped };
+}
+
+async function processGuide(guidePath, options) {
+  const refs = collectRefs(guidePath);
+  if (refs.size === 0) {
+    console.log(`No raster refs in ${guidePath}`);
+    return;
+  }
+
+  console.log(`Guide: ${guidePath}`);
+  const imagesDir = join(dirname(guidePath), "images");
+  const existingManifest = loadExistingManifest(imagesDir);
+  const manifestImages = {};
+  let generated = 0;
+  let skipped = 0;
+
+  for (const sourcePath of [...refs.keys()].sort()) {
+    const result = await processSource(sourcePath, {
+      ...options,
+      manifestImages,
+      existingManifest,
+    });
+    generated += result.generated;
+    skipped += result.skipped;
+  }
+
+  const manifest = {
+    version: 1,
+    format: VARIANT_FORMAT,
+    widths: VARIANT_WIDTHS,
+    images: manifestImages,
+  };
+  const thumbDir = join(imagesDir, THUMBNAILS_DIR);
+  const manifestPath = join(thumbDir, MANIFEST_NAME);
+
+  if (options.dryRun) {
+    console.log(
+      `  WOULD WRITE ${THUMBNAILS_DIR}/${MANIFEST_NAME} (${Object.keys(manifestImages).length} images)`,
+    );
+  } else if (!existsSync(imagesDir)) {
+    console.log(`  SKIP manifest: no images/ directory`);
+  } else {
+    if (!existsSync(thumbDir)) {
+      mkdirSync(thumbDir, { recursive: true });
+    }
+    writeFileSync(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`, "utf8");
+    console.log(`  WRITE ${THUMBNAILS_DIR}/${MANIFEST_NAME}`);
+  }
+  console.log(`  Generated ${generated}, skipped ${skipped} variant(s)\n`);
+}
+
+async function main(argv) {
+  const args = argv.slice(2);
+  if (args.length === 0 || args.includes("-h") || args.includes("--help")) {
+    printHelp();
+    process.exit(args.length === 0 ? 1 : 0);
+  }
+
+  let dryRun = false;
+  let quality = 75;
+  let root = null;
+
+  for (let i = 0; i < args.length; i += 1) {
+    const arg = args[i];
+    if (arg === "--dry-run") {
+      dryRun = true;
+    } else if (arg === "--quality") {
+      quality = Number(args[++i]);
+      if (!Number.isFinite(quality) || quality < 0 || quality > 100) {
+        console.error("error: --quality must be 0–100");
+        process.exit(2);
+      }
+    } else if (arg.startsWith("-")) {
+      console.error(`Unknown option: ${arg}`);
+      printHelp();
+      process.exit(2);
+    } else {
+      root = resolve(arg);
+    }
+  }
+
+  if (!root) {
+    printHelp();
+    process.exit(1);
+  }
+
+  if (!existsSync(root) || !statSync(root).isDirectory()) {
+    console.error(`error: not a directory: ${root}`);
+    process.exit(1);
+  }
+
+  const guideAtRoot = join(root, "guide.mdx");
+  const guides = existsSync(guideAtRoot) ? [guideAtRoot] : findGuideMdx(root);
+  if (guides.length === 0) {
+    console.error(`error: no guide.mdx found under ${root}`);
+    process.exit(1);
+  }
+
+  let sharpPromise = null;
+  const getSharp = () => {
+    sharpPromise ??= loadSharp();
+    return sharpPromise;
+  };
+
+  console.log(`Root: ${root}`);
+  console.log(`Mode: quality=${quality}${dryRun ? " (dry-run)" : ""}\n`);
+
+  for (const guide of guides) {
+    await processGuide(guide, { dryRun, quality, getSharp });
+  }
+}
+
+main(process.argv).catch((error) => {
+  console.error(error);
+  process.exit(1);
+});

package/dist/components/GuideLayout/GuideLayout.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"GuideLayout.d.ts","sourceRoot":"","sources":["../../../src/components/GuideLayout/GuideLayout.tsx"],"names":[],"mappings":"AAEA,OAAO,EAAuC,KAAK,SAAS,EAAE,MAAM,OAAO,CAAC;AAS5E,OAAO,EAEL,KAAK,UAAU,EAChB,MAAM,oBAAoB,CAAC;AAE5B,MAAM,WAAW,gBAAgB;IAC/B,mGAAmG;IACnG,QAAQ,EAAE,SAAS,CAAC;IACpB;;;;OAIG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,sBAAsB;IACrC,mBAAmB;IACnB,KAAK,EAAE,SAAS,CAAC;IACjB,uFAAuF;IACvF,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,+DAA+D;IAC/D,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,0DAA0D;IAC1D,UAAU,CAAC,EAAE,UAAU,CAAC;IACxB,kDAAkD;IAClD,YAAY,CAAC,EAAE,SAAS,CAAC;IACzB,8DAA8D;IAC9D,IAAI,CAAC,EAAE,SAAS,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,qBAAqB;IACpC,6DAA6D;IAC7D,QAAQ,EAAE,SAAS,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,iBAAS,iBAAiB,CAAC,EACzB,KAAK,EACL,SAAS,EACT,YAAY,EACZ,UAAU,EACV,YAAY,EACZ,IAAI,EACJ,SAAS,GACV,EAAE,sBAAsB,+BA2CxB;AAED,+DAA+D;AAC/D,iBAAS,gBAAgB,CAAC,EAAE,QAAQ,EAAE,SAAS,EAAE,EAAE,qBAAqB,+BAMvE;AAED,iEAAiE;AACjE,iBAAS,kBAAkB,CAAC,EAC1B,QAAQ,EACR,SAAS,GACV,EAAE;IACD,QAAQ,EAAE,SAAS,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,+BAMA;AAED,kEAAkE;AAClE,iBAAS,kBAAkB,CAAC,EAC1B,QAAQ,EACR,SAAS,GACV,EAAE;IACD,QAAQ,EAAE,SAAS,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,+BAWA;AAED;;;;;GAKG;AACH,eAAO,MAAM,WAAW,+CAKnB,gBAAgB;;;;;CAwCpB,CAAC"}
+{"version":3,"file":"GuideLayout.d.ts","sourceRoot":"","sources":["../../../src/components/GuideLayout/GuideLayout.tsx"],"names":[],"mappings":"AAEA,OAAO,EAAuC,KAAK,SAAS,EAAE,MAAM,OAAO,CAAC;AAS5E,OAAO,EAAmB,KAAK,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAGtE,MAAM,WAAW,gBAAgB;IAC/B,mGAAmG;IACnG,QAAQ,EAAE,SAAS,CAAC;IACpB;;;;OAIG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,sBAAsB;IACrC,mBAAmB;IACnB,KAAK,EAAE,SAAS,CAAC;IACjB,uFAAuF;IACvF,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,+DAA+D;IAC/D,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,0DAA0D;IAC1D,UAAU,CAAC,EAAE,UAAU,CAAC;IACxB,kDAAkD;IAClD,YAAY,CAAC,EAAE,SAAS,CAAC;IACzB,8DAA8D;IAC9D,IAAI,CAAC,EAAE,SAAS,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,qBAAqB;IACpC,6DAA6D;IAC7D,QAAQ,EAAE,SAAS,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,iBAAS,iBAAiB,CAAC,EACzB,KAAK,EACL,SAAS,EACT,YAAY,EACZ,UAAU,EACV,YAAY,EACZ,IAAI,EACJ,SAAS,GACV,EAAE,sBAAsB,+BA4CxB;AAED,+DAA+D;AAC/D,iBAAS,gBAAgB,CAAC,EAAE,QAAQ,EAAE,SAAS,EAAE,EAAE,qBAAqB,+BAMvE;AAED,iEAAiE;AACjE,iBAAS,kBAAkB,CAAC,EAC1B,QAAQ,EACR,SAAS,GACV,EAAE;IACD,QAAQ,EAAE,SAAS,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,+BAMA;AAED,kEAAkE;AAClE,iBAAS,kBAAkB,CAAC,EAC1B,QAAQ,EACR,SAAS,GACV,EAAE;IACD,QAAQ,EAAE,SAAS,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,+BAWA;AAED;;;;;GAKG;AACH,eAAO,MAAM,WAAW,+CAKnB,gBAAgB;;;;;CAwCpB,CAAC"}

package/dist/components/GuideLayout/GuideLayout.stories.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"GuideLayout.stories.d.ts","sourceRoot":"","sources":["../../../src/components/GuideLayout/GuideLayout.stories.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAQ,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AAqC5D,QAAA,MAAM,IAAI;;;;;;;qBAyDY,CAAC;;;;qBAQa,CAAC;;;;;;;;;;;;;;;CAxDD,CAAC;AAErC,eAAe,IAAI,CAAC;AAEpB,KAAK,KAAK,GAAG,QAAQ,CAAC,OAAO,IAAI,CAAC,CAAC;AAKnC,eAAO,MAAM,SAAS,EAAE,KAwGvB,CAAC;AAEF,eAAO,MAAM,aAAa,EAAE,KA2B3B,CAAC;AAEF,eAAO,MAAM,cAAc,EAAE,KAsD5B,CAAC"}
+{"version":3,"file":"GuideLayout.stories.d.ts","sourceRoot":"","sources":["../../../src/components/GuideLayout/GuideLayout.stories.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAQ,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AAqC5D,QAAA,MAAM,IAAI;;;;;;;qBA2DS,CAAC;;;;qBAO+C,CAAC;;;;;;;;;;;;;;;CAzDhC,CAAC;AAErC,eAAe,IAAI,CAAC;AAEpB,KAAK,KAAK,GAAG,QAAQ,CAAC,OAAO,IAAI,CAAC,CAAC;AAKnC,eAAO,MAAM,SAAS,EAAE,KAwGvB,CAAC;AAEF,eAAO,MAAM,aAAa,EAAE,KA2B3B,CAAC;AAEF,eAAO,MAAM,cAAc,EAAE,KAsD5B,CAAC"}

package/dist/components/GuideResponsiveImage/GuideResponsiveImage.d.ts

@@ -0,0 +1,23 @@
+import type { ImgHTMLAttributes } from "react";
+import { type GuideImageRole } from "../../utils/guideImageSources";
+export interface GuideResponsiveImageProps extends Omit<ImgHTMLAttributes<HTMLImageElement>, "src" | "srcSet" | "sizes"> {
+    src: string;
+    /** Layout role — picks default `sizes` and preferred variant width. */
+    role?: GuideImageRole;
+    /**
+     * When true, wrap in `<picture>` with an AVIF `<source>` when variants exist.
+     * @default true
+     */
+    responsive?: boolean;
+}
+/**
+ * Guide raster that opts into AVIF `srcset` when a {@link GuideImageVariantsProvider}
+ * supplies a manifest. Falls back to a single `src` otherwise.
+ *
+ * When variants exist, a `<picture>` with `display: contents` wraps the AVIF
+ * source so layout classes on the `<img>` still fill the parent frame.
+ */
+export declare function GuideResponsiveImage({ src, role, responsive, loading, decoding, alt, className, style, onLoad, ...imgProps }: GuideResponsiveImageProps): import("react").JSX.Element;
+/** Preferred single-URL variant for a role (e.g. catalog cards that need one file). */
+export declare function useGuideImagePreferredSrc(src: string | undefined, role: GuideImageRole): string | undefined;
+//# sourceMappingURL=GuideResponsiveImage.d.ts.map

package/dist/components/GuideResponsiveImage/GuideResponsiveImage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"GuideResponsiveImage.d.ts","sourceRoot":"","sources":["../../../src/components/GuideResponsiveImage/GuideResponsiveImage.tsx"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,OAAO,CAAC;AAE/C,OAAO,EAEL,KAAK,cAAc,EACpB,MAAM,+BAA+B,CAAC;AAEvC,MAAM,WAAW,yBACf,SAAQ,IAAI,CAAC,iBAAiB,CAAC,gBAAgB,CAAC,EAAE,KAAK,GAAG,QAAQ,GAAG,OAAO,CAAC;IAC7E,GAAG,EAAE,MAAM,CAAC;IACZ,uEAAuE;IACvE,IAAI,CAAC,EAAE,cAAc,CAAC;IACtB;;;OAGG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,EACnC,GAAG,EACH,IAAgB,EAChB,UAAiB,EACjB,OAAgB,EAChB,QAAkB,EAClB,GAAQ,EACR,SAAS,EACT,KAAK,EACL,MAAM,EACN,GAAG,QAAQ,EACZ,EAAE,yBAAyB,+BA+B3B;AAED,uFAAuF;AACvF,wBAAgB,yBAAyB,CACvC,GAAG,EAAE,MAAM,GAAG,SAAS,EACvB,IAAI,EAAE,cAAc,GACnB,MAAM,GAAG,SAAS,CAMpB"}

package/dist/components/MediaFigure/MediaCropEditor.d.ts

@@ -3,20 +3,22 @@ export interface MediaCropEditorProps {
     /** Image source to crop. */
     src: string;
     /**
-     * Current 4:3 region in source pixels. When omitted, the editor starts from the
-     * largest centered region (the same view the fixed frame center-crops to).
+     * Current 4:3 region as percentages of the source. When omitted, the editor
+     * starts from the largest centered region (the same view the fixed frame
+     * center-crops to). Legacy pixel regions (any axis > 100) are accepted and
+     * normalized.
      */
     region?: MediaDisplayRegion;
-    /** Reports a new region (source pixels) when the user finishes a drag. */
+    /** Reports a new region (source %) when the user finishes a drag. */
     onChange: (region: MediaDisplayRegion) => void;
     className?: string;
 }
 /**
  * Interactive crop tool: shows the full source image with a draggable, 4:3-locked
- * selection that maps directly to a {@link MediaDisplayRegion} in source pixels.
- * Drag the box to move it, drag a corner to resize. The component owns all
- * pixel geometry and reports the chosen region — selection chrome and persistence
- * stay with the consumer (see the authoring tool's crop modal).
+ * selection that maps directly to a {@link MediaDisplayRegion} in source
+ * percentages. Drag the box to move it, drag a corner to resize. The component
+ * owns all geometry and reports the chosen region — selection chrome and
+ * persistence stay with the consumer (see the authoring tool's crop modal).
  *
  * Once the source loads, the editor publishes its aspect ratio as the
  * `--crop-aspect` custom property on its root, so a sized container can fit the

package/dist/components/MediaFigure/MediaCropEditor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"MediaCropEditor.d.ts","sourceRoot":"","sources":["../../../src/components/MediaFigure/MediaCropEditor.tsx"],"names":[],"mappings":"AAUA,OAAO,EAKL,KAAK,kBAAkB,EACxB,MAAM,uBAAuB,CAAC;AA2E/B,MAAM,WAAW,oBAAoB;IACnC,4BAA4B;IAC5B,GAAG,EAAE,MAAM,CAAC;IACZ;;;OAGG;IACH,MAAM,CAAC,EAAE,kBAAkB,CAAC;IAC5B,0EAA0E;IAC1E,QAAQ,EAAE,CAAC,MAAM,EAAE,kBAAkB,KAAK,IAAI,CAAC;IAC/C,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,eAAe,CAAC,EAC9B,GAAG,EACH,MAAM,EACN,QAAQ,EACR,SAAS,GACV,EAAE,oBAAoB,+BA6ItB"}
+{"version":3,"file":"MediaCropEditor.d.ts","sourceRoot":"","sources":["../../../src/components/MediaFigure/MediaCropEditor.tsx"],"names":[],"mappings":"AAUA,OAAO,EAOL,KAAK,kBAAkB,EACxB,MAAM,uBAAuB,CAAC;AAwF/B,MAAM,WAAW,oBAAoB;IACnC,4BAA4B;IAC5B,GAAG,EAAE,MAAM,CAAC;IACZ;;;;;OAKG;IACH,MAAM,CAAC,EAAE,kBAAkB,CAAC;IAC5B,qEAAqE;IACrE,QAAQ,EAAE,CAAC,MAAM,EAAE,kBAAkB,KAAK,IAAI,CAAC;IAC/C,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,eAAe,CAAC,EAC9B,GAAG,EACH,MAAM,EACN,QAAQ,EACR,SAAS,GACV,EAAE,oBAAoB,+BAgJtB"}

package/dist/components/MediaFigure/MediaFigure.d.ts

@@ -85,8 +85,9 @@ export interface MediaFigureProps {
     /** Markers overlaid on the media, positioned by percentage of the visible frame. */
     annotations?: MediaAnnotation[];
     /**
-     * When set, show this 4:3 source-pixel rect (`height` is `round(width × 3 / 4)`),
-     * scaled to fill the frame without re-encoding the image.
+     * When set, show this 4:3 source region as percentages of the source image
+     * (`{ x, y, width }` in 0–100; height is 4:3-derived), scaled to fill the frame
+     * without re-encoding. Legacy pixel regions (any axis > 100) are still accepted.
      */
     displayRegion?: MediaDisplayRegion;
     /**
@@ -110,11 +111,12 @@ export interface MediaFigureProps {
 /**
  * Instructional image, video, or 3D model with percentage-positioned annotation overlays.
  * The frame is always 4:3; non-4:3 sources are center-cropped unless
- * `displayRegion` selects a source-pixel crop. Point markers use
+ * `displayRegion` selects a source-percentage crop. Point markers use
  * {@link GuideColor} values so they can be visually linked to matching `GuideStep`
  * bullets; circles and rectangles use the same color for their outline and fill.
  * Image figures are zoomable by default: clicking opens the full-size source in a
- * modal lightbox (see `zoomable`).
+ * modal lightbox (see `zoomable`). The lightbox mounts the canonical `src` only while
+ * open so in-page figures can stay on smaller AVIF variants.
  */
 export declare function MediaFigure({ src, type, modelFileName, annotations, displayRegion, zoomable, annotationEditing, layoutSettleKey, className, }: MediaFigureProps): import("react").JSX.Element;
 /** Recognizes MDX preview wrappers as MediaFigure slots in `GuideStep.Media`. */

package/dist/components/MediaFigure/MediaFigure.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"MediaFigure.d.ts","sourceRoot":"","sources":["../../../src/components/MediaFigure/MediaFigure.tsx"],"names":[],"mappings":"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"}
+{"version":3,"file":"MediaFigure.d.ts","sourceRoot":"","sources":["../../../src/components/MediaFigure/MediaFigure.tsx"],"names":[],"mappings":"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"}

package/dist/components/MediaFigure/MediaFigure.stories.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"MediaFigure.stories.d.ts","sourceRoot":"","sources":["../../../src/components/MediaFigure/MediaFigure.stories.tsx"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAQ,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AAE5D,OAAO,EACL,WAAW,EAGZ,MAAM,eAAe,CAAC;AAmEvB,QAAA,MAAM,IAAI;;;;;;;;;;;;;;;;;;;;;;;CAc0B,CAAC;AAErC,eAAe,IAAI,CAAC;AAEpB,KAAK,KAAK,GAAG,QAAQ,CAAC,OAAO,IAAI,CAAC,CAAC;AAEnC,eAAO,MAAM,OAAO,EAAE,KAcrB,CAAC;AAEF,eAAO,MAAM,QAAQ,EAAE,KAiBtB,CAAC;AAEF,eAAO,MAAM,oBAAoB,EAAE,KAqBlC,CAAC;AAEF,eAAO,MAAM,oBAAoB,EAAE,KA2ClC,CAAC;AAEF,eAAO,MAAM,KAAK,EAAE,KAkBnB,CAAC;AAEF,eAAO,MAAM,OAAO,EAAE,KAkBrB,CAAC;AAEF,eAAO,MAAM,mBAAmB,EAAE,KAiBjC,CAAC;AAEF,eAAO,MAAM,aAAa,EAAE,KAkB3B,CAAC;AAKF,eAAO,MAAM,gBAAgB,EAAE,KA0F9B,CAAC"}
+{"version":3,"file":"MediaFigure.stories.d.ts","sourceRoot":"","sources":["../../../src/components/MediaFigure/MediaFigure.stories.tsx"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAQ,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AAE5D,OAAO,EACL,WAAW,EAGZ,MAAM,eAAe,CAAC;AAoEvB,QAAA,MAAM,IAAI;;;;;;;;;;;;;;;;;;;;;;;CAc0B,CAAC;AAErC,eAAe,IAAI,CAAC;AAEpB,KAAK,KAAK,GAAG,QAAQ,CAAC,OAAO,IAAI,CAAC,CAAC;AAEnC,eAAO,MAAM,OAAO,EAAE,KAcrB,CAAC;AAEF,eAAO,MAAM,QAAQ,EAAE,KAiBtB,CAAC;AAEF,eAAO,MAAM,oBAAoB,EAAE,KAqBlC,CAAC;AAEF,eAAO,MAAM,oBAAoB,EAAE,KA2ClC,CAAC;AAEF,eAAO,MAAM,KAAK,EAAE,KAkBnB,CAAC;AAEF,eAAO,MAAM,OAAO,EAAE,KAkBrB,CAAC;AAEF,eAAO,MAAM,mBAAmB,EAAE,KAiBjC,CAAC;AAEF,eAAO,MAAM,aAAa,EAAE,KAkB3B,CAAC;AAKF,eAAO,MAAM,gBAAgB,EAAE,KA0F9B,CAAC"}

package/dist/components/MediaFigure/MediaFigureClipFrame.d.ts

@@ -1,5 +1,6 @@
 import { type ReactNode } from "react";
 import { type MediaDisplayRegion } from "../../utils/mediaCrop";
+import type { GuideImageRole } from "../../utils/guideImageSources";
 export interface MediaFigureClipFrameProps {
     className?: string;
     src: string;
@@ -8,6 +9,14 @@ export interface MediaFigureClipFrameProps {
     modelFileName?: string;
     layoutSettleKey?: boolean | number | string;
     remeasureWhenVisible?: boolean;
+    /** Image role for responsive `sizes` / preferred width. @default "display" */
+    imageRole?: GuideImageRole;
+    /**
+     * When false, always use the canonical `src` (lightbox). @default true
+     */
+    responsive?: boolean;
+    /** Override image loading (lightbox uses eager). */
+    loading?: "lazy" | "eager";
     children?: ReactNode;
 }
 /**
@@ -15,7 +24,7 @@ export interface MediaFigureClipFrameProps {
  * taken on this element's border box so crop math matches the visible area — including
  * inside modals and container-query layouts.
  */
-export declare function MediaFigureClipFrame({ className, src, type, displayRegion, modelFileName, layoutSettleKey, remeasureWhenVisible, children, }: MediaFigureClipFrameProps): import("react").JSX.Element;
+export declare function MediaFigureClipFrame({ className, src, type, displayRegion, modelFileName, layoutSettleKey, remeasureWhenVisible, imageRole, responsive, loading, children, }: MediaFigureClipFrameProps): import("react").JSX.Element;
 export interface MediaFigureMediaProps {
     src: string;
     type: "image" | "video" | "model";
@@ -23,6 +32,9 @@ export interface MediaFigureMediaProps {
     modelFileName?: string;
     layoutSettleKey?: boolean | number | string;
     remeasureWhenVisible?: boolean;
+    imageRole?: GuideImageRole;
+    responsive?: boolean;
+    loading?: "lazy" | "eager";
 }
 /** Fills an existing relative clip frame (used inside {@link MediaFigure}). */
 export declare function MediaFigureMedia({ className, ...props }: MediaFigureMediaProps & {

package/dist/components/MediaFigure/MediaFigureClipFrame.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"MediaFigureClipFrame.d.ts","sourceRoot":"","sources":["../../../src/components/MediaFigure/MediaFigureClipFrame.tsx"],"names":[],"mappings":"AAEA,OAAO,EAAuB,KAAK,SAAS,EAAuB,MAAM,OAAO,CAAC;AAEjF,OAAO,EAEL,KAAK,kBAAkB,EACxB,MAAM,uBAAuB,CAAC;AAM/B,MAAM,WAAW,yBAAyB;IACxC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,CAAC,EAAE,OAAO,GAAG,OAAO,GAAG,OAAO,CAAC;IACnC,aAAa,CAAC,EAAE,kBAAkB,CAAC;IACnC,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,eAAe,CAAC,EAAE,OAAO,GAAG,MAAM,GAAG,MAAM,CAAC;IAC5C,oBAAoB,CAAC,EAAE,OAAO,CAAC;IAC/B,QAAQ,CAAC,EAAE,SAAS,CAAC;CACtB;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,EACnC,SAAS,EACT,GAAG,EACH,IAAc,EACd,aAAa,EACb,aAAa,EACb,eAAe,EACf,oBAA4B,EAC5B,QAAQ,GACT,EAAE,yBAAyB,+BAwF3B;AAED,MAAM,WAAW,qBAAqB;IACpC,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,OAAO,GAAG,OAAO,GAAG,OAAO,CAAC;IAClC,aAAa,CAAC,EAAE,kBAAkB,CAAC;IACnC,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,eAAe,CAAC,EAAE,OAAO,GAAG,MAAM,GAAG,MAAM,CAAC;IAC5C,oBAAoB,CAAC,EAAE,OAAO,CAAC;CAChC;AAED,+EAA+E;AAC/E,wBAAgB,gBAAgB,CAAC,EAC/B,SAA8B,EAC9B,GAAG,KAAK,EACT,EAAE,qBAAqB,GAAG;IAAE,SAAS,CAAC,EAAE,MAAM,CAAA;CAAE,+BAEhD"}
+{"version":3,"file":"MediaFigureClipFrame.d.ts","sourceRoot":"","sources":["../../../src/components/MediaFigure/MediaFigureClipFrame.tsx"],"names":[],"mappings":"AAEA,OAAO,EAAuB,KAAK,SAAS,EAAuB,MAAM,OAAO,CAAC;AAEjF,OAAO,EAEL,KAAK,kBAAkB,EACxB,MAAM,uBAAuB,CAAC;AAG/B,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAC;AAKpE,MAAM,WAAW,yBAAyB;IACxC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,CAAC,EAAE,OAAO,GAAG,OAAO,GAAG,OAAO,CAAC;IACnC,aAAa,CAAC,EAAE,kBAAkB,CAAC;IACnC,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,eAAe,CAAC,EAAE,OAAO,GAAG,MAAM,GAAG,MAAM,CAAC;IAC5C,oBAAoB,CAAC,EAAE,OAAO,CAAC;IAC/B,8EAA8E;IAC9E,SAAS,CAAC,EAAE,cAAc,CAAC;IAC3B;;OAEG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,oDAAoD;IACpD,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;IAC3B,QAAQ,CAAC,EAAE,SAAS,CAAC;CACtB;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,EACnC,SAAS,EACT,GAAG,EACH,IAAc,EACd,aAAa,EACb,aAAa,EACb,eAAe,EACf,oBAA4B,EAC5B,SAAqB,EACrB,UAAiB,EACjB,OAAgB,EAChB,QAAQ,GACT,EAAE,yBAAyB,+BA2F3B;AAED,MAAM,WAAW,qBAAqB;IACpC,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,OAAO,GAAG,OAAO,GAAG,OAAO,CAAC;IAClC,aAAa,CAAC,EAAE,kBAAkB,CAAC;IACnC,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,eAAe,CAAC,EAAE,OAAO,GAAG,MAAM,GAAG,MAAM,CAAC;IAC5C,oBAAoB,CAAC,EAAE,OAAO,CAAC;IAC/B,SAAS,CAAC,EAAE,cAAc,CAAC;IAC3B,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;CAC5B;AAED,+EAA+E;AAC/E,wBAAgB,gBAAgB,CAAC,EAC/B,SAA8B,EAC9B,GAAG,KAAK,EACT,EAAE,qBAAqB,GAAG;IAAE,SAAS,CAAC,EAAE,MAAM,CAAA;CAAE,+BAEhD"}

package/dist/components/MediaFigure/MediaFigureThumbnail.d.ts

@@ -8,8 +8,8 @@ export interface MediaFigureThumbnailProps {
     /** Markers overlaid on the media, positioned by percentage of the visible frame. */
     annotations?: MediaAnnotation[];
     /**
-     * When set, show this 4:3 source-pixel rect in the thumbnail, matching the main
-     * {@link MediaFigure} crop.
+     * When set, show this 4:3 source-percentage rect in the thumbnail, matching the
+     * main {@link MediaFigure} crop.
      */
     displayRegion?: MediaDisplayRegion;
     className?: string;

package/dist/components/MediaFigure/MediaFigureThumbnail.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"MediaFigureThumbnail.d.ts","sourceRoot":"","sources":["../../../src/components/MediaFigure/MediaFigureThumbnail.tsx"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AACvE,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAqBhE,MAAM,WAAW,yBAAyB;IACxC,0CAA0C;IAC1C,GAAG,EAAE,MAAM,CAAC;IACZ,iFAAiF;IACjF,IAAI,CAAC,EAAE,gBAAgB,CAAC,MAAM,CAAC,CAAC;IAChC,oFAAoF;IACpF,WAAW,CAAC,EAAE,eAAe,EAAE,CAAC;IAChC;;;OAGG;IACH,aAAa,CAAC,EAAE,kBAAkB,CAAC;IACnC,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,EACnC,GAAG,EACH,IAAc,EACd,WAAgB,EAChB,aAAa,EACb,SAAS,GACV,EAAE,yBAAyB,+BAwB3B"}
+{"version":3,"file":"MediaFigureThumbnail.d.ts","sourceRoot":"","sources":["../../../src/components/MediaFigure/MediaFigureThumbnail.tsx"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AACvE,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAqBhE,MAAM,WAAW,yBAAyB;IACxC,0CAA0C;IAC1C,GAAG,EAAE,MAAM,CAAC;IACZ,iFAAiF;IACjF,IAAI,CAAC,EAAE,gBAAgB,CAAC,MAAM,CAAC,CAAC;IAChC,oFAAoF;IACpF,WAAW,CAAC,EAAE,eAAe,EAAE,CAAC;IAChC;;;OAGG;IACH,aAAa,CAAC,EAAE,kBAAkB,CAAC;IACnC,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,EACnC,GAAG,EACH,IAAc,EACd,WAAgB,EAChB,aAAa,EACb,SAAS,GACV,EAAE,yBAAyB,+BAyB3B"}

package/dist/components/ToolList/ToolList.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ToolList.d.ts","sourceRoot":"","sources":["../../../src/components/ToolList/ToolList.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAGvC,MAAM,WAAW,aAAa;IAC5B,qEAAqE;IACrE,KAAK,CAAC,EAAE,SAAS,CAAC;IAClB,gCAAgC;IAChC,QAAQ,EAAE,SAAS,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,iBAAiB;IAChC,yBAAyB;IACzB,IAAI,EAAE,SAAS,CAAC;IAChB,oCAAoC;IACpC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,iEAAiE;IACjE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,2CAA2C;IAC3C,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,mCAAmC;IACnC,KAAK,CAAC,EAAE,SAAS,CAAC;IAClB,8CAA8C;IAC9C,QAAQ,CAAC,EAAE,SAAS,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,iBAAS,YAAY,CAAC,EACpB,IAAI,EACJ,SAAS,EACT,IAAI,EACJ,QAAQ,EACR,KAAK,EACL,QAAQ,EACR,SAAS,GACV,EAAE,iBAAiB,+BAmCnB;AAED,iBAAS,YAAY,CAAC,EACpB,KAAuB,EACvB,QAAQ,EACR,SAAS,GACV,EAAE,aAAa,+BAaf;AAED;;;GAGG;AACH,eAAO,MAAM,QAAQ;;CAAsD,CAAC"}
+{"version":3,"file":"ToolList.d.ts","sourceRoot":"","sources":["../../../src/components/ToolList/ToolList.tsx"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAIvC,MAAM,WAAW,aAAa;IAC5B,qEAAqE;IACrE,KAAK,CAAC,EAAE,SAAS,CAAC;IAClB,gCAAgC;IAChC,QAAQ,EAAE,SAAS,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,iBAAiB;IAChC,yBAAyB;IACzB,IAAI,EAAE,SAAS,CAAC;IAChB,oCAAoC;IACpC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,iEAAiE;IACjE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,2CAA2C;IAC3C,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,mCAAmC;IACnC,KAAK,CAAC,EAAE,SAAS,CAAC;IAClB,8CAA8C;IAC9C,QAAQ,CAAC,EAAE,SAAS,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,iBAAS,YAAY,CAAC,EACpB,IAAI,EACJ,SAAS,EACT,IAAI,EACJ,QAAQ,EACR,KAAK,EACL,QAAQ,EACR,SAAS,GACV,EAAE,iBAAiB,+BAoCnB;AAED,iBAAS,YAAY,CAAC,EACpB,KAAuB,EACvB,QAAQ,EACR,SAAS,GACV,EAAE,aAAa,+BAaf;AAED;;;GAGG;AACH,eAAO,MAAM,QAAQ;;CAAsD,CAAC"}

package/dist/context/guideImageVariants.d.ts

@@ -0,0 +1,16 @@
+import { type ReactNode } from "react";
+import type { GuideImageVariantsManifest } from "../utils/guideImageSources";
+export interface GuideImageVariantsProviderProps {
+    /** Manifest from `images/thumbnails/variants.json`, or `null` to disable responsive variants. */
+    manifest?: GuideImageVariantsManifest | null;
+    children: ReactNode;
+}
+/**
+ * Supplies a per-guide {@link GuideImageVariantsManifest} so `MediaFigure`,
+ * thumbnails, heroes, and tool list images can emit AVIF `srcset` without
+ * speculative URLs. Omit the provider (or pass `null`) for single-`src` fallback.
+ */
+export declare function GuideImageVariantsProvider({ manifest, children, }: GuideImageVariantsProviderProps): import("react").JSX.Element;
+/** Current guide image variants manifest, or `null` when unset. */
+export declare function useGuideImageVariants(): GuideImageVariantsManifest | null;
+//# sourceMappingURL=guideImageVariants.d.ts.map

package/dist/context/guideImageVariants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"guideImageVariants.d.ts","sourceRoot":"","sources":["../../src/context/guideImageVariants.tsx"],"names":[],"mappings":"AAAA,OAAO,EAA6B,KAAK,SAAS,EAAE,MAAM,OAAO,CAAC;AAClE,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,4BAA4B,CAAC;AAM7E,MAAM,WAAW,+BAA+B;IAC9C,iGAAiG;IACjG,QAAQ,CAAC,EAAE,0BAA0B,GAAG,IAAI,CAAC;IAC7C,QAAQ,EAAE,SAAS,CAAC;CACrB;AAED;;;;GAIG;AACH,wBAAgB,0BAA0B,CAAC,EACzC,QAAe,EACf,QAAQ,GACT,EAAE,+BAA+B,+BAMjC;AAED,mEAAmE;AACnE,wBAAgB,qBAAqB,IAAI,0BAA0B,GAAG,IAAI,CAEzE"}