@geekity/cms 0.3.0 → 0.4.0

package/dist/images/markup.d.ts

@@ -0,0 +1,47 @@
+import type { ImageConfig, ImageRecord } from './variants.ts';
+/**
+ * Responsive markup for the site's own pages.
+ *
+ * This runs over the HTML on its way into a theme template and nowhere else.
+ * The feeds, the JSON and Markdown representations and the ActivityStreams
+ * `content` keep the plain `<img>` that {@link renderMarkdown} produced, as
+ * decision-10 requires: a reader's client and a remote instance cannot resolve
+ * a `srcset` of this site's derived files sensibly, and half of them would
+ * strip the `<picture>` anyway.
+ */
+/** What the markup asks about an upload. See {@link describeImage}. */
+export type DescribeImage = (source: string) => ImageRecord | undefined;
+/**
+ * The `sizes` every image is given.
+ *
+ * `100vw` is 11ty/image's own default and the only honest one a CMS can pick:
+ * how wide a picture is drawn is a fact about the theme's stylesheet, which
+ * this code has never seen. A theme that knows better overrides it, and being
+ * wrong here costs bandwidth rather than correctness — the browser picks a
+ * candidate that is too wide, never one that is too small.
+ */
+export declare const IMAGE_SIZES = "100vw";
+/**
+ * Rewrite every uploaded image in a fragment of HTML as a `<picture>`.
+ *
+ * An image is left exactly as it was when it points somewhere else, when it
+ * points at a derived file already, or when the lookup knows nothing about it
+ * — which is the case for a GIF, for an SVG, and for any upload whose variants
+ * have not been derived yet. Leaving it alone is always safe: the original is
+ * the source of truth and the site serves it either way.
+ *
+ * It is a text rewrite rather than a parse because the input is one document's
+ * body, the only tags it has to understand are `<img>` ones, and a parser
+ * would have to reproduce the exact HTML around them to hand it back.
+ */
+export declare function responsiveImages(html: string, describe: DescribeImage): string;
+/**
+ * The same rewrite, over one site's own derived images.
+ *
+ * An upload with no record yet is left plain and its variants are derived in
+ * the background, so the page that first mentions a newly hand-dropped image
+ * renders at once and the one after it is responsive. Nothing waits on an
+ * encoder while a reader waits on a page.
+ */
+export declare function siteImageMarkup(config: ImageConfig, html: string): string;
+//# sourceMappingURL=markup.d.ts.map

package/dist/images/markup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"markup.d.ts","sourceRoot":"","sources":["../../src/images/markup.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,WAAW,EAAE,WAAW,EAAgB,MAAM,eAAe,CAAC;AAE5E;;;;;;;;;GASG;AAEH,uEAAuE;AACvE,MAAM,MAAM,aAAa,GAAG,CAAC,MAAM,EAAE,MAAM,KAAK,WAAW,GAAG,SAAS,CAAC;AAExE;;;;;;;;GAQG;AACH,eAAO,MAAM,WAAW,UAAU,CAAC;AAQnC;;;;;;;;;;;;GAYG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,aAAa,GAAG,MAAM,CAiB9E;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,WAAW,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAazE"}

package/dist/images/markup.js

@@ -0,0 +1,175 @@
+import { UPLOAD_ASSET_PREFIX } from '../web/assets.js';
+import { describeImage, generateImageVariants, imageMediaType, VARIANT_ASSET_PREFIX, } from './variants.js';
+/**
+ * The `sizes` every image is given.
+ *
+ * `100vw` is 11ty/image's own default and the only honest one a CMS can pick:
+ * how wide a picture is drawn is a fact about the theme's stylesheet, which
+ * this code has never seen. A theme that knows better overrides it, and being
+ * wrong here costs bandwidth rather than correctness — the browser picks a
+ * candidate that is too wide, never one that is too small.
+ */
+export const IMAGE_SIZES = '100vw';
+/** Every `<img>` tag, with its attribute text. Void elements have no closing half. */
+const IMG_TAG = /<img\s([^>]*?)\/?>/gi;
+/** One attribute of a tag: its name, and its value however it was quoted. */
+const ATTRIBUTE = /([a-zA-Z_:][-a-zA-Z0-9_:.]*)(?:\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s"'=<>`]+)))?/g;
+/**
+ * Rewrite every uploaded image in a fragment of HTML as a `<picture>`.
+ *
+ * An image is left exactly as it was when it points somewhere else, when it
+ * points at a derived file already, or when the lookup knows nothing about it
+ * — which is the case for a GIF, for an SVG, and for any upload whose variants
+ * have not been derived yet. Leaving it alone is always safe: the original is
+ * the source of truth and the site serves it either way.
+ *
+ * It is a text rewrite rather than a parse because the input is one document's
+ * body, the only tags it has to understand are `<img>` ones, and a parser
+ * would have to reproduce the exact HTML around them to hand it back.
+ */
+export function responsiveImages(html, describe) {
+    if (!html.includes('<img'))
+        return html;
+    return html.replace(IMG_TAG, (tag, attributes) => {
+        const parsed = parseAttributes(attributes);
+        const src = parsed.get('src');
+        if (src === undefined)
+            return tag;
+        const source = uploadPath(src);
+        if (source === undefined)
+            return tag;
+        const record = describe(source);
+        if (record === undefined || record.variants.length === 0)
+            return tag;
+        return picture({ tag, attributes: parsed, record });
+    });
+}
+/**
+ * The same rewrite, over one site's own derived images.
+ *
+ * An upload with no record yet is left plain and its variants are derived in
+ * the background, so the page that first mentions a newly hand-dropped image
+ * renders at once and the one after it is responsive. Nothing waits on an
+ * encoder while a reader waits on a page.
+ */
+export function siteImageMarkup(config, html) {
+    if (!config.imageOptimization)
+        return html;
+    return responsiveImages(html, (source) => {
+        const record = describeImage(config, source);
+        if (record === undefined) {
+            void generateImageVariants(config, source).catch((error) => {
+                const message = error instanceof Error ? error.message : String(error);
+                console.warn(`Could not derive image variants for ${source}: ${message}`);
+            });
+        }
+        return record;
+    });
+}
+/** One `<picture>`: a `<source>` per derived format, then the original's `<img>`. */
+function picture(input) {
+    const { record } = input;
+    const byFormat = new Map();
+    for (const variant of record.variants) {
+        byFormat.set(variant.format, [...(byFormat.get(variant.format) ?? []), variant]);
+    }
+    const sources = [];
+    for (const [format, variants] of byFormat) {
+        // The original's own format is the `<img>`, not a `<source>`: a browser
+        // that skipped every source has to land on something.
+        if (format === record.format)
+            continue;
+        const type = imageMediaType(format);
+        if (type === undefined)
+            continue;
+        sources.push(`<source type="${type}" srcset="${srcset(record.source, variants)}" sizes="${IMAGE_SIZES}">`);
+    }
+    const fallback = byFormat.get(record.format) ?? [];
+    return `<picture>${sources.join('')}${image(input.tag, input.attributes, record, fallback)}</picture>`;
+}
+/**
+ * The `<img>` at the bottom of the `<picture>`: the author's tag, with what
+ * the record knows added to it.
+ *
+ * The author's own attributes are kept verbatim and win over every one of
+ * these — a `width` written by hand is a decision, and a CMS that overruled it
+ * would be a CMS that could not be argued with.
+ */
+function image(tag, attributes, record, fallback) {
+    const additions = [];
+    if (fallback.length > 0)
+        additions.push(`srcset="${srcset(record.source, fallback)}"`);
+    additions.push(`sizes="${IMAGE_SIZES}"`);
+    additions.push(`width="${String(record.width)}"`);
+    additions.push(`height="${String(record.height)}"`);
+    additions.push('loading="lazy"');
+    const wanted = additions.filter((addition) => {
+        const name = addition.slice(0, addition.indexOf('='));
+        return !attributes.has(name);
+    });
+    if (wanted.length === 0)
+        return tag;
+    // The author's tag with the additions inserted before its close, so nothing
+    // about how it was written — the quoting, the order, a stray attribute the
+    // CMS has never heard of — is reconstructed and possibly got wrong.
+    const close = tag.endsWith('/>') ? -2 : -1;
+    return `${tag.slice(0, close).trimEnd()} ${wanted.join(' ')}>`;
+}
+/** A `srcset`: every variant of one format, narrowest first, with its width descriptor. */
+function srcset(source, variants) {
+    return [...variants]
+        .sort((a, b) => a.width - b.width)
+        .map((variant) => `${variantHref(source, variant)} ${String(variant.width)}w`)
+        .join(', ');
+}
+/** The URL of one derived file, with every path segment encoded as a URL wants. */
+function variantHref(source, variant) {
+    const segments = [...source.split('/'), variant.file].map((segment) => encodeURIComponent(segment));
+    return `${VARIANT_ASSET_PREFIX}${segments.join('/')}`;
+}
+/**
+ * The upload a `src` points at, relative to `content/uploads/`, or
+ * `undefined` when it points somewhere else.
+ *
+ * A derived file is somewhere else on purpose: the rewrite must not be able to
+ * feed on its own output, whether that is a page rendered twice or an author
+ * who pasted a variant URL by hand.
+ */
+function uploadPath(src) {
+    if (src.startsWith(VARIANT_ASSET_PREFIX))
+        return undefined;
+    if (!src.startsWith(UPLOAD_ASSET_PREFIX))
+        return undefined;
+    const relative = src.slice(UPLOAD_ASSET_PREFIX.length);
+    if (relative === '' || relative.includes('..'))
+        return undefined;
+    // A URL is what is in the attribute and a path is what is on disk, so the
+    // percent-encoding markdown-it applied has to come off before the lookup.
+    try {
+        return relative.split('/').map(decodeURIComponent).join('/');
+    }
+    catch {
+        return undefined;
+    }
+}
+/** A tag's attributes by lower-cased name, with entities left as written. */
+function parseAttributes(attributes) {
+    const parsed = new Map();
+    for (const match of attributes.matchAll(ATTRIBUTE)) {
+        const name = (match[1] ?? '').toLowerCase();
+        if (name === '' || parsed.has(name))
+            continue;
+        parsed.set(name, decodeEntities(match[2] ?? match[3] ?? match[4] ?? ''));
+    }
+    return parsed;
+}
+/** The five entities markdown-it writes into an attribute, back as characters. */
+function decodeEntities(value) {
+    return value
+        .replace(/&lt;/g, '<')
+        .replace(/&gt;/g, '>')
+        .replace(/&quot;/g, '"')
+        .replace(/&#39;/g, "'")
+        .replace(/&amp;/g, '&');
+}
+//# sourceMappingURL=markup.js.map

package/dist/images/markup.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"markup.js","sourceRoot":"","sources":["../../src/images/markup.ts"],"names":[],"mappings":"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"}

package/dist/images/paths.d.ts

@@ -0,0 +1,34 @@
+import type { ResolvedConfig } from '../config.ts';
+/**
+ * Where a derived image comes from and where it goes.
+ *
+ * Its own file because both kinds of derived file need it — the widths in
+ * `variants.ts` and the site's icons in `icons.ts` — and one of those has to
+ * be able to ask the other to derive a file without the two importing each
+ * other.
+ */
+/** The directory under `dataDir` that holds every derived image. */
+export declare const IMAGE_DIRECTORY = "images";
+/**
+ * URL prefix the derived files are served under.
+ *
+ * It sits inside `/uploads/` rather than beside it so a site's asset host, its
+ * cache rules and its Eleventy passthrough only ever have to know about one
+ * path. `_` cannot collide with a real upload: the CMS files uploads under
+ * `{yyyy}/{mm}/`, and Eleventy — like the CMS's own content walk — ignores
+ * underscore-prefixed directories anyway.
+ */
+export declare const VARIANT_ASSET_PREFIX = "/uploads/_/";
+/** The part of the config the derived images are derived according to. */
+export type ImageConfig = Pick<ResolvedConfig, 'contentDir' | 'dataDir' | 'imageOptimization' | 'imageWidths' | 'imageFormats'>;
+/** The derived directory for one upload. */
+export declare function derivedDir(config: ImageConfig, source: string): string;
+/**
+ * The upload as an absolute path, or `undefined` when it is not one.
+ *
+ * A source path can arrive off a URL, so containment is checked after
+ * resolution rather than by inspecting the string — the rule `findAsset`
+ * applies to every other request for a file.
+ */
+export declare function sourceFile(config: ImageConfig, source: string): string | undefined;
+//# sourceMappingURL=paths.d.ts.map

package/dist/images/paths.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"paths.d.ts","sourceRoot":"","sources":["../../src/images/paths.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAGnD;;;;;;;GAOG;AAEH,oEAAoE;AACpE,eAAO,MAAM,eAAe,WAAW,CAAC;AAExC;;;;;;;;GAQG;AACH,eAAO,MAAM,oBAAoB,gBAA6B,CAAC;AAE/D,0EAA0E;AAC1E,MAAM,MAAM,WAAW,GAAG,IAAI,CAC5B,cAAc,EACd,YAAY,GAAG,SAAS,GAAG,mBAAmB,GAAG,aAAa,GAAG,cAAc,CAChF,CAAC;AAEF,4CAA4C;AAC5C,wBAAgB,UAAU,CAAC,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAEtE;AAED;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAKlF"}

package/dist/images/paths.js

@@ -0,0 +1,41 @@
+import path from 'node:path';
+import { UPLOAD_ASSET_PREFIX, UPLOAD_DIRECTORY } from '../web/assets.js';
+/**
+ * Where a derived image comes from and where it goes.
+ *
+ * Its own file because both kinds of derived file need it — the widths in
+ * `variants.ts` and the site's icons in `icons.ts` — and one of those has to
+ * be able to ask the other to derive a file without the two importing each
+ * other.
+ */
+/** The directory under `dataDir` that holds every derived image. */
+export const IMAGE_DIRECTORY = 'images';
+/**
+ * URL prefix the derived files are served under.
+ *
+ * It sits inside `/uploads/` rather than beside it so a site's asset host, its
+ * cache rules and its Eleventy passthrough only ever have to know about one
+ * path. `_` cannot collide with a real upload: the CMS files uploads under
+ * `{yyyy}/{mm}/`, and Eleventy — like the CMS's own content walk — ignores
+ * underscore-prefixed directories anyway.
+ */
+export const VARIANT_ASSET_PREFIX = `${UPLOAD_ASSET_PREFIX}_/`;
+/** The derived directory for one upload. */
+export function derivedDir(config, source) {
+    return path.join(config.dataDir, IMAGE_DIRECTORY, ...source.split('/'));
+}
+/**
+ * The upload as an absolute path, or `undefined` when it is not one.
+ *
+ * A source path can arrive off a URL, so containment is checked after
+ * resolution rather than by inspecting the string — the rule `findAsset`
+ * applies to every other request for a file.
+ */
+export function sourceFile(config, source) {
+    if (source === '' || source.includes('\0'))
+        return undefined;
+    const root = path.resolve(config.contentDir, UPLOAD_DIRECTORY);
+    const file = path.resolve(root, source);
+    return file.startsWith(root + path.sep) ? file : undefined;
+}
+//# sourceMappingURL=paths.js.map

package/dist/images/paths.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"paths.js","sourceRoot":"","sources":["../../src/images/paths.ts"],"names":[],"mappings":"AAAA,OAAO,IAAI,MAAM,WAAW,CAAC;AAG7B,OAAO,EAAE,mBAAmB,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAEzE;;;;;;;GAOG;AAEH,oEAAoE;AACpE,MAAM,CAAC,MAAM,eAAe,GAAG,QAAQ,CAAC;AAExC;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG,GAAG,mBAAmB,IAAI,CAAC;AAQ/D,4CAA4C;AAC5C,MAAM,UAAU,UAAU,CAAC,MAAmB,EAAE,MAAc;IAC5D,OAAO,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,eAAe,EAAE,GAAG,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC;AAC1E,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,UAAU,CAAC,MAAmB,EAAE,MAAc;IAC5D,IAAI,MAAM,KAAK,EAAE,IAAI,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC;QAAE,OAAO,SAAS,CAAC;IAC7D,MAAM,IAAI,GAAG,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,UAAU,EAAE,gBAAgB,CAAC,CAAC;IAC/D,MAAM,IAAI,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IACxC,OAAO,IAAI,CAAC,UAAU,CAAC,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC;AAC7D,CAAC"}

package/dist/images/variants.d.ts

@@ -0,0 +1,104 @@
+import type { StaticAsset } from '../web/assets.ts';
+import type { ImageConfig } from './paths.ts';
+/**
+ * Image variants: the derived copies of an upload, and the record of them.
+ *
+ * The original under `content/uploads/` is the only source of truth
+ * (decision-10). Everything this module writes lives under
+ * `<dataDir>/images/<the upload's path>/`, is rebuildable from that original,
+ * and may be deleted at any moment — which is also decision-9's rule for
+ * `data/`. Nothing here is ever read by the feeds or by a remote instance;
+ * only the site's own HTML knows these files exist.
+ *
+ * Where the files live is `paths.ts`, and the site's icons are `icons.ts`:
+ * both kinds of derived file share the directory and the URL prefix.
+ */
+export { IMAGE_DIRECTORY, VARIANT_ASSET_PREFIX } from './paths.ts';
+export type { ImageConfig } from './paths.ts';
+/** The sidecar that records what was derived, beside the files it describes. */
+export declare const IMAGE_RECORD_NAME = "image.json";
+/** One derived copy of an upload. */
+export interface ImageVariant {
+    /** Its width in pixels, which is also what the `srcset` descriptor says. */
+    width: number;
+    /** Its height, so a caller never has to open the file to know the shape. */
+    height: number;
+    /** One of {@link KNOWN_IMAGE_FORMATS}. */
+    format: string;
+    /** Its filename inside the source's derived directory, e.g. `640.webp`. */
+    file: string;
+}
+/**
+ * What was derived from one upload, and the intrinsic size of the upload
+ * itself.
+ *
+ * This is the sidecar's shape. It exists so that rendering a page never opens
+ * an image: decision-10 requires the dimensions to be recorded when the
+ * variants are generated and read back, never probed per request.
+ */
+export interface ImageRecord {
+    /** The upload it was derived from, relative to `content/uploads/`. */
+    source: string;
+    /** The original's width once its EXIF orientation has been applied. */
+    width: number;
+    /** The original's height, likewise. */
+    height: number;
+    /** The original's own format, which is the one the `<img>` falls back to. */
+    format: string;
+    /**
+     * The original's modification time in milliseconds.
+     *
+     * It is what makes a stale record notice it is stale. The CMS never
+     * overwrites an upload — a second `photo.png` becomes `photo-2.png` — but a
+     * file dropped in by hand can be replaced, and a record that outlived its
+     * original would give the page the wrong dimensions.
+     */
+    sourceModified: number;
+    /** Every derived copy, by format in configured order and then by width. */
+    variants: ImageVariant[];
+}
+/** The media type a `<source>` for this format announces, or `undefined`. */
+export declare function imageMediaType(format: string): string | undefined;
+/** The public URL of one derived file. */
+export declare function variantUrl(source: string, variant: ImageVariant): string;
+/**
+ * Derive every variant of one upload and record what was derived.
+ *
+ * Returns `undefined` — having written nothing — when optimization is off,
+ * when the file is not a raster image the CMS varianties (a GIF, a PDF, a
+ * text file), when it is animated, or when it is not there at all. None of
+ * those is an error: an upload that has no variants is the ordinary case for
+ * most of what a site holds, and the caller's job is to fall back to the
+ * original, which is exactly what it would have served anyway.
+ *
+ * Two callers asking for the same image at once share one encode.
+ */
+export declare function generateImageVariants(config: ImageConfig, source: string): Promise<ImageRecord | undefined>;
+/**
+ * What is known about one upload's variants, or `undefined` when nothing is.
+ *
+ * Synchronous and cached, because it is called once per image while a page
+ * renders. `undefined` means the caller should serve the plain original: the
+ * upload is not an image, or nothing has been derived from it yet.
+ */
+export declare function describeImage(config: ImageConfig, source: string): ImageRecord | undefined;
+/**
+ * Take one upload's derived files away.
+ *
+ * Forgiving by design: an upload with nothing derived from it is the ordinary
+ * case, and this runs after the original has already gone, so refusing to
+ * finish would leave the site worse than it found it.
+ */
+export declare function removeImageVariants(config: ImageConfig, source: string): Promise<void>;
+/**
+ * Find one derived file by its request path, generating it if it is not there.
+ *
+ * `relative` is what follows {@link VARIANT_ASSET_PREFIX}, so
+ * `2026/09/photo.jpg/640.webp`. A request for a file that was swept away
+ * rebuilds the whole set for that source and then serves it, which is what
+ * makes the derived directory disposable in the way decision-9 requires. A
+ * request for a width or a format the site does not offer is a 404 and encodes
+ * nothing, so nobody can make the server work by asking for sizes.
+ */
+export declare function findImageVariant(config: ImageConfig, relative: string): Promise<StaticAsset | undefined>;
+//# sourceMappingURL=variants.d.ts.map

package/dist/images/variants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"variants.d.ts","sourceRoot":"","sources":["../../src/images/variants.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAGpD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE9C;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,eAAe,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AACnE,YAAY,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE9C,gFAAgF;AAChF,eAAO,MAAM,iBAAiB,eAAe,CAAC;AAE9C,qCAAqC;AACrC,MAAM,WAAW,YAAY;IAC3B,4EAA4E;IAC5E,KAAK,EAAE,MAAM,CAAC;IACd,4EAA4E;IAC5E,MAAM,EAAE,MAAM,CAAC;IACf,0CAA0C;IAC1C,MAAM,EAAE,MAAM,CAAC;IACf,2EAA2E;IAC3E,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,WAAW;IAC1B,sEAAsE;IACtE,MAAM,EAAE,MAAM,CAAC;IACf,uEAAuE;IACvE,KAAK,EAAE,MAAM,CAAC;IACd,uCAAuC;IACvC,MAAM,EAAE,MAAM,CAAC;IACf,6EAA6E;IAC7E,MAAM,EAAE,MAAM,CAAC;IACf;;;;;;;OAOG;IACH,cAAc,EAAE,MAAM,CAAC;IACvB,2EAA2E;IAC3E,QAAQ,EAAE,YAAY,EAAE,CAAC;CAC1B;AAgCD,6EAA6E;AAC7E,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAEjE;AAED,0CAA0C;AAC1C,wBAAgB,UAAU,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,YAAY,GAAG,MAAM,CAExE;AAgBD;;;;;;;;;;;GAWG;AACH,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,WAAW,EACnB,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,WAAW,GAAG,SAAS,CAAC,CAQlC;AAgID;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,MAAM,GAAG,WAAW,GAAG,SAAS,CAW1F;AAyDD;;;;;;GAMG;AACH,wBAAsB,mBAAmB,CAAC,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAM5F;AAED;;;;;;;;;GASG;AACH,wBAAsB,gBAAgB,CACpC,MAAM,EAAE,WAAW,EACnB,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,WAAW,GAAG,SAAS,CAAC,CA+BlC"}