@geekity/cms 0.3.0 → 0.4.0

package/dist/mail/templates.js

@@ -0,0 +1,69 @@
+import { createTemplateEnvironment, useThemeDirs } from '../web/templates.js';
+import { findThemeFile } from '../web/themes.js';
+/** Which files a named message is built from, relative to a theme directory. */
+export function mailTemplateFiles(name) {
+    return {
+        subject: `mail/${name}.subject.njk`,
+        text: `mail/${name}.txt.njk`,
+        html: `mail/${name}.html.njk`,
+    };
+}
+/** Build the mail templates for one site. */
+export function createMailTemplates(options) {
+    // The same environment the theme is rendered through, so a message has the
+    // same `date`, `url` and `absoluteUrl` filters a page does and a site does
+    // not have to learn a second set of rules to write one.
+    const environment = createTemplateEnvironment({
+        themeDirs: options.themes.current().dirs,
+        baseUrl: options.baseUrl,
+        ...(options.noCache === undefined ? {} : { noCache: options.noCache }),
+    });
+    // The same again with autoescaping off, for the two halves of a message that
+    // are not HTML. Built here rather than by unescaping afterwards, because
+    // there is no way to tell an `&` the template meant from one it did not.
+    const plainEnvironment = createTemplateEnvironment({
+        themeDirs: options.themes.current().dirs,
+        baseUrl: options.baseUrl,
+        autoescape: false,
+        ...(options.noCache === undefined ? {} : { noCache: options.noCache }),
+    });
+    /**
+     * The theme this message is being written in, with both environments pointed
+     * at it.
+     *
+     * Asked per message rather than held, for the reason a page asks per render:
+     * a theme chosen a minute ago is the one the next message should come from.
+     * The directories it hands back are what `present` then asks about, so which
+     * halves of a message exist is the same question as which file a render
+     * would read.
+     */
+    function themeDirs() {
+        const dirs = options.themes.current().dirs;
+        useThemeDirs(environment, dirs);
+        useThemeDirs(plainEnvironment, dirs);
+        return dirs;
+    }
+    return {
+        environment,
+        plainEnvironment,
+        render(name, context = {}) {
+            const files = mailTemplateFiles(name);
+            const searchPath = themeDirs();
+            /** Whether any theme on the search path has that template. */
+            const present = (template) => findThemeFile(searchPath, template) !== undefined;
+            if (!present(files.text)) {
+                throw new Error(`There is no mail template ${files.text} in the site theme or in the packaged one.`);
+            }
+            return {
+                // A subject is a header, and a header is one line: whatever the
+                // template did with whitespace, what goes out is a single line.
+                subject: present(files.subject)
+                    ? plainEnvironment.render(files.subject, context).replace(/\s+/g, ' ').trim()
+                    : '',
+                text: plainEnvironment.render(files.text, context),
+                ...(present(files.html) ? { html: environment.render(files.html, context) } : {}),
+            };
+        },
+    };
+}
+//# sourceMappingURL=templates.js.map

package/dist/mail/templates.js.map

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

package/dist/notifications/comments.d.ts

@@ -0,0 +1,66 @@
+import type { AdminStore, PostComment } from '../admin/store.ts';
+import type { ResolvedConfig } from '../config.ts';
+import type { ContentStore } from '../content/store.ts';
+import type { MailService } from '../mail/service.ts';
+/**
+ * The two messages a comment sets off, and the rules about who gets them.
+ *
+ * Both go through the mail service and nothing else (TASK-53), so a site with
+ * no provider sends nothing and every path through here still works. Neither
+ * is awaited by the request that caused it: a comment is stored, a page is
+ * redirected to, and the message goes out behind that.
+ *
+ * **The moderation notice.** A comment or a webmention has entered the queue,
+ * so everyone who has an address and has not turned the notice off is told,
+ * with the words themselves and three signed links that approve, file as spam
+ * or delete it without a login. It goes out for `pending` and nothing else,
+ * which is the whole of the "not for spam" rule: a comment Akismet filed as
+ * spam is nobody's decision to make today, and one it said to discard was
+ * never stored at all.
+ *
+ * **The reply notice.** Somebody ticked "tell me about replies" when they
+ * commented, and a reply to that comment has just been approved. That is the
+ * only moment it goes: an unapproved reply is not something a stranger should
+ * be emailed the text of, and a moderator should be able to delete a nasty one
+ * before anybody hears about it.
+ *
+ * Three things stop it. The address is missing, the address has unsubscribed,
+ * or the reply is by the very person who would be told — nobody needs an email
+ * about their own words.
+ */
+/** The message an admin gets when something is waiting. */
+export declare const COMMENT_PENDING_TEMPLATE = "comment-pending";
+/** The message a commenter gets when a reply to them is approved. */
+export declare const COMMENT_REPLY_TEMPLATE = "comment-reply";
+/** The event name the users screen switches, from the registry. */
+export declare const COMMENTS_NOTIFICATION = "comments";
+/** What {@link createCommentNotifier} needs. */
+export interface CreateCommentNotifierOptions {
+    /** The comment index, which is what a parent comment is looked up in. */
+    admin: AdminStore;
+    /** The content index, for the post's title. */
+    store: ContentStore;
+    /** The one door out for email. */
+    mail: MailService;
+    /**
+     * Config after defaults: the base URL the links are absolute against, the
+     * data directory the signing secret and the opt-outs live in, and the clock.
+     */
+    config: Pick<ResolvedConfig, 'baseUrl' | 'dataDir' | 'now'>;
+}
+/** Tells people about comments. Never throws, and never waits on a provider. */
+export interface CommentNotifier {
+    /**
+     * A comment has been stored. Tells the moderators when, and only when, it is
+     * waiting for one of them.
+     */
+    pending(comment: PostComment): void;
+    /**
+     * A comment has been approved. Tells whoever it answers, when they asked to
+     * be told and are still listening.
+     */
+    replyApproved(reply: PostComment): void;
+}
+/** Build the notifier for one site. */
+export declare function createCommentNotifier(options: CreateCommentNotifierOptions): CommentNotifier;
+//# sourceMappingURL=comments.d.ts.map

package/dist/notifications/comments.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"comments.d.ts","sourceRoot":"","sources":["../../src/notifications/comments.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AACjE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AACnD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACxD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAKtD;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,2DAA2D;AAC3D,eAAO,MAAM,wBAAwB,oBAAoB,CAAC;AAE1D,qEAAqE;AACrE,eAAO,MAAM,sBAAsB,kBAAkB,CAAC;AAEtD,mEAAmE;AACnE,eAAO,MAAM,qBAAqB,aAAa,CAAC;AAEhD,gDAAgD;AAChD,MAAM,WAAW,4BAA4B;IAC3C,yEAAyE;IACzE,KAAK,EAAE,UAAU,CAAC;IAClB,+CAA+C;IAC/C,KAAK,EAAE,YAAY,CAAC;IACpB,kCAAkC;IAClC,IAAI,EAAE,WAAW,CAAC;IAClB;;;OAGG;IACH,MAAM,EAAE,IAAI,CAAC,cAAc,EAAE,SAAS,GAAG,SAAS,GAAG,KAAK,CAAC,CAAC;CAC7D;AAED,gFAAgF;AAChF,MAAM,WAAW,eAAe;IAC9B;;;OAGG;IACH,OAAO,CAAC,OAAO,EAAE,WAAW,GAAG,IAAI,CAAC;IACpC;;;OAGG;IACH,aAAa,CAAC,KAAK,EAAE,WAAW,GAAG,IAAI,CAAC;CACzC;AAED,uCAAuC;AACvC,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,4BAA4B,GAAG,eAAe,CA6G5F"}

package/dist/notifications/comments.js

@@ -0,0 +1,151 @@
+import { listUsers } from '../admin/accounts.js';
+import { commentAnchor } from '../web/conversation.js';
+import { MODERATION_ACTIONS } from '../comments/moderate.js';
+import { moderationLink, unsubscribeLink } from './links.js';
+import { hasOptedOut } from './optouts.js';
+import { isBatchedMode, notificationMode, notificationRecipients } from './preferences.js';
+/**
+ * The two messages a comment sets off, and the rules about who gets them.
+ *
+ * Both go through the mail service and nothing else (TASK-53), so a site with
+ * no provider sends nothing and every path through here still works. Neither
+ * is awaited by the request that caused it: a comment is stored, a page is
+ * redirected to, and the message goes out behind that.
+ *
+ * **The moderation notice.** A comment or a webmention has entered the queue,
+ * so everyone who has an address and has not turned the notice off is told,
+ * with the words themselves and three signed links that approve, file as spam
+ * or delete it without a login. It goes out for `pending` and nothing else,
+ * which is the whole of the "not for spam" rule: a comment Akismet filed as
+ * spam is nobody's decision to make today, and one it said to discard was
+ * never stored at all.
+ *
+ * **The reply notice.** Somebody ticked "tell me about replies" when they
+ * commented, and a reply to that comment has just been approved. That is the
+ * only moment it goes: an unapproved reply is not something a stranger should
+ * be emailed the text of, and a moderator should be able to delete a nasty one
+ * before anybody hears about it.
+ *
+ * Three things stop it. The address is missing, the address has unsubscribed,
+ * or the reply is by the very person who would be told — nobody needs an email
+ * about their own words.
+ */
+/** The message an admin gets when something is waiting. */
+export const COMMENT_PENDING_TEMPLATE = 'comment-pending';
+/** The message a commenter gets when a reply to them is approved. */
+export const COMMENT_REPLY_TEMPLATE = 'comment-reply';
+/** The event name the users screen switches, from the registry. */
+export const COMMENTS_NOTIFICATION = 'comments';
+/** Build the notifier for one site. */
+export function createCommentNotifier(options) {
+    const { admin, store, mail, config } = options;
+    /** The post a comment is on, as a message names it. */
+    function postOf(comment) {
+        const document = store.getBySlug(comment.slug);
+        return {
+            title: document?.title ?? comment.slug,
+            url: absolute(comment.permalink, config.baseUrl),
+        };
+    }
+    /** What a message says about the comment itself. */
+    function commentIn(comment) {
+        return {
+            author: comment.author.name,
+            // The website they gave, which is a thing a moderator judges a comment
+            // by. Never their email: the message goes to a moderator, but it also
+            // goes through a third party's servers, and the address is not needed to
+            // decide anything.
+            website: comment.author.url,
+            source: comment.source,
+            kind: comment.kind,
+            text: comment.content.markdown,
+            html: comment.content.html,
+            submitted: comment.submitted,
+            // Where it came from, for a webmention: the page that linked here.
+            url: comment.url,
+        };
+    }
+    return {
+        pending(comment) {
+            if (comment.status !== 'pending')
+                return;
+            // Asked before anything else, so a site that sends no mail never mints a
+            // signing secret it would have no use for.
+            if (!mail.configured())
+                return;
+            // Everybody who wants the notice as it happens. A user on an hourly or
+            // daily digest is deliberately not written to here: the whole of what
+            // choosing a window means is that this moment is not one of the moments
+            // they hear about (TASK-60), and `createCommentDigest` writes to them
+            // instead, from the queue as it stands when their window comes up.
+            const recipients = notificationRecipients(listUsers(config.dataDir), COMMENTS_NOTIFICATION).filter((recipient) => !isBatchedMode(notificationMode(recipient.user, COMMENTS_NOTIFICATION)));
+            if (recipients.length === 0)
+                return;
+            const context = { dataDir: config.dataDir, baseUrl: config.baseUrl, now: config.now() };
+            const actions = MODERATION_ACTIONS.map((action) => ({
+                action,
+                label: action === 'approve' ? 'Approve' : action === 'spam' ? 'Spam' : 'Delete',
+                url: moderationLink(context, comment.id, action),
+            }));
+            const data = {
+                comment: commentIn(comment),
+                post: postOf(comment),
+                actions,
+                queueUrl: absolute('/admin/comments', config.baseUrl),
+            };
+            for (const recipient of recipients) {
+                // One message each rather than one with everybody on it: a moderator's
+                // address is not something to show the other moderators, and a message
+                // per person is what lets a later version say something different to
+                // each of them.
+                void mail.send({ to: recipient.email, template: COMMENT_PENDING_TEMPLATE, data });
+            }
+        },
+        replyApproved(reply) {
+            if (reply.status !== 'approved' || reply.inReplyTo === null)
+                return;
+            if (!mail.configured())
+                return;
+            const parent = admin.getComment(reply.inReplyTo);
+            if (parent === undefined || !parent.notify)
+                return;
+            const address = parent.author.email;
+            if (address === null || address === '')
+                return;
+            // Nobody wants an email about their own reply, and a thread of two
+            // people talking would otherwise send one on every message.
+            if (address.toLowerCase() === (reply.author.email ?? '').toLowerCase())
+                return;
+            if (hasOptedOut(config.dataDir, address))
+                return;
+            const context = { dataDir: config.dataDir, baseUrl: config.baseUrl, now: config.now() };
+            const post = postOf(reply);
+            void mail.send({
+                to: address,
+                template: COMMENT_REPLY_TEMPLATE,
+                data: {
+                    reply: {
+                        ...commentIn(reply),
+                        url: reply.url ?? `${post.url}#${commentAnchor(reply.id)}`,
+                    },
+                    comment: {
+                        ...commentIn(parent),
+                        url: parent.url ?? `${post.url}#${commentAnchor(parent.id)}`,
+                    },
+                    post,
+                    unsubscribeUrl: unsubscribeLink(context, address),
+                },
+            });
+        },
+    };
+}
+/** A site-root path as an absolute URL. */
+function absolute(pathname, baseUrl) {
+    try {
+        return new URL(pathname, baseUrl).href;
+    }
+    catch {
+        return pathname;
+    }
+}
+//# sourceMappingURL=comments.js.map

package/dist/notifications/comments.js.map

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

package/dist/notifications/digest.d.ts

@@ -0,0 +1,135 @@
+import type { AdminStore } from '../admin/store.ts';
+import type { ResolvedConfig } from '../config.ts';
+import type { ContentStore } from '../content/store.ts';
+import type { MailService } from '../mail/service.ts';
+/**
+ * One message a window instead of one message a comment.
+ *
+ * TASK-55 emails every moderator the moment something enters the queue, which
+ * is right for a quiet site and wrong for a spam wave that Akismet let
+ * through. A user who has chosen `hourly` or `daily` on `/admin/users` is sent
+ * nothing when a comment arrives; instead this sends them one message per
+ * window listing everything still waiting, each item with its own approve,
+ * spam and delete links.
+ *
+ * Three decisions hold the whole thing up:
+ *
+ * - **A digest is derived, not queued.** It is built from what
+ *   `admin.listComments({ status: 'pending' })` says right now, so an item
+ *   somebody approved before the run is simply absent and there is no queue to
+ *   keep true across a restart, a crash or a `geekity rebuild`. Nothing has to
+ *   remember what it meant to send.
+ * - **The only new state is when each user was last written to**, and it lives
+ *   in `data/notification-digests.json` rather than in the database, because
+ *   decision-9 says the database may be deleted whenever the site is stopped —
+ *   and a forgotten timestamp would mean either a window silently skipped or a
+ *   digest sent twice. It is its own file rather than a field in
+ *   `data/users.json` because that file is the answer to "who may sign in",
+ *   and a timestamp the sender rewrites every hour is bookkeeping rather than
+ *   anything about the person.
+ * - **Nothing is sent for an empty queue, and an empty run records nothing.**
+ *   A user with nothing waiting is never emailed, and because their timestamp
+ *   does not move, the first thing that does arrive goes out on the very next
+ *   tick rather than waiting out a window that had nothing in it. The promise
+ *   a mode makes is "at most one message per window", and that is kept.
+ */
+/** The message a batched user gets: everything still waiting, in one. */
+export declare const COMMENT_DIGEST_TEMPLATE = "comment-digest";
+/** The file, relative to `dataDir`. */
+export declare const DIGEST_TIMES_FILE = "notification-digests.json";
+/** Nobody but the site's own user reads it. */
+export declare const DIGEST_TIMES_FILE_MODE = 384;
+/**
+ * How often the timer looks.
+ *
+ * A minute. The tick is not the window — each user's own mode decides whether
+ * they are due — so this only sets how promptly a window that has come up is
+ * noticed, and a minute's lag on an hourly digest is nothing while a busier
+ * tick would be a query a minute for no one.
+ */
+export declare const DIGEST_TICK_MS: number;
+/**
+ * The most items one digest lists.
+ *
+ * A cap rather than "everything", because "everything" during a spam wave is a
+ * message with thousands of entries and three signed links each, which no mail
+ * provider would take and nobody could read. What is over the cap is counted
+ * in a line at the bottom pointing at the moderation queue, and the next
+ * window lists the next hundred.
+ */
+export declare const DIGEST_MAX_ITEMS = 100;
+/** Where the digest times live for a given data directory. */
+export declare function digestTimesFile(dataDir: string): string;
+/**
+ * When each user last had a digest of each event, as
+ * `{ [event]: { [userId]: instant } }`.
+ *
+ * Keyed by event as well as by user because the registry may grow a second
+ * batched notice, and the two would then be on windows of their own. A file
+ * that is missing, damaged or the wrong shape reads as nobody having had
+ * anything — the same direction {@link readCommentOptOuts} fails in, and for
+ * the same reason: the cost is a duplicate digest, and the alternative is a
+ * site whose timer throws over a stray comma.
+ */
+export declare function readDigestTimes(dataDir: string): Record<string, Record<string, string>>;
+/**
+ * Write down that these users have just been sent a digest of this event.
+ *
+ * The read is inside the write, so two runs at once cannot lose one another's
+ * timestamps.
+ */
+export declare function recordDigestTimes(dataDir: string, event: string, users: readonly number[], at: Date): Promise<void>;
+/**
+ * The timer the digest waits on, injected so a test can fire it rather than
+ * wait for it. The shape {@link ScheduleTimers} has, for the same reason: a
+ * repeating tick, unreferenced so it never holds the process open on its own.
+ */
+export interface NotificationTimers {
+    set(callback: () => void, everyMs: number): unknown;
+    clear(handle: unknown): void;
+}
+/** The real one. */
+export declare const systemNotificationTimers: NotificationTimers;
+/** Where a digest run reports what it could not do. `console` will do. */
+export interface DigestLogger {
+    warn(message: string): void;
+}
+/** What {@link createCommentDigest} needs. */
+export interface CreateCommentDigestOptions {
+    /** The comment index, which is what "still pending" is asked of. */
+    admin: AdminStore;
+    /** The content index, for the posts the items are on. */
+    store: ContentStore;
+    /** The one door out for email. */
+    mail: MailService;
+    /**
+     * Config after defaults: the base URL the links are absolute against, the
+     * data directory the signing secret and the record live in, and the clock.
+     */
+    config: Pick<ResolvedConfig, 'baseUrl' | 'dataDir' | 'now'>;
+    /** The timer to tick on. Defaults to {@link systemNotificationTimers}. */
+    timers?: NotificationTimers | undefined;
+    /** How often it ticks. Defaults to {@link DIGEST_TICK_MS}. */
+    tickMs?: number | undefined;
+    /** The most items one message lists. Defaults to {@link DIGEST_MAX_ITEMS}. */
+    maxItems?: number | undefined;
+    /** Where failures are reported. Defaults to `console`. */
+    logger?: DigestLogger | undefined;
+}
+/** Sends the batched notices. Never throws, and never waits on a provider. */
+export interface CommentDigest {
+    /**
+     * Send a digest to every user who is due one and has something waiting.
+     * Resolves with how many messages were handed to the mail service.
+     */
+    run(): Promise<number>;
+    /** Start ticking. Safe twice. */
+    start(): void;
+    /** Stop ticking. Safe before starting and safe twice. */
+    stop(): void;
+    /** Resolve once the run in flight, if there is one, has finished. */
+    settled(): Promise<void>;
+}
+/** Build the digest sender for one site. */
+export declare function createCommentDigest(options: CreateCommentDigestOptions): CommentDigest;
+//# sourceMappingURL=digest.d.ts.map

package/dist/notifications/digest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"digest.d.ts","sourceRoot":"","sources":["../../src/notifications/digest.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,UAAU,EAAe,MAAM,mBAAmB,CAAC;AACjE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AACnD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACxD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAUtD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,yEAAyE;AACzE,eAAO,MAAM,uBAAuB,mBAAmB,CAAC;AAExD,uCAAuC;AACvC,eAAO,MAAM,iBAAiB,8BAA8B,CAAC;AAE7D,+CAA+C;AAC/C,eAAO,MAAM,sBAAsB,MAAQ,CAAC;AAE5C;;;;;;;GAOG;AACH,eAAO,MAAM,cAAc,QAAY,CAAC;AAExC;;;;;;;;GAQG;AACH,eAAO,MAAM,gBAAgB,MAAM,CAAC;AAEpC,8DAA8D;AAC9D,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAEvD;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAEvF;AAED;;;;;GAKG;AACH,wBAAsB,iBAAiB,CACrC,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,SAAS,MAAM,EAAE,EACxB,EAAE,EAAE,IAAI,GACP,OAAO,CAAC,IAAI,CAAC,CAaf;AAED;;;;GAIG;AACH,MAAM,WAAW,kBAAkB;IACjC,GAAG,CAAC,QAAQ,EAAE,MAAM,IAAI,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC;IACpD,KAAK,CAAC,MAAM,EAAE,OAAO,GAAG,IAAI,CAAC;CAC9B;AAED,oBAAoB;AACpB,eAAO,MAAM,wBAAwB,EAAE,kBAStC,CAAC;AAEF,0EAA0E;AAC1E,MAAM,WAAW,YAAY;IAC3B,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;CAC7B;AAED,8CAA8C;AAC9C,MAAM,WAAW,0BAA0B;IACzC,oEAAoE;IACpE,KAAK,EAAE,UAAU,CAAC;IAClB,yDAAyD;IACzD,KAAK,EAAE,YAAY,CAAC;IACpB,kCAAkC;IAClC,IAAI,EAAE,WAAW,CAAC;IAClB;;;OAGG;IACH,MAAM,EAAE,IAAI,CAAC,cAAc,EAAE,SAAS,GAAG,SAAS,GAAG,KAAK,CAAC,CAAC;IAC5D,0EAA0E;IAC1E,MAAM,CAAC,EAAE,kBAAkB,GAAG,SAAS,CAAC;IACxC,8DAA8D;IAC9D,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC5B,8EAA8E;IAC9E,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC9B,0DAA0D;IAC1D,MAAM,CAAC,EAAE,YAAY,GAAG,SAAS,CAAC;CACnC;AAED,8EAA8E;AAC9E,MAAM,WAAW,aAAa;IAC5B;;;OAGG;IACH,GAAG,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC;IACvB,iCAAiC;IACjC,KAAK,IAAI,IAAI,CAAC;IACd,yDAAyD;IACzD,IAAI,IAAI,IAAI,CAAC;IACb,qEAAqE;IACrE,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC1B;AAED,4CAA4C;AAC5C,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,0BAA0B,GAAG,aAAa,CA0ItF"}