@kernhq/module-quire 0.13.1 → 0.15.0

package/dist/server/services/index.d.ts

@@ -1,11 +1,15 @@
-import type { Kernel } from '@kernhq/kernel';
+import type { JobDef, Kernel } from '@kernhq/kernel';
 import { quireAccess } from './access.js';
 import { quireComments } from './comments.js';
 import { quireDatabases } from './databases.js';
+import { quireExport } from './export.js';
+import { quireImport } from './import.js';
+import { quireMacros } from './macros.js';
 import { quireOrganisation } from './organisation.js';
 import { quirePages } from './pages.js';
 import { quirePublications } from './publications.js';
 import { quireSpaces } from './spaces.js';
+import { quireTemplates } from './templates.js';
 import { quireVersions } from './versions.js';
 export interface QuireServices {
     access: ReturnType<typeof quireAccess>;
@@ -16,17 +20,44 @@ export interface QuireServices {
     databases: ReturnType<typeof quireDatabases>;
     organisation: ReturnType<typeof quireOrganisation>;
     publications: ReturnType<typeof quirePublications>;
+    exports: ReturnType<typeof quireExport>;
+    imports: ReturnType<typeof quireImport>;
+    templates: ReturnType<typeof quireTemplates>;
+    macros: ReturnType<typeof quireMacros>;
 }
 /** One set of services per kernel: they are stateless, and rebuilding them per request is waste. */
 export declare function quireServices(kernel: Kernel): QuireServices;
+/**
+ * The background work this module hands to a worker process, gathered here rather than in
+ * `index.ts`.
+ *
+ * One line in the module definition, so adding a job is an edit to this file and not to the file
+ * every other part of the module is also editing. The names reach pg-boss as `quire.<name>` — the
+ * kernel prefixes them — and only a process started with a worker role runs them; an API process
+ * registers nothing and merely sends.
+ *
+ * `retryLimit` is deliberately small. An export that fails for a reason of its own — Gotenberg is
+ * not running, a page will not render — records that reason on its row and returns *successfully*,
+ * because it has finished: it failed, and it said so, and repeating it would only write the same
+ * sentence three more times. A throw out of the handler means something underneath went wrong
+ * (the database, the broker), which is the case a retry is for.
+ */
+export declare const quireJobs: JobDef<{
+    workspaceId: string;
+    jobId: string;
+}>[];
 export * from './access.js';
 export * from './comments.js';
 export * from './databases.js';
+export * from './export.js';
+export * from './import.js';
+export * from './macros.js';
 export * from './organisation.js';
 export * from './pages.js';
 export * from './publications.js';
 /** The public surface resolves a workspace slug before anything touches the schema. */
 export { resolveWorkspaceSegment } from './publications.js';
 export * from './spaces.js';
+export * from './templates.js';
 export * from './versions.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/server/services/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/server/services/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,gBAAgB,CAAA;AAC5C,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAA;AACzC,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAA;AAC7C,OAAO,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAA;AAC/C,OAAO,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAA;AACrD,OAAO,EAAE,UAAU,EAAE,MAAM,YAAY,CAAA;AACvC,OAAO,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAA;AACrD,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAA;AACzC,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAA;AAE7C,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,UAAU,CAAC,OAAO,WAAW,CAAC,CAAA;IACtC,MAAM,EAAE,UAAU,CAAC,OAAO,WAAW,CAAC,CAAA;IACtC,KAAK,EAAE,UAAU,CAAC,OAAO,UAAU,CAAC,CAAA;IACpC,QAAQ,EAAE,UAAU,CAAC,OAAO,aAAa,CAAC,CAAA;IAC1C,QAAQ,EAAE,UAAU,CAAC,OAAO,aAAa,CAAC,CAAA;IAC1C,SAAS,EAAE,UAAU,CAAC,OAAO,cAAc,CAAC,CAAA;IAC5C,YAAY,EAAE,UAAU,CAAC,OAAO,iBAAiB,CAAC,CAAA;IAClD,YAAY,EAAE,UAAU,CAAC,OAAO,iBAAiB,CAAC,CAAA;CACnD;AAID,oGAAoG;AACpG,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,aAAa,CAiB3D;AAED,cAAc,aAAa,CAAA;AAC3B,cAAc,eAAe,CAAA;AAC7B,cAAc,gBAAgB,CAAA;AAC9B,cAAc,mBAAmB,CAAA;AACjC,cAAc,YAAY,CAAA;AAC1B,cAAc,mBAAmB,CAAA;AACjC,uFAAuF;AACvF,OAAO,EAAE,uBAAuB,EAAE,MAAM,mBAAmB,CAAA;AAC3D,cAAc,aAAa,CAAA;AAC3B,cAAc,eAAe,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/server/services/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,gBAAgB,CAAA;AAEpD,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAA;AACzC,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAA;AAC7C,OAAO,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAA;AAC/C,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAA;AACzC,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAA;AACzC,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAA;AACzC,OAAO,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAA;AACrD,OAAO,EAAE,UAAU,EAAE,MAAM,YAAY,CAAA;AACvC,OAAO,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAA;AACrD,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAA;AACzC,OAAO,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAA;AAC/C,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAA;AAE7C,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,UAAU,CAAC,OAAO,WAAW,CAAC,CAAA;IACtC,MAAM,EAAE,UAAU,CAAC,OAAO,WAAW,CAAC,CAAA;IACtC,KAAK,EAAE,UAAU,CAAC,OAAO,UAAU,CAAC,CAAA;IACpC,QAAQ,EAAE,UAAU,CAAC,OAAO,aAAa,CAAC,CAAA;IAC1C,QAAQ,EAAE,UAAU,CAAC,OAAO,aAAa,CAAC,CAAA;IAC1C,SAAS,EAAE,UAAU,CAAC,OAAO,cAAc,CAAC,CAAA;IAC5C,YAAY,EAAE,UAAU,CAAC,OAAO,iBAAiB,CAAC,CAAA;IAClD,YAAY,EAAE,UAAU,CAAC,OAAO,iBAAiB,CAAC,CAAA;IAClD,OAAO,EAAE,UAAU,CAAC,OAAO,WAAW,CAAC,CAAA;IACvC,OAAO,EAAE,UAAU,CAAC,OAAO,WAAW,CAAC,CAAA;IACvC,SAAS,EAAE,UAAU,CAAC,OAAO,cAAc,CAAC,CAAA;IAC5C,MAAM,EAAE,UAAU,CAAC,OAAO,WAAW,CAAC,CAAA;CACvC;AAID,oGAAoG;AACpG,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,aAAa,CA0C3D;AAED;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,SAAS,EAAE,MAAM,CAAC;IAAE,WAAW,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC,EAiCrE,CAAA;AAED,cAAc,aAAa,CAAA;AAC3B,cAAc,eAAe,CAAA;AAC7B,cAAc,gBAAgB,CAAA;AAC9B,cAAc,aAAa,CAAA;AAC3B,cAAc,aAAa,CAAA;AAC3B,cAAc,aAAa,CAAA;AAC3B,cAAc,mBAAmB,CAAA;AACjC,cAAc,YAAY,CAAA;AAC1B,cAAc,mBAAmB,CAAA;AACjC,uFAAuF;AACvF,OAAO,EAAE,uBAAuB,EAAE,MAAM,mBAAmB,CAAA;AAC3D,cAAc,aAAa,CAAA;AAC3B,cAAc,gBAAgB,CAAA;AAC9B,cAAc,eAAe,CAAA"}

package/dist/server/services/index.js

@@ -1,10 +1,15 @@
+import { z } from 'zod';
 import { quireAccess } from './access.js';
 import { quireComments } from './comments.js';
 import { quireDatabases } from './databases.js';
+import { quireExport } from './export.js';
+import { quireImport } from './import.js';
+import { quireMacros } from './macros.js';
 import { quireOrganisation } from './organisation.js';
 import { quirePages } from './pages.js';
 import { quirePublications } from './publications.js';
 import { quireSpaces } from './spaces.js';
+import { quireTemplates } from './templates.js';
 import { quireVersions } from './versions.js';
 const cache = new WeakMap();
 /** One set of services per kernel: they are stateless, and rebuilding them per request is waste. */
@@ -14,27 +19,105 @@ export function quireServices(kernel) {
         return existing;
     const access = quireAccess(kernel);
     const versions = quireVersions(kernel, access);
+    // An import writes pages *and* databases, so it is the one service built on another one: it needs
+    // `databases` to mint the properties whose keys its rows are keyed by. See `import.ts`'s `write`.
+    const databases = quireDatabases(kernel, access);
+    /*
+     * Templates make pages and spaces, so they are built on the two services that already know how —
+     * a second implementation of "create a page" would be a second fractional-index algorithm, and two
+     * orderings of one tree is a sidebar that disagrees with itself.
+     */
+    const spaces = quireSpaces(access);
+    const pages = quirePages(access);
+    /*
+     * Built before `publications`, which needs it: a published page's HTML is rendered on the public
+     * path, and a macro inside it has to resolve there too — against the publication rather than
+     * against a reader, because on that path there is no reader at all.
+     */
+    const macros = quireMacros(kernel, access);
     const services = {
         access,
-        spaces: quireSpaces(access),
-        pages: quirePages(access),
+        spaces,
+        pages,
         versions,
         comments: quireComments(access),
-        databases: quireDatabases(kernel, access),
+        databases,
         organisation: quireOrganisation(access),
-        publications: quirePublications(kernel, access, versions),
+        publications: quirePublications(kernel, access, versions, macros),
+        exports: quireExport(kernel, access),
+        imports: quireImport(kernel, access, databases),
+        templates: quireTemplates(kernel, access, pages, spaces),
+        /*
+         * Macros resolve *reads* against whoever is reading, so this service has `access` and nothing
+         * that writes. It is deliberately not built on `pages`: a macro must never reach a procedure
+         * that answers for the caller rather than for the reader.
+         */
+        macros,
     };
     cache.set(kernel, services);
     return services;
 }
+/**
+ * The background work this module hands to a worker process, gathered here rather than in
+ * `index.ts`.
+ *
+ * One line in the module definition, so adding a job is an edit to this file and not to the file
+ * every other part of the module is also editing. The names reach pg-boss as `quire.<name>` — the
+ * kernel prefixes them — and only a process started with a worker role runs them; an API process
+ * registers nothing and merely sends.
+ *
+ * `retryLimit` is deliberately small. An export that fails for a reason of its own — Gotenberg is
+ * not running, a page will not render — records that reason on its row and returns *successfully*,
+ * because it has finished: it failed, and it said so, and repeating it would only write the same
+ * sentence three more times. A throw out of the handler means something underneath went wrong
+ * (the database, the broker), which is the case a retry is for.
+ */
+export const quireJobs = [
+    {
+        name: 'export',
+        schema: z.object({ workspaceId: z.uuid(), jobId: z.uuid() }),
+        handler: async (input, { kernel }) => {
+            await quireServices(kernel).exports.run(input.workspaceId, input.jobId);
+        },
+        options: { retryLimit: 2, retryDelay: 30, expireInSeconds: 900 },
+    },
+    /**
+     * An import, with **no retries at all** — the one place in this module where that is the safe
+     * setting rather than the timid one.
+     *
+     * `run` is idempotent against its own row (`done` and `failed` are terminal, and it claims the row
+     * before it does anything), so a retry after a *completed* run is a no-op. What a retry cannot be
+     * safe against is the case pg-boss actually retries: a handler that threw. An import commits its
+     * pages and its finished row in one transaction, so a throw means nothing was written — but a
+     * *lost connection after the commit* looks exactly the same from here, and running it again would
+     * write every page in the archive a second time. Two hundred duplicate pages in somebody's space
+     * is a worse outcome than a job that says it failed and can be started again by a person who can
+     * see what is in the space.
+     *
+     * The window is longer than an export's for the obvious reason: reading a few hundred megabytes of
+     * zip and writing four thousand rows is not a fifteen-minute job on a busy instance.
+     */
+    {
+        name: 'import',
+        schema: z.object({ workspaceId: z.uuid(), jobId: z.uuid() }),
+        handler: async (input, { kernel }) => {
+            await quireServices(kernel).imports.run(input.workspaceId, input.jobId);
+        },
+        options: { retryLimit: 0, expireInSeconds: 3600 },
+    },
+];
 export * from './access.js';
 export * from './comments.js';
 export * from './databases.js';
+export * from './export.js';
+export * from './import.js';
+export * from './macros.js';
 export * from './organisation.js';
 export * from './pages.js';
 export * from './publications.js';
 /** The public surface resolves a workspace slug before anything touches the schema. */
 export { resolveWorkspaceSegment } from './publications.js';
 export * from './spaces.js';
+export * from './templates.js';
 export * from './versions.js';
 //# sourceMappingURL=index.js.map

package/dist/server/services/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/server/services/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAA;AACzC,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAA;AAC7C,OAAO,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAA;AAC/C,OAAO,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAA;AACrD,OAAO,EAAE,UAAU,EAAE,MAAM,YAAY,CAAA;AACvC,OAAO,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAA;AACrD,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAA;AACzC,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAA;AAa7C,MAAM,KAAK,GAAG,IAAI,OAAO,EAAyB,CAAA;AAElD,oGAAoG;AACpG,MAAM,UAAU,aAAa,CAAC,MAAc;IAC1C,MAAM,QAAQ,GAAG,KAAK,CAAC,GAAG,CAAC,MAAM,CAAC,CAAA;IAClC,IAAI,QAAQ;QAAE,OAAO,QAAQ,CAAA;IAC7B,MAAM,MAAM,GAAG,WAAW,CAAC,MAAM,CAAC,CAAA;IAClC,MAAM,QAAQ,GAAG,aAAa,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAC9C,MAAM,QAAQ,GAAkB;QAC9B,MAAM;QACN,MAAM,EAAE,WAAW,CAAC,MAAM,CAAC;QAC3B,KAAK,EAAE,UAAU,CAAC,MAAM,CAAC;QACzB,QAAQ;QACR,QAAQ,EAAE,aAAa,CAAC,MAAM,CAAC;QAC/B,SAAS,EAAE,cAAc,CAAC,MAAM,EAAE,MAAM,CAAC;QACzC,YAAY,EAAE,iBAAiB,CAAC,MAAM,CAAC;QACvC,YAAY,EAAE,iBAAiB,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,CAAC;KAC1D,CAAA;IACD,KAAK,CAAC,GAAG,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAA;IAC3B,OAAO,QAAQ,CAAA;AACjB,CAAC;AAED,cAAc,aAAa,CAAA;AAC3B,cAAc,eAAe,CAAA;AAC7B,cAAc,gBAAgB,CAAA;AAC9B,cAAc,mBAAmB,CAAA;AACjC,cAAc,YAAY,CAAA;AAC1B,cAAc,mBAAmB,CAAA;AACjC,uFAAuF;AACvF,OAAO,EAAE,uBAAuB,EAAE,MAAM,mBAAmB,CAAA;AAC3D,cAAc,aAAa,CAAA;AAC3B,cAAc,eAAe,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/server/services/index.ts"],"names":[],"mappings":"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"}

package/dist/server/services/macros.d.ts

@@ -0,0 +1,83 @@
+/**
+ * What a macro is allowed to say, to the person actually reading.
+ *
+ * Five of the eight macros draw pages that are not in the document — `pageChildren`,
+ * `excerptInclude`, `includePage`, `recentlyUpdated` and `contributors`. Everything about them that
+ * matters is in this file, because this is the only place that decides *which* pages, and the
+ * decision is the feature's whole risk: a children macro that forgets its filter still compiles,
+ * still renders, and looks right to the author, because the author can read everything on it.
+ *
+ * The rule, in three parts, and `macros.int.test.ts` holds all three:
+ *
+ *   1. **The renderer never reads a database.** `renderPageDoc` draws a reading macro only from a
+ *      `MacroResolver` it was handed. With none — which is what every caller written before this
+ *      feature passes, the exporters and the publish-time render included — a reading macro draws
+ *      its frame and nothing else. Fail-closed is the default rather than a branch to remember.
+ *   2. **A signed-in reader sees exactly what they could open.** Every page named here is asked
+ *      about with `quire.page.view` at *page* scope, so a DENY bound to one page removes it.
+ *   3. **A published site has no reader, so the publication is the audience.** The set of publicly
+ *      reachable pages — which `publications.walk` already computes, root first and pruned — is the
+ *      whole of what exists. Anything outside it is not drawn as a title with a dead link; it is
+ *      not drawn.
+ *
+ * Two structural choices follow from that and are worth stating rather than leaving to be inferred.
+ *
+ * **Resolution is a pass, not a per-node lookup.** `macrosIn` collects the reading macros in a
+ * document and de-duplicates them by their attributes, this file answers them against one audience,
+ * and `renderPageDoc` reads the answers out of a map. The alternative — resolving inside the
+ * renderer — is a database round trip per macro in render order, on a request that is otherwise two
+ * queries, and it would make the renderer async for every caller that has no macros at all.
+ *
+ * **A prune is not a filter.** Where a page is not visible, its descendants go with it. Removing a
+ * page from a children list and then listing its children anyway would name every page under it to
+ * whoever guessed there was something there, which is exactly the shape `publications.ts`'s walk
+ * exists to avoid — and the reason that walk prunes is the reason this one does.
+ */
+import type { Principal } from '@kernhq/contracts';
+import type { Kernel, Tx } from '@kernhq/kernel';
+import { type PageDoc } from '@kernhq/ui/editor/page-doc';
+import { type MacroResolver } from '../render.js';
+import type { QuireAccess } from './access.js';
+/**
+ * Who is being drawn for.
+ *
+ * A discriminated union with exactly two members, and there is deliberately no third: a caller
+ * cannot express "resolve this for nobody in particular", because that is the shape that leaks. A
+ * caller with no audience passes no resolver at all, and the renderer draws empty frames.
+ */
+export type MacroAudience = {
+    kind: 'reader';
+    principal: Principal;
+}
+/**
+ * The publicly reachable pages, as `publications.walk` computed them for *this* publication.
+ * A set rather than a publication id, so this file cannot disagree with the walk about what
+ * "public" means — there is only one definition of it and it is not here.
+ */
+ | {
+    kind: 'publication';
+    pageIds: ReadonlySet<string>;
+};
+export interface MacroContext {
+    /** The page the document belongs to. `null` for a render with no page — a preview, an import. */
+    pageId: string | null;
+    /** Where to send a reader for a page id, if this render has addresses at all. */
+    pageHref?: (pageId: string) => string | null;
+    /** For the dates a list macro draws. `principal.locale` for a reader; the site's for a publication. */
+    locale?: string | null;
+}
+export declare function quireMacros(kernel: Kernel, access: QuireAccess): {
+    /**
+     * Answer every reading macro in a document, for one audience, in one pass.
+     *
+     * Returns the synchronous lookup `renderPageDoc` takes. A macro this could not answer — a page
+     * that was deleted, a page the audience may not see, a lookup that failed — is simply absent
+     * from the map, and an absent answer is the empty frame. There is no path through this function
+     * that returns a page the audience failed the gate on, and no way to express one: `visible` is
+     * the only thing that builds a `MacroPageRef`'s input, and every caller of `refOf` has just
+     * awaited it.
+     */
+    resolve(tx: Tx, workspaceId: string, doc: PageDoc | null | undefined, audience: MacroAudience, ctx: MacroContext): Promise<MacroResolver>;
+};
+export type QuireMacros = ReturnType<typeof quireMacros>;
+//# sourceMappingURL=macros.d.ts.map

package/dist/server/services/macros.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"macros.d.ts","sourceRoot":"","sources":["../../../src/server/services/macros.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAA;AAClD,OAAO,KAAK,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,gBAAgB,CAAA;AAChD,OAAO,EAGL,KAAK,OAAO,EAEb,MAAM,4BAA4B,CAAA;AAGnC,OAAO,EAGL,KAAK,aAAa,EAKnB,MAAM,cAAc,CAAA;AAErB,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAA;AAG9C;;;;;;GAMG;AACH,MAAM,MAAM,aAAa,GACrB;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,SAAS,EAAE,SAAS,CAAA;CAAE;AAC1C;;;;GAIG;GACD;IAAE,IAAI,EAAE,aAAa,CAAC;IAAC,OAAO,EAAE,WAAW,CAAC,MAAM,CAAC,CAAA;CAAE,CAAA;AAEzD,MAAM,WAAW,YAAY;IAC3B,iGAAiG;IACjG,MAAM,EAAE,MAAM,GAAG,IAAI,CAAA;IACrB,iFAAiF;IACjF,QAAQ,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,MAAM,GAAG,IAAI,CAAA;IAC5C,uGAAuG;IACvG,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;CACvB;AA6GD,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW;IAgV3D;;;;;;;;;OASG;gBAEG,EAAE,eACO,MAAM,OACd,OAAO,GAAG,IAAI,GAAG,SAAS,YACrB,aAAa,OAClB,YAAY,GAChB,OAAO,CAAC,aAAa,CAAC;EA0H5B;AAED,MAAM,MAAM,WAAW,GAAG,UAAU,CAAC,OAAO,WAAW,CAAC,CAAA"}